@lossless.org/client 0.1.0

package/dist_ts/nosqldb/classes.session.js

@@ -0,0 +1,246 @@
+import * as plugins from './plugins.js';
+import { SmartdataPersistenceError, normalizeOrdinaryPersistenceError, } from './classes.persistence.js';
+const bindings = new WeakMap();
+const bindingsByOwner = new WeakMap();
+const smartdataSessionInvalidationAggregateBrand = Symbol('smartdataSessionInvalidationAggregate');
+class SmartdataSessionInvalidationAggregateError extends AggregateError {
+    [smartdataSessionInvalidationAggregateBrand] = true;
+}
+const transactionContext = new plugins.nodeAsyncHooks.AsyncLocalStorage();
+const resolveBinding = (sessionArg, ownerArg) => {
+    const binding = bindings.get(sessionArg);
+    if (!binding || binding.invalidated || binding.rawSession.hasEnded) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'The SmartData session has ended or is no longer valid.');
+    }
+    if (ownerArg && binding.owner !== ownerArg) {
+        throw new SmartdataPersistenceError('invalid_argument', 'The SmartData session belongs to another database.');
+    }
+    if (binding.owner.status !== 'connected'
+        || binding.owner.mongoDbClient !== binding.client) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'The SmartData session belongs to a stale database lifecycle.');
+    }
+    return binding;
+};
+const assertTransactionSucceeded = (bindingArg) => {
+    if (bindingArg.transactionFailure) {
+        throw bindingArg.transactionFailure.error;
+    }
+};
+export class SmartdataSession {
+    async withTransaction(callbackArg) {
+        if (typeof callbackArg !== 'function') {
+            throw new SmartdataPersistenceError('invalid_argument', 'SmartData transaction callback must be a function.');
+        }
+        const binding = resolveBinding(this);
+        if (binding.operationActive || binding.transactionActive) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'Parallel or nested SmartData session operations are not supported.');
+        }
+        binding.transactionActive = true;
+        let callbackError;
+        try {
+            return await binding.rawSession.withTransaction(async () => {
+                const attempt = Symbol('smartdataTransactionAttempt');
+                binding.transactionAttempt = attempt;
+                binding.transactionCallbackOpen = true;
+                binding.transactionUsesOrdinaryWrite = false;
+                binding.transactionFailure = undefined;
+                callbackError = undefined;
+                try {
+                    let callbackReturned = false;
+                    try {
+                        const result = await transactionContext.run({ contextToken: binding.contextToken, attempt }, async () => callbackArg(this));
+                        callbackReturned = true;
+                        return result;
+                    }
+                    finally {
+                        const activeOperation = binding.operationActive
+                            ? binding.operationSettled
+                            : undefined;
+                        binding.transactionCallbackOpen = false;
+                        if (binding.transactionAttempt === attempt) {
+                            binding.transactionAttempt = undefined;
+                        }
+                        if (activeOperation) {
+                            await activeOperation;
+                        }
+                        assertTransactionSucceeded(binding);
+                        if (callbackReturned && activeOperation) {
+                            throw new SmartdataPersistenceError('unsupported_operation', 'A SmartData transaction callback returned with an operation still active.');
+                        }
+                    }
+                }
+                catch (errorArg) {
+                    callbackError = errorArg;
+                    throw errorArg;
+                }
+            });
+        }
+        catch (errorArg) {
+            if (errorArg === callbackError) {
+                throw errorArg;
+            }
+            if (binding.transactionUsesOrdinaryWrite) {
+                return normalizeOrdinaryPersistenceError(errorArg, 'SmartData transaction conflicts with a unique index.');
+            }
+            throw errorArg;
+        }
+        finally {
+            binding.transactionActive = false;
+            binding.transactionUsesOrdinaryWrite = false;
+            binding.transactionFailure = undefined;
+        }
+    }
+    async close() {
+        const binding = bindings.get(this);
+        if (!binding) {
+            return;
+        }
+        if (binding.operationActive || binding.transactionActive) {
+            throw new SmartdataPersistenceError('unsupported_operation', 'Cannot close a SmartData session while an operation is active.');
+        }
+        await closeSessionBinding(binding);
+    }
+}
+export const createSmartdataSession = (ownerArg) => {
+    if (ownerArg.status !== 'connected' || !ownerArg.mongoDbClient) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'Cannot create a SmartData session before the database is connected.');
+    }
+    const session = new SmartdataSession();
+    const binding = {
+        session,
+        contextToken: Symbol('smartdataSessionContext'),
+        owner: ownerArg,
+        client: ownerArg.mongoDbClient,
+        rawSession: ownerArg.mongoDbClient.startSession(),
+        operationActive: false,
+        transactionActive: false,
+        transactionCallbackOpen: false,
+        transactionUsesOrdinaryWrite: false,
+        invalidated: false,
+    };
+    bindings.set(session, binding);
+    let ownerBindings = bindingsByOwner.get(ownerArg);
+    if (!ownerBindings) {
+        ownerBindings = new Set();
+        bindingsByOwner.set(ownerArg, ownerBindings);
+    }
+    ownerBindings.add(binding);
+    return session;
+};
+export const acquireSmartdataSession = (sessionArg, ownerArg, optionsArg = {}) => {
+    const binding = resolveBinding(sessionArg, ownerArg);
+    if (binding.transactionFailure) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'The SmartData transaction attempt has aborted and cannot accept further operations.');
+    }
+    const currentContext = transactionContext.getStore();
+    const isOwnedTransactionContext = currentContext?.contextToken === binding.contextToken;
+    if (binding.operationActive
+        || (binding.transactionActive
+            && (!binding.transactionCallbackOpen
+                || !isOwnedTransactionContext
+                || currentContext.attempt !== binding.transactionAttempt))
+        || (!binding.transactionActive && isOwnedTransactionContext)) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'Parallel SmartData session operations are not supported.');
+    }
+    if (optionsArg.ordinaryWrite && binding.transactionActive) {
+        binding.transactionUsesOrdinaryWrite = true;
+    }
+    binding.operationActive = true;
+    binding.operationSettled = new Promise((resolveArg) => {
+        binding.resolveOperationSettled = resolveArg;
+    });
+    let released = false;
+    return {
+        rawSession: binding.rawSession,
+        release: () => {
+            if (!released) {
+                released = true;
+                binding.operationActive = false;
+                binding.resolveOperationSettled?.();
+                binding.operationSettled = undefined;
+                binding.resolveOperationSettled = undefined;
+            }
+        },
+    };
+};
+/** Marks the current owned attempt for rollback by withTransaction. */
+export const failSmartdataTransaction = (sessionArg, ownerArg, errorArg) => {
+    const binding = resolveBinding(sessionArg, ownerArg);
+    const context = transactionContext.getStore();
+    if (!binding.operationActive
+        || !binding.transactionActive
+        || context?.contextToken !== binding.contextToken
+        || context.attempt !== binding.transactionAttempt) {
+        throw new SmartdataPersistenceError('unsupported_operation', 'Only the active owned operation can abort a SmartData transaction attempt.');
+    }
+    binding.transactionFailure ??= { error: errorArg };
+    throw binding.transactionFailure.error;
+};
+export const isSmartdataSession = (sessionArg) => sessionArg instanceof SmartdataSession;
+export const isOrdinarySessionInTransaction = (sessionArg) => {
+    if (!sessionArg) {
+        return false;
+    }
+    if (isSmartdataSession(sessionArg)) {
+        return resolveBinding(sessionArg).transactionActive;
+    }
+    return sessionArg.inTransaction();
+};
+export const runWithOrdinarySmartdataSession = async (sessionArg, ownerArg, optionsArg, operationArg) => {
+    if (!isSmartdataSession(sessionArg)) {
+        return operationArg(sessionArg);
+    }
+    if (!optionsArg.prepared) {
+        throw new SmartdataPersistenceError('unsupported_operation', optionsArg.preparationMessage ||
+            'Initialize every participating SmartData model before using an owned session.');
+    }
+    const lease = acquireSmartdataSession(sessionArg, ownerArg, {
+        ordinaryWrite: optionsArg.ordinaryWrite,
+    });
+    try {
+        return await operationArg(lease.rawSession);
+    }
+    finally {
+        lease.release();
+    }
+};
+export const invalidateSmartdataSessions = async (ownerArg) => {
+    const ownerBindings = bindingsByOwner.get(ownerArg);
+    if (!ownerBindings) {
+        return;
+    }
+    const sessions = [...ownerBindings];
+    for (const bindingArg of sessions) {
+        bindingArg.invalidated = true;
+    }
+    const results = await Promise.allSettled(sessions.map((bindingArg) => closeSessionBinding(bindingArg)));
+    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason] : []);
+    if (errors.length === 1) {
+        throw errors[0];
+    }
+    if (errors.length > 1) {
+        throw new SmartdataSessionInvalidationAggregateError(errors, 'Multiple SmartData sessions failed to close.');
+    }
+};
+/** Failed cleanup remains owned and invalidated until an explicit retry succeeds. */
+const closeSessionBinding = async (bindingArg) => {
+    if (bindingArg.closing)
+        return bindingArg.closing;
+    bindingArg.invalidated = true;
+    const closing = Promise.resolve().then(async () => {
+        await bindingArg.rawSession.endSession();
+        bindingsByOwner.get(bindingArg.owner)?.delete(bindingArg);
+        bindings.delete(bindingArg.session);
+    });
+    bindingArg.closing = closing;
+    try {
+        await closing;
+    }
+    finally {
+        bindingArg.closing = undefined;
+    }
+};
+export const unwrapSmartdataSessionInvalidationErrors = (errorArg) => errorArg instanceof SmartdataSessionInvalidationAggregateError
+    ? errorArg.errors
+    : undefined;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zZXNzaW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvbm9zcWxkYi9jbGFzc2VzLnNlc3Npb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFHeEMsT0FBTyxFQUNMLHlCQUF5QixFQUN6QixpQ0FBaUMsR0FDbEMsTUFBTSwwQkFBMEIsQ0FBQztBQW9CbEMsTUFBTSxRQUFRLEdBQUcsSUFBSSxPQUFPLEVBQThDLENBQUM7QUFDM0UsTUFBTSxlQUFlLEdBQUcsSUFBSSxPQUFPLEVBQThDLENBQUM7QUFDbEYsTUFBTSwwQ0FBMEMsR0FBRyxNQUFNLENBQ3ZELHVDQUF1QyxDQUN4QyxDQUFDO0FBRUYsTUFBTSwwQ0FBMkMsU0FBUSxjQUFjO0lBQ3JELENBQUMsMENBQTBDLENBQUMsR0FBRyxJQUFJLENBQUM7Q0FDckU7QUFnQkQsTUFBTSxrQkFBa0IsR0FBRyxJQUFJLE9BQU8sQ0FBQyxjQUFjLENBQUMsaUJBQWlCLEVBRXBFLENBQUM7QUFFSixNQUFNLGNBQWMsR0FBRyxDQUNyQixVQUE0QixFQUM1QixRQUFzQixFQUNJLEVBQUU7SUFDNUIsTUFBTSxPQUFPLEdBQUcsUUFBUSxDQUFDLEdBQUcsQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUN6QyxJQUFJLENBQUMsT0FBTyxJQUFJLE9BQU8sQ0FBQyxXQUFXLElBQUksT0FBTyxDQUFDLFVBQVUsQ0FBQyxRQUFRLEVBQUUsQ0FBQztRQUNuRSxNQUFNLElBQUkseUJBQXlCLENBQ2pDLHVCQUF1QixFQUN2Qix3REFBd0QsQ0FDekQsQ0FBQztJQUNKLENBQUM7SUFDRCxJQUFJLFFBQVEsSUFBSSxPQUFPLENBQUMsS0FBSyxLQUFLLFFBQVEsRUFBRSxDQUFDO1FBQzNDLE1BQU0sSUFBSSx5QkFBeUIsQ0FDakMsa0JBQWtCLEVBQ2xCLG9EQUFvRCxDQUNyRCxDQUFDO0lBQ0osQ0FBQztJQUNELElBQ0UsT0FBTyxD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

package/dist_ts/nosqldb/classes.storedinspection.d.ts

@@ -0,0 +1,44 @@
+import type { SmartdataDb } from './classes.db.js';
+import { type SmartdataSession } from './classes.session.js';
+export interface ISmartdataStoredInspectionOptions {
+    filter?: Record<string, unknown>;
+    /** Default 100, maximum 10000. Results are ordered by immutable _id. */
+    limit?: number;
+    skip?: number;
+    /** Default 4 MiB, maximum 64 MiB; overflow rejects the entire page. */
+    maxBytes?: number;
+    /** Default 5000ms, maximum 120000ms. */
+    timeoutMS?: number;
+    signal?: AbortSignal;
+    session?: SmartdataSession;
+}
+export interface ISmartdataStoredInspection {
+    readonly documents: readonly Readonly<Record<string, unknown>>[];
+    readonly hasMore: boolean;
+}
+export type TSmartdataOrdinaryDocumentEvidence = {
+    readonly status: 'valid';
+} | {
+    readonly status: 'invalid';
+    readonly code: 'invalid_document';
+} | {
+    readonly status: 'not_configured';
+};
+export interface ISmartdataStoredDocumentEvidence {
+    /** Untouched stored BSON for diagnosis, never an authorized application record. */
+    readonly document: Readonly<Record<string, unknown>>;
+    /** Reports only the model's ordinary persistence assertion, not exact/domain assertions. */
+    readonly ordinaryValidation: TSmartdataOrdinaryDocumentEvidence;
+}
+export interface ISmartdataStoredEvidenceInspection {
+    readonly evidence: readonly ISmartdataStoredDocumentEvidence[];
+    readonly hasMore: boolean;
+}
+/** @internal Strict inspection used by Model.inspectStoredDocuments. */
+export declare const inspectStoredDocuments: (modelArg: any, dbArg: SmartdataDb, opts?: ISmartdataStoredInspectionOptions) => Promise<ISmartdataStoredInspection>;
+/**
+ * @internal Diagnostic inspection preserves malformed evidence from the same
+ * model and bounds as strict inspection. Invalid records must never enter
+ * normal application flows. Exact and domain assertions remain caller-owned.
+ */
+export declare const inspectStoredDocumentEvidence: (modelArg: any, dbArg: SmartdataDb, opts?: ISmartdataStoredInspectionOptions) => Promise<ISmartdataStoredEvidenceInspection>;

package/dist_ts/nosqldb/classes.storedinspection.js

@@ -0,0 +1,100 @@
+import * as plugins from './plugins.js';
+import { convertFilterForMongoDb } from './classes.doc.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+import { runCursorOperation } from './classes.cursoroperation.js';
+import { acquireSmartdataSession, isSmartdataSession } from './classes.session.js';
+import { collectionTopologyDbInspectionSymbol, collectionModelSchemaResolverSymbol, } from './classes.collectiontopology.js';
+import { validateOrdinaryStoredDocument } from './classes.ordinarypersistence.js';
+/** No model binding, index initialization, hydration, or raw handle escapes. */
+const readStoredDocuments = async (modelArg, dbArg, opts = {}) => {
+    if (!opts || Object.getPrototypeOf(opts) !== Object.prototype ||
+        Reflect.ownKeys(opts).some((keyArg) => typeof keyArg !== 'string' ||
+            !['filter', 'limit', 'skip', 'maxBytes', 'timeoutMS', 'signal', 'session'].includes(keyArg) ||
+            !('value' in Object.getOwnPropertyDescriptor(opts, keyArg)))) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Invalid stored inspection options.');
+    }
+    const limit = opts.limit === undefined ? 100 : opts.limit;
+    const skip = opts.skip === undefined ? 0 : opts.skip;
+    const maxBytes = opts.maxBytes === undefined ? 4 * 1024 * 1024 : opts.maxBytes;
+    const timeoutMS = opts.timeoutMS === undefined ? 5_000 : opts.timeoutMS;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000 ||
+        !Number.isSafeInteger(skip) || skip < 0 || skip > 2_147_483_647 ||
+        !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 64 * 1024 * 1024 ||
+        !Number.isSafeInteger(timeoutMS) || timeoutMS < 1 || timeoutMS > 120_000 ||
+        (opts.signal !== undefined && !(opts.signal instanceof AbortSignal)) ||
+        (opts.session !== undefined && !isSmartdataSession(opts.session))) {
+        throw new SmartdataPersistenceError('invalid_argument', 'Invalid stored inspection bounds or context.');
+    }
+    opts.signal?.throwIfAborted();
+    const schema = modelArg[collectionModelSchemaResolverSymbol]();
+    const filter = convertFilterForMongoDb(opts.filter || {});
+    const lease = opts.session ? acquireSmartdataSession(opts.session, dbArg) : undefined;
+    let page;
+    try {
+        page = await dbArg[collectionTopologyDbInspectionSymbol](async (mongoDbArg) => {
+            const cursor = mongoDbArg.collection(schema.collectionName).find(filter, {
+                sort: { _id: 1 }, skip, limit: limit + 1, batchSize: 1,
+                timeoutMS, timeoutMode: 'cursorLifetime', signal: opts.signal, session: lease?.rawSession,
+            });
+            return runCursorOperation(cursor, async (cursorArg) => {
+                const documents = [];
+                let bytes = 0;
+                while (true) {
+                    const next = await cursorArg.next();
+                    if (next === null)
+                        return { documents, hasMore: false };
+                    if (documents.length === limit)
+                        return { documents, hasMore: true };
+                    bytes += plugins.mongodb.BSON.calculateObjectSize(next);
+                    if (bytes > maxBytes)
+                        throw new SmartdataPersistenceError('unsupported_operation', 'Stored inspection exceeds its byte budget.');
+                    documents.push(next);
+                }
+            }, opts.signal);
+        });
+    }
+    catch (errorArg) {
+        opts.signal?.throwIfAborted();
+        throw errorArg;
+    }
+    finally {
+        lease?.release();
+    }
+    return { schema, page };
+};
+/** @internal Strict inspection used by Model.inspectStoredDocuments. */
+export const inspectStoredDocuments = async (modelArg, dbArg, opts = {}) => {
+    const { schema, page } = await readStoredDocuments(modelArg, dbArg, opts);
+    // Full validation occurs on the untouched stored envelope, before any
+    // constructor/default/serializer can hide field-presence evidence.
+    const documents = schema.ordinaryPersistence
+        ? page.documents.map((documentArg) => validateOrdinaryStoredDocument(documentArg, schema.ordinaryPersistence, schema.persistedFields))
+        : page.documents;
+    return Object.freeze({ documents: Object.freeze(documents), hasMore: page.hasMore });
+};
+/**
+ * @internal Diagnostic inspection preserves malformed evidence from the same
+ * model and bounds as strict inspection. Invalid records must never enter
+ * normal application flows. Exact and domain assertions remain caller-owned.
+ */
+export const inspectStoredDocumentEvidence = async (modelArg, dbArg, opts = {}) => {
+    const { schema, page } = await readStoredDocuments(modelArg, dbArg, opts);
+    const evidence = page.documents.map((documentArg) => {
+        let ordinaryValidation = { status: 'not_configured' };
+        if (schema.ordinaryPersistence) {
+            try {
+                validateOrdinaryStoredDocument(documentArg, schema.ordinaryPersistence, schema.persistedFields);
+                ordinaryValidation = { status: 'valid' };
+            }
+            catch (errorArg) {
+                if (!(errorArg instanceof SmartdataPersistenceError) || errorArg.code !== 'invalid_document') {
+                    throw errorArg;
+                }
+                ordinaryValidation = { status: 'invalid', code: 'invalid_document' };
+            }
+        }
+        return Object.freeze({ document: documentArg, ordinaryValidation: Object.freeze(ordinaryValidation) });
+    });
+    return Object.freeze({ evidence: Object.freeze(evidence), hasMore: page.hasMore });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zdG9yZWRpbnNwZWN0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvbm9zcWxkYi9jbGFzc2VzLnN0b3JlZGluc3BlY3Rpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsT0FBTyxFQUFFLHVCQUF1QixFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDM0QsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDckUsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbEUsT0FBTyxFQUFFLHVCQUF1QixFQUFFLGtCQUFrQixFQUF5QixNQUFNLHNCQUFzQixDQUFDO0FBQzFHLE9BQU8sRUFDTCxvQ0FBb0MsRUFBRSxtQ0FBbUMsR0FDMUUsTUFBTSxpQ0FBaUMsQ0FBQztBQUV6QyxPQUFPLEVBQUUsOEJBQThCLEVBQUUsTUFBTSxrQ0FBa0MsQ0FBQztBQXFDbEYsZ0ZBQWdGO0FBQ2hGLE1BQU0sbUJBQW1CLEdBQUcsS0FBSyxFQUMvQixRQUFhLEVBQ2IsS0FBa0IsRUFDbEIsT0FBMEMsRUFBRSxFQUkzQyxFQUFFO0lBQ0gsSUFBSSxDQUFDLElBQUksSUFBSSxNQUFNLENBQUMsY0FBYyxDQUFDLElBQUksQ0FBQyxLQUFLLE1BQU0sQ0FBQyxTQUFTO1FBQzNELE9BQU8sQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsTUFBTSxFQUFFLEVBQUUsQ0FBQyxPQUFPLE1BQU0sS0FBSyxRQUFRO1lBQy9ELENBQUMsQ0FBQyxRQUFRLEVBQUUsT0FBTyxFQUFFLE1BQU0sRUFBRSxVQUFVLEVBQUUsV0FBVyxFQUFFLFFBQVEsRUFBRSxTQUFTLENBQUMsQ0FBQyxRQUFRLENBQUMsTUFBTSxDQUFDO1lBQzNGLENBQUMsQ0FBQyxPQUFPLElBQUksTUFBTSxDQUFDLHdCQUF3QixDQUFD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

package/dist_ts/nosqldb/classes.testdatabase.d.ts

@@ -0,0 +1,56 @@
+import { SmartdataDb } from './classes.db.js';
+import { SmartDataDbDoc } from './classes.doc.js';
+import { SmartdataPersistenceError } from './classes.persistence.js';
+export interface ISmartdataTestConnection {
+    /** Literal loopback IPv4, ::1, or localhost (normalized to 127.0.0.1). */
+    host: string;
+    port: number;
+    /** Supply both credentials or neither. Authentication uses admin. */
+    username?: string;
+    password?: string;
+}
+export interface ISmartdataTestDatabaseOptions {
+    connection: ISmartdataTestConnection;
+    /** Default 5000; maximum 120000 ms, shared by connection and ownership checks. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ISmartdataStoredDocumentFaultOptions {
+    /** Default 64 KiB, maximum 1 MiB. */
+    maxBytes?: number;
+    /** Default 5000; maximum 120000 ms, including collection preparation. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ISmartdataIndexFaultOptions {
+    /** Default 5000; maximum 120000 ms, shared by topology verification and removal. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export type TSmartdataTestModel = Pick<typeof SmartDataDbDoc, 'prototype' | 'collection' | 'getExpectedCollectionTopology' | 'prepareCollection'> & (abstract new (...args: never[]) => object);
+/** Construction failed and cleanup also failed. Explicit close retries the retained owner. */
+export declare class SmartdataTestDatabaseCreationError extends SmartdataPersistenceError {
+    #private;
+    constructor(cleanupArg: () => Promise<void>);
+    close(): Promise<void>;
+}
+/** Disposable fault injection is available only through the testsupport package subpath. */
+export declare class SmartdataTestDatabase {
+    #private;
+    readonly db: SmartdataDb;
+    private constructor();
+    static create(optionsArg: ISmartdataTestDatabaseOptions): Promise<SmartdataTestDatabase>;
+    insertStoredDocumentFault(modelArg: TSmartdataTestModel, documentArg: unknown, optionsArg?: ISmartdataStoredDocumentFaultOptions): Promise<void>;
+    replaceStoredDocumentFault(modelArg: TSmartdataTestModel, expectedIdArg: unknown, documentArg: unknown, optionsArg?: ISmartdataStoredDocumentFaultOptions): Promise<void>;
+    /** Remove one declared secondary index from an exact, owned test collection. */
+    dropDeclaredIndexFault(modelArg: TSmartdataTestModel, indexNameArg: string, optionsArg?: ISmartdataIndexFaultOptions): Promise<void>;
+    private assertFaultAvailable;
+    private getFaultModelTopology;
+    private assertOwnedBinding;
+    private inject;
+    /** Idempotent after success. A failed close retains ownership for an explicit retry. */
+    close(optionsArg?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    private dispose;
+}