@prosopo/database 3.15.18 → 3.15.20

package/dist/databases/provider.js

@@ -1,2253 +1,1829 @@
-import { isHex } from "@polkadot/util/is";
+import { MongoDatabase } from "../base/mongo.js";
 import { ProsopoDBError } from "@prosopo/common";
+import { CaptchaStates, CaptchaStatus, ContextType, DatasetWithIdsAndTreeSchema, DecisionMachineKind, StoredStatusNames, UserCommitmentSchema } from "@prosopo/types";
+import { CaptchaRecordSchema, ClientContextEntropyRecordSchema, ClientRecordSchema, DatasetRecordSchema, DecisionMachineArtifactRecordSchema, DetectorRecordSchema, PoWCaptchaRecordSchema, PuzzleCaptchaRecordSchema, ScheduledTaskRecordSchema, ScheduledTaskSchema, SessionRecordSchema, SolutionRecordSchema, SpamEmailDomainRecordSchema, UserCommitmentRecordSchema, UserSolutionRecordSchema } from "@prosopo/types-database";
+import { isHex } from "@polkadot/util/is";
 import { connectToRedis, setupRedisIndex } from "@prosopo/redis-client";
-import { DatasetWithIdsAndTreeSchema, UserCommitmentSchema, CaptchaStatus, StoredStatusNames, CaptchaStates, DecisionMachineKind, ContextType } from "@prosopo/types";
-import { CaptchaRecordSchema, PoWCaptchaRecordSchema, PuzzleCaptchaRecordSchema, DatasetRecordSchema, SolutionRecordSchema, UserCommitmentRecordSchema, UserSolutionRecordSchema, ScheduledTaskRecordSchema, ClientRecordSchema, SessionRecordSchema, DetectorRecordSchema, DecisionMachineArtifactRecordSchema, ClientContextEntropyRecordSchema, SpamEmailDomainRecordSchema, ScheduledTaskSchema } from "@prosopo/types-database";
 import { accessRulesRedisIndex, createRedisAccessRulesStorage } from "@prosopo/user-access-policy/redis";
 import { assertCoordsSafe, buildDomainSuffixCandidates } from "@prosopo/util";
-import { MongoDatabase } from "../base/mongo.js";
-const TWENTY_FOUR_HOURS_IN_MS = 24 * 60 * 60 * 1e3;
-const MAX_DOMAIN_SUFFIX_CANDIDATES = 5;
-var TableNames = /* @__PURE__ */ ((TableNames2) => {
-  TableNames2["captcha"] = "captcha";
-  TableNames2["dataset"] = "dataset";
-  TableNames2["solution"] = "solution";
-  TableNames2["commitment"] = "commitment";
-  TableNames2["usersolution"] = "usersolution";
-  TableNames2["scheduler"] = "scheduler";
-  TableNames2["powcaptcha"] = "powcaptcha";
-  TableNames2["puzzlecaptcha"] = "puzzlecaptcha";
-  TableNames2["client"] = "client";
-  TableNames2["session"] = "session";
-  TableNames2["detector"] = "detector";
-  TableNames2["decisionMachine"] = "decisionMachine";
-  TableNames2["clientContextEntropy"] = "clientContextEntropy";
-  TableNames2["spamEmailDomain"] = "spamEmailDomain";
-  return TableNames2;
-})(TableNames || {});
-const PROVIDER_TABLES = [
-  {
-    collectionName: "captcha",
-    modelName: "Captcha",
-    schema: CaptchaRecordSchema
-  },
-  {
-    collectionName: "powcaptcha",
-    modelName: "PowCaptcha",
-    schema: PoWCaptchaRecordSchema
-  },
-  {
-    collectionName: "puzzlecaptcha",
-    modelName: "PuzzleCaptcha",
-    schema: PuzzleCaptchaRecordSchema
-  },
-  {
-    collectionName: "dataset",
-    modelName: "Dataset",
-    schema: DatasetRecordSchema
-  },
-  {
-    collectionName: "solution",
-    modelName: "Solution",
-    schema: SolutionRecordSchema
-  },
-  {
-    collectionName: "commitment",
-    modelName: "UserCommitment",
-    schema: UserCommitmentRecordSchema
-  },
-  {
-    collectionName: "usersolution",
-    modelName: "UserSolution",
-    schema: UserSolutionRecordSchema
-  },
-  {
-    collectionName: "scheduler",
-    modelName: "Scheduler",
-    schema: ScheduledTaskRecordSchema
-  },
-  {
-    collectionName: "client",
-    modelName: "Client",
-    schema: ClientRecordSchema
-  },
-  {
-    collectionName: "session",
-    modelName: "Session",
-    schema: SessionRecordSchema
-  },
-  {
-    collectionName: "detector",
-    modelName: "Detector",
-    schema: DetectorRecordSchema
-  },
-  {
-    collectionName: "decisionMachine",
-    modelName: "DecisionMachine",
-    schema: DecisionMachineArtifactRecordSchema
-  },
-  {
-    collectionName: "clientContextEntropy",
-    modelName: "ClientContextEntropy",
-    schema: ClientContextEntropyRecordSchema
-  },
-  {
-    collectionName: "spamEmailDomain",
-    modelName: "SpamEmailDomain",
-    schema: SpamEmailDomainRecordSchema
-  }
+//#region src/databases/provider.ts
+var TWENTY_FOUR_HOURS_IN_MS = 1440 * 60 * 1e3;
+var MAX_DOMAIN_SUFFIX_CANDIDATES = 5;
+var PROVIDER_TABLES = [
+	{
+		collectionName: "captcha",
+		modelName: "Captcha",
+		schema: CaptchaRecordSchema
+	},
+	{
+		collectionName: "powcaptcha",
+		modelName: "PowCaptcha",
+		schema: PoWCaptchaRecordSchema
+	},
+	{
+		collectionName: "puzzlecaptcha",
+		modelName: "PuzzleCaptcha",
+		schema: PuzzleCaptchaRecordSchema
+	},
+	{
+		collectionName: "dataset",
+		modelName: "Dataset",
+		schema: DatasetRecordSchema
+	},
+	{
+		collectionName: "solution",
+		modelName: "Solution",
+		schema: SolutionRecordSchema
+	},
+	{
+		collectionName: "commitment",
+		modelName: "UserCommitment",
+		schema: UserCommitmentRecordSchema
+	},
+	{
+		collectionName: "usersolution",
+		modelName: "UserSolution",
+		schema: UserSolutionRecordSchema
+	},
+	{
+		collectionName: "scheduler",
+		modelName: "Scheduler",
+		schema: ScheduledTaskRecordSchema
+	},
+	{
+		collectionName: "client",
+		modelName: "Client",
+		schema: ClientRecordSchema
+	},
+	{
+		collectionName: "session",
+		modelName: "Session",
+		schema: SessionRecordSchema
+	},
+	{
+		collectionName: "detector",
+		modelName: "Detector",
+		schema: DetectorRecordSchema
+	},
+	{
+		collectionName: "decisionMachine",
+		modelName: "DecisionMachine",
+		schema: DecisionMachineArtifactRecordSchema
+	},
+	{
+		collectionName: "clientContextEntropy",
+		modelName: "ClientContextEntropy",
+		schema: ClientContextEntropyRecordSchema
+	},
+	{
+		collectionName: "spamEmailDomain",
+		modelName: "SpamEmailDomain",
+		schema: SpamEmailDomainRecordSchema
+	}
 ];
-class ProviderDatabase extends MongoDatabase {
-  constructor(options) {
-    super(
-      options.mongo.url,
-      options.mongo.dbname,
-      options.mongo.authSource,
-      options.logger
-    );
-    this.options = options;
-    this.tables = {};
-    this.indexesEnsured = false;
-    this.tables = {};
-    this.redisAccessRulesConnection = null;
-    this.redisConnection = null;
-    this.userAccessRulesStorage = null;
-  }
-  setCentralDbStreamer(streamer) {
-    this.centralStreamer = streamer;
-  }
-  hasCentralDbStreamer() {
-    return this.centralStreamer !== void 0;
-  }
-  async connect() {
-    await super.connect();
-    this.loadTables();
-    await this.setupRedis();
-  }
-  async setupRedis() {
-    this.redisConnection = connectToRedis({
-      url: this.options.redis?.url,
-      password: this.options.redis?.password,
-      logger: this.logger
-    });
-    this.redisAccessRulesConnection = setupRedisIndex(
-      this.redisConnection,
-      {
-        ...accessRulesRedisIndex,
-        name: this.options.redis?.indexName || accessRulesRedisIndex.name
-      },
-      this.logger
-    );
-    this.userAccessRulesStorage = createRedisAccessRulesStorage(
-      this.redisAccessRulesConnection,
-      this.logger
-    );
-  }
-  loadTables() {
-    const tables = {};
-    PROVIDER_TABLES.map(({ collectionName, modelName, schema }) => {
-      if (this.connection) {
-        tables[collectionName] = this.connection.model(modelName, schema);
-      }
-    });
-    this.tables = tables;
-  }
-  getTables() {
-    if (!this.tables) {
-      throw new ProsopoDBError("DATABASE.TABLES_UNDEFINED", {
-        context: { failedFuncName: this.getTables.name },
-        logger: this.logger
-      });
-    }
-    return this.tables;
-  }
-  getRedisAccessRulesConnection() {
-    if (null === this.redisAccessRulesConnection) {
-      throw new ProsopoDBError(
-        "DATABASE.REDIS_ACCESS_RULES_CONNECTION_UNDEFINED"
-      );
-    }
-    return this.redisAccessRulesConnection;
-  }
-  getRedisConnection() {
-    if (null === this.redisConnection) {
-      throw new ProsopoDBError(
-        "DATABASE.REDIS_ACCESS_RULES_CONNECTION_UNDEFINED"
-      );
-    }
-    return this.redisConnection;
-  }
-  async ensureIndexes() {
-    const indexPromises = [];
-    if (!this.indexesEnsured) {
-      PROVIDER_TABLES.map(({ collectionName }) => {
-        indexPromises.push(
-          new Promise((resolve) => {
-            if (this.connected) {
-              this.tables[collectionName].collection.dropIndexes().then(() => {
-                this.tables[collectionName].ensureIndexes().then(() => {
-                  this.logger.info(() => ({
-                    msg: `Indexes ensured for collection ${collectionName}`
-                  }));
-                  resolve();
-                }).catch((err) => {
-                  this.logger.warn(() => ({
-                    err,
-                    msg: `Error creating indexes for collection ${collectionName}`
-                  }));
-                  resolve();
-                });
-              });
-            } else {
-              this.logger.info(() => ({
-                msg: `Skipping index creation for collection ${collectionName} as not connected`
-              }));
-              resolve();
-            }
-          })
-        );
-      });
-    }
-    await Promise.all(indexPromises);
-    this.indexesEnsured = true;
-  }
-  getUserAccessRulesStorage() {
-    if (null === this.userAccessRulesStorage) {
-      throw new ProsopoDBError("DATABASE.USER_ACCESS_RULES_STORAGE_UNDEFINED");
-    }
-    return this.userAccessRulesStorage;
-  }
-  /**
-   * @description Load a dataset to the database
-   * @param {Dataset}  dataset
-   */
-  async storeDataset(dataset) {
-    try {
-      this.logger.debug(() => ({
-        data: { datasetId: dataset.datasetId },
-        msg: "Storing dataset in database"
-      }));
-      const parsedDataset = DatasetWithIdsAndTreeSchema.parse(dataset);
-      const datasetDoc = {
-        datasetId: parsedDataset.datasetId,
-        datasetContentId: parsedDataset.datasetContentId,
-        format: parsedDataset.format,
-        contentTree: parsedDataset.contentTree,
-        solutionTree: parsedDataset.solutionTree
-      };
-      const filter = {
-        datasetId: parsedDataset.datasetId
-      };
-      await this.tables.dataset?.updateOne(
-        filter,
-        { $set: datasetDoc },
-        { upsert: true }
-      );
-      const captchaDocs = parsedDataset.captchas.map(
-        ({ solution, ...captcha }, index) => ({
-          ...captcha,
-          datasetId: parsedDataset.datasetId,
-          datasetContentId: parsedDataset.datasetContentId,
-          index,
-          solved: !!solution?.length
-        })
-      );
-      this.logger.debug(() => ({
-        msg: "Inserting captcha records"
-      }));
-      if (captchaDocs.length) {
-        await this.tables?.captcha.bulkWrite(
-          captchaDocs.map((captchaDoc) => ({
-            updateOne: {
-              filter: { captchaId: captchaDoc.captchaId },
-              // `$setOnInsert` stamps `randomKey` once on the
-              // initial insert and leaves it untouched on
-              // re-imports of the same captchaId. See
-              // `getRandomCaptcha` and the
-              // providerBackfillCaptchaRandomKey playbook for
-              // the corresponding read path and one-shot
-              // backfill of pre-existing rows.
-              update: {
-                $set: captchaDoc,
-                $setOnInsert: { randomKey: Math.random() }
-              },
-              upsert: true
-            }
-          }))
-        );
-      }
-      const captchaSolutionDocs = parsedDataset.captchas.filter(({ solution }) => solution?.length).map((captcha) => ({
-        captchaId: captcha.captchaId,
-        captchaContentId: captcha.captchaContentId,
-        solution: captcha.solution,
-        salt: captcha.salt,
-        datasetId: parsedDataset.datasetId,
-        datasetContentId: parsedDataset.datasetContentId
-      }));
-      this.logger.debug(() => ({
-        msg: "Inserting solution records"
-      }));
-      if (captchaSolutionDocs.length) {
-        await this.tables?.solution.bulkWrite(
-          captchaSolutionDocs.map((captchaSolutionDoc) => ({
-            updateOne: {
-              filter: { captchaId: captchaSolutionDoc.captchaId },
-              update: { $set: captchaSolutionDoc },
-              upsert: true
-            }
-          }))
-        );
-      }
-      this.logger.debug(() => ({
-        msg: "Dataset stored in database"
-      }));
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.DATASET_LOAD_FAILED", {
-        context: { failedFuncName: this.storeDataset.name, error: err },
-        logger: this.logger
-      });
-    }
-  }
-  /** @description Get solutions for a dataset
-   * @param {string} datasetId
-   */
-  async getSolutions(datasetId) {
-    const filter = { datasetId };
-    const docs = await this.tables?.solution.find(filter).lean();
-    return docs ? docs : [];
-  }
-  /** @description Get a solution by captcha id
-   * @param {string} captchaId
-   */
-  async getSolutionByCaptchaId(captchaId) {
-    const filter = { captchaId };
-    const doc = await this.tables?.solution.findOne(filter).lean();
-    return doc || null;
-  }
-  /** @description Get a dataset from the database
-   * @param {string} datasetId
-   */
-  async getDataset(datasetId) {
-    const filter = { datasetId };
-    const datasetDoc = await this.tables?.dataset.findOne(filter).lean();
-    if (datasetDoc) {
-      const { datasetContentId, format, contentTree, solutionTree } = datasetDoc;
-      const captchas = await this.tables?.captcha.find(filter).lean() || [];
-      const solutions = await this.tables?.solution.find(filter).lean() || [];
-      const solutionsKeyed = {};
-      for (const solution of solutions) {
-        solutionsKeyed[solution.captchaId] = solution;
-      }
-      return {
-        datasetId,
-        datasetContentId,
-        format,
-        contentTree: contentTree || [],
-        solutionTree: solutionTree || [],
-        captchas: captchas.map((captchaDoc) => {
-          const { captchaId, captchaContentId, items, target, salt, solved } = captchaDoc;
-          const solution = solutionsKeyed[captchaId];
-          return {
-            captchaId,
-            captchaContentId,
-            solved: !!solved,
-            salt,
-            items,
-            target,
-            solution: solved && solution ? solution.solution : []
-          };
-        })
-      };
-    }
-    throw new ProsopoDBError("DATABASE.DATASET_GET_FAILED", {
-      context: { failedFuncName: this.getDataset.name, datasetId }
-    });
-  }
-  /**
-   * @description Get random captchas that are solved or not solved
-   * @param {boolean}  solved    `true` when captcha is solved
-   * @param {string}   datasetId  the id of the data set
-   * @param {number}   size       the number of records to be returned
-   */
-  async getRandomCaptcha(solved, datasetId, size) {
-    if (!isHex(datasetId)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: { failedFuncName: this.getRandomCaptcha.name, datasetId }
-      });
-    }
-    const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
-    const projection = {
-      _id: 0,
-      datasetId: 1,
-      datasetContentId: 1,
-      captchaId: 1,
-      captchaContentId: 1,
-      items: 1,
-      target: 1
-    };
-    const baseFilter = { datasetId, solved };
-    const pivot = Math.random();
-    const head = await this.tables?.captcha.find({ ...baseFilter, randomKey: { $gte: pivot } }, projection).sort({ randomKey: 1 }).limit(sampleSize).lean() ?? [];
-    let docs = head;
-    if (docs.length < sampleSize) {
-      const tail = await this.tables?.captcha.find({ ...baseFilter, randomKey: { $lt: pivot } }, projection).sort({ randomKey: 1 }).limit(sampleSize - docs.length).lean() ?? [];
-      docs = docs.concat(tail);
-    }
-    if (docs.length === 0) {
-      const fallback = await this.tables?.captcha.aggregate([
-        { $match: baseFilter },
-        { $sample: { size: sampleSize } },
-        { $project: projection }
-      ]).exec() ?? [];
-      if (fallback.length > 0) {
-        return fallback.map(({ _id, ...keep }) => keep);
-      }
-    }
-    if (docs.length > 0) {
-      return docs;
-    }
-    throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-      context: {
-        failedFuncName: this.getRandomCaptcha.name,
-        solved,
-        datasetId,
-        size
-      }
-    });
-  }
-  /**
-   * @description Get captchas by id
-   * @param {string[]} captchaId
-   */
-  async getCaptchaById(captchaId) {
-    const filter = { captchaId: { $in: captchaId } };
-    const cursor = this.tables?.captcha.find(filter, {
-      _id: 0,
-      captchaId: 1,
-      datasetId: 1,
-      items: 1
-    }).lean();
-    const docs = await cursor;
-    if (docs?.length) {
-      return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
-    }
-    throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-      context: { failedFuncName: this.getCaptchaById.name, captchaId }
-    });
-  }
-  /**
-   * @description Update a captcha
-   * @param {Captcha}  captcha
-   * @param {string}   datasetId  the id of the data set
-   */
-  async updateCaptcha(captcha, datasetId) {
-    if (!isHex(datasetId)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: { failedFuncName: this.updateCaptcha.name, datasetId }
-      });
-    }
-    try {
-      const filter = { datasetId };
-      await this.tables?.captcha.updateOne(
-        filter,
-        { $set: captcha },
-        { upsert: false }
-      );
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
-        context: { failedFuncName: this.getDatasetDetails.name, error: err }
-      });
-    }
-  }
-  /**
-   * @description Remove captchas
-   */
-  async removeCaptchas(captchaIds) {
-    const filter = { captchaId: { $in: captchaIds } };
-    await this.tables?.captcha.deleteMany(filter);
-  }
-  /**
-   * @description Get a dataset by Id
-   */
-  /**
-   * Returns the most recently uploaded dataset's ID. Used as the per-provider
-   * default when a client doesn't pin a specific dataset (which it can't
-   * under DNS-based routing — clients don't know which provider they'll hit).
-   */
-  async getMostRecentDatasetId() {
-    const dataset = await this.tables?.dataset.findOne().sort({ _id: -1 }).lean();
-    const datasetId = dataset?.datasetId;
-    return typeof datasetId === "string" ? datasetId : void 0;
-  }
-  async getDatasetDetails(datasetId) {
-    if (!isHex(datasetId)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: { failedFuncName: this.getDatasetDetails.name, datasetId }
-      });
-    }
-    const filter = { datasetId };
-    const doc = await this.tables?.dataset.findOne(filter).lean();
-    if (doc) {
-      return doc;
-    }
-    throw new ProsopoDBError("DATABASE.DATASET_GET_FAILED", {
-      context: {
-        failedFuncName: this.getDatasetDetails.name,
-        datasetId
-      }
-    });
-  }
-  /**
-   * @description Store a Dapp User's captcha solution commitment
-   */
-  async storeUserImageCaptchaSolution(captchas, commit) {
-    const commitmentRecord = UserCommitmentSchema.parse({
-      ...commit,
-      lastUpdatedTimestamp: /* @__PURE__ */ new Date()
-    });
-    if (captchas.length) {
-      const filter = {
-        id: commit.id
-      };
-      await this.tables?.commitment.updateOne(filter, commitmentRecord, {
-        upsert: true
-      });
-      const ops = captchas.map((captcha) => ({
-        updateOne: {
-          filter: {
-            commitmentId: commit.id,
-            captchaId: captcha.captchaId
-          },
-          update: {
-            $set: {
-              captchaId: captcha.captchaId,
-              captchaContentId: captcha.captchaContentId,
-              salt: captcha.salt,
-              solution: captcha.solution,
-              commitmentId: commit.id,
-              processed: false
-            }
-          },
-          upsert: true
-        }
-      }));
-      await this.tables?.usersolution.bulkWrite(ops);
-      this.centralStreamer?.streamImageRecord(
-        commitmentRecord,
-        (ts) => this.tables.commitment.updateOne({ id: commit.id }, { $set: { storedAtTimestamp: ts } }).then(() => {
-        })
-      );
-    }
-  }
-  /**
-   * @description Adds a new PoW Captcha record to the database.
-   * @param {string} challenge The challenge string for the captcha.
-   * @param components The components of the PoW challenge.
-   * @param difficulty
-   * @param providerSignature
-   * @param ipAddress
-   * @param headers
-   * @param ja4
-   * @param sessionId
-   * @param serverChecked
-   * @param userSubmitted
-   * @param storedStatus
-   * @param userSignature
-   * @param ipInfo full ipinfo payload from the ipInfoMiddleware
-   * @returns {Promise<void>} A promise that resolves when the record is added.
-   */
-  async storePowCaptchaRecord(challenge, components, difficulty, providerSignature, ipAddress, headers, ja4, sessionId, serverChecked = false, userSubmitted = false, userSignature, ipInfo) {
-    const tables = this.getTables();
-    const powCaptchaRecord = {
-      challenge,
-      userAccount: components.userAccount,
-      dappAccount: components.dappAccount,
-      requestedAtTimestamp: new Date(components.requestedAtTimestamp),
-      ipAddress,
-      headers,
-      ja4,
-      result: { status: CaptchaStatus.pending },
-      userSubmitted,
-      serverChecked,
-      difficulty,
-      providerSignature,
-      userSignature,
-      lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-      pendingStage: true,
-      sessionId,
-      ipInfo
-    };
-    try {
-      await tables.powcaptcha.create(powCaptchaRecord);
-      this.logger.info(() => ({
-        data: {
-          challenge,
-          userSubmitted,
-          serverChecked,
-          countryCode: ipInfo?.isValid ? ipInfo.countryCode : void 0
-        },
-        msg: "PowCaptcha record added successfully"
-      }));
-      this.centralStreamer?.streamPowRecord(
-        powCaptchaRecord,
-        (ts) => (
-          // Guard with `lastUpdatedTimestamp: { $lte: ts }` so a concurrent
-          // update (newer lastUpdatedTimestamp) doesn't get its pendingStage
-          // flag cleared by this older stage completion. Mismatched docs
-          // leave pendingStage set so the next sweep picks them up.
-          this.tables.powcaptcha.updateOne(
-            { challenge, lastUpdatedTimestamp: { $lte: ts } },
-            {
-              $set: { storedAtTimestamp: ts },
-              $unset: { pendingStage: 1 }
-            }
-          ).then(() => {
-          })
-        )
-      );
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
-        context: {
-          error,
-          challenge,
-          userSubmitted,
-          serverChecked,
-          ipInfo
-        },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err: error,
-        msg: "Failed to add PowCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  /**
-   * @description Retrieves a PoW Captcha record by its challenge string.
-   * @param {string} challenge The challenge string to search for.
-   * @returns {Promise<PoWCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
-   */
-  async getPowCaptchaRecordByChallenge(challenge) {
-    if (!this.tables) {
-      throw new ProsopoDBError("DATABASE.DATABASE_UNDEFINED", {
-        context: { failedFuncName: this.getPowCaptchaRecordByChallenge.name },
-        logger: this.logger
-      });
-    }
-    try {
-      const filter = { challenge };
-      const record = await this.tables.powcaptcha.findOne(filter, {
-        challenge: 1,
-        userAccount: 1,
-        dappAccount: 1,
-        requestedAtTimestamp: 1,
-        submittedAtTimestamp: 1,
-        verifiedAtTimestamp: 1,
-        failedAtTimestamp: 1,
-        ipAddress: 1,
-        headers: 1,
-        ja4: 1,
-        result: 1,
-        difficulty: 1,
-        sessionId: 1,
-        ipInfo: 1,
-        deviceCapability: 1,
-        behavioralDataPacked: 1,
-        serverChecked: 1,
-        userSubmitted: 1,
-        coords: 1
-      }).lean();
-      if (record) {
-        this.logger.info(() => ({
-          data: { challenge },
-          msg: "PowCaptcha record retrieved successfully"
-        }));
-        return record;
-      }
-      this.logger.info(() => ({
-        data: { challenge },
-        msg: "No PowCaptcha record found"
-      }));
-      return null;
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-        context: { error, challenge },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err,
-        msg: "Failed to retrieve PowCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  /**
-   * @description Updates a PoW Captcha record in the database.
-   * @param {string} challenge The challenge string of the captcha to be updated.
-   * @param result
-   * @param serverChecked
-   * @param userSubmitted
-   * @param userSignature
-   * @returns {Promise<void>} A promise that resolves when the record is updated.
-   */
-  async updatePowCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords) {
-    const tables = this.getTables();
-    const timestamp = /* @__PURE__ */ new Date();
-    const isDisapproved = result.status === CaptchaStatus.disapproved;
-    assertCoordsSafe(coords, "coords");
-    const setStage = {
-      result,
-      serverChecked,
-      userSubmitted,
-      userSignature,
-      lastUpdatedTimestamp: timestamp,
-      pendingStage: true,
-      ...coords && { coords }
-    };
-    if (userSubmitted) {
-      setStage.submittedAtTimestamp = {
-        $ifNull: ["$submittedAtTimestamp", timestamp]
-      };
-    }
-    if (isDisapproved) {
-      setStage.failedAtTimestamp = {
-        $ifNull: ["$failedAtTimestamp", timestamp]
-      };
-    }
-    try {
-      const updateResult = await tables.powcaptcha.updateOne({ challenge }, [
-        { $set: setStage }
-      ]);
-      if (updateResult.matchedCount === 0) {
-        const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-          context: {
-            challenge,
-            ...setStage
-          },
-          logger: this.logger
-        });
-        this.logger.info(() => ({
-          err,
-          msg: "No PowCaptcha record found to update"
-        }));
-        throw err;
-      }
-      this.logger.info(() => ({
-        data: {
-          challenge,
-          ...setStage
-        },
-        msg: "PowCaptcha record updated successfully"
-      }));
-      this.centralStreamer?.streamPowUpdate(
-        () => this.getPowCaptchaRecordByChallenge(challenge),
-        (ts) => this.tables.powcaptcha.updateOne(
-          { challenge, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
-        context: {
-          error,
-          challenge,
-          ...setStage
-        },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err,
-        msg: "Failed to update PowCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  async updatePowCaptchaRecord(challenge, updates) {
-    const tables = this.getTables();
-    await tables.powcaptcha.updateOne(
-      { challenge },
-      { $set: { ...updates, pendingStage: true } },
-      { upsert: false }
-    );
-    this.centralStreamer?.streamPowUpdate(
-      () => this.getPowCaptchaRecordByChallenge(challenge),
-      (ts) => this.tables.powcaptcha.updateOne(
-        { challenge, lastUpdatedTimestamp: { $lte: ts } },
-        {
-          $set: { storedAtTimestamp: ts },
-          $unset: { pendingStage: 1 }
-        }
-      ).then(() => {
-      })
-    );
-  }
-  async storePuzzleCaptchaRecord(challenge, components, targetX, targetY, originX, originY, tolerance, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
-    const tables = this.getTables();
-    const puzzleCaptchaRecord = {
-      challenge,
-      userAccount: components.userAccount,
-      dappAccount: components.dappAccount,
-      requestedAtTimestamp: new Date(components.requestedAtTimestamp),
-      ipAddress,
-      headers,
-      ja4,
-      result: { status: CaptchaStatus.pending },
-      userSubmitted: false,
-      serverChecked: false,
-      targetX,
-      targetY,
-      originX,
-      originY,
-      tolerance,
-      providerSignature,
-      lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-      pendingStage: true,
-      sessionId,
-      ipInfo
-    };
-    try {
-      await tables.puzzlecaptcha.create(puzzleCaptchaRecord);
-      this.logger.info(() => ({
-        data: {
-          challenge,
-          countryCode: ipInfo?.isValid ? ipInfo.countryCode : void 0
-        },
-        msg: "PuzzleCaptcha record added successfully"
-      }));
-      this.centralStreamer?.streamPuzzleRecord(
-        puzzleCaptchaRecord,
-        (ts) => this.tables.puzzlecaptcha.updateOne(
-          { challenge, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
-        context: {
-          error,
-          challenge,
-          ipInfo
-        },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err: error,
-        msg: "Failed to add PuzzleCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  /**
-   * @description Retrieves a Puzzle Captcha record by its challenge string.
-   * @param {string} challenge The challenge string to search for.
-   * @returns {Promise<PuzzleCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
-   */
-  async getPuzzleCaptchaRecordByChallenge(challenge) {
-    if (!this.tables) {
-      throw new ProsopoDBError("DATABASE.DATABASE_UNDEFINED", {
-        context: {
-          failedFuncName: this.getPuzzleCaptchaRecordByChallenge.name
-        },
-        logger: this.logger
-      });
-    }
-    try {
-      const filter = { challenge };
-      const record = await this.tables.puzzlecaptcha.findOne(filter, {
-        challenge: 1,
-        userAccount: 1,
-        dappAccount: 1,
-        requestedAtTimestamp: 1,
-        // submittedAtTimestamp gates the submit → verify
-        // recency check in serverVerifyPuzzleCaptchaSolution.
-        // Missing it here silently trips the "too old" path
-        // even on freshly-solved puzzles because the code
-        // treats a missing field as Number.POSITIVE_INFINITY.
-        submittedAtTimestamp: 1,
-        ipAddress: 1,
-        headers: 1,
-        ja4: 1,
-        result: 1,
-        targetX: 1,
-        targetY: 1,
-        originX: 1,
-        originY: 1,
-        tolerance: 1,
-        puzzleEvents: 1,
-        sessionId: 1,
-        ipInfo: 1,
-        deviceCapability: 1,
-        behavioralDataPacked: 1,
-        serverChecked: 1,
-        userSubmitted: 1,
-        coords: 1
-      }).lean();
-      if (record) {
-        this.logger.info(() => ({
-          data: { challenge },
-          msg: "PuzzleCaptcha record retrieved successfully"
-        }));
-        return record;
-      }
-      this.logger.info(() => ({
-        data: { challenge },
-        msg: "No PuzzleCaptcha record found"
-      }));
-      return null;
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-        context: { error, challenge },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err,
-        msg: "Failed to retrieve PuzzleCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  /**
-   * @description Updates a Puzzle Captcha record result in the database.
-   * @param {string} challenge The challenge string of the captcha to be updated.
-   * @param result
-   * @param serverChecked
-   * @param userSubmitted
-   * @param userSignature
-   * @param coords
-   * @param lastUpdatedTimestamp
-   * @returns {Promise<void>} A promise that resolves when the record is updated.
-   */
-  async updatePuzzleCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
-    const tables = this.getTables();
-    const timestamp = lastUpdatedTimestamp ?? /* @__PURE__ */ new Date();
-    const isDisapproved = result.status === CaptchaStatus.disapproved;
-    assertCoordsSafe(coords, "coords");
-    const setStage = {
-      result,
-      serverChecked,
-      userSubmitted,
-      userSignature,
-      lastUpdatedTimestamp: timestamp,
-      pendingStage: true,
-      ...coords && { coords },
-      ...userSubmitted && { submittedAtTimestamp: timestamp },
-      ...isDisapproved && { failedAtTimestamp: timestamp }
-    };
-    try {
-      const updateResult = await tables.puzzlecaptcha.updateOne(
-        { challenge },
-        { $set: setStage }
-      );
-      if (updateResult.matchedCount === 0) {
-        const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
-          context: {
-            challenge,
-            ...setStage
-          },
-          logger: this.logger
-        });
-        this.logger.info(() => ({
-          err,
-          msg: "No PuzzleCaptcha record found to update"
-        }));
-        throw err;
-      }
-      this.logger.info(() => ({
-        data: {
-          challenge,
-          ...setStage
-        },
-        msg: "PuzzleCaptcha record updated successfully"
-      }));
-      this.centralStreamer?.streamPuzzleUpdate(
-        () => this.getPuzzleCaptchaRecordByChallenge(challenge),
-        (ts) => this.tables.puzzlecaptcha.updateOne(
-          { challenge, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (error) {
-      const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
-        context: {
-          error,
-          challenge,
-          ...setStage
-        },
-        logger: this.logger
-      });
-      this.logger.error(() => ({
-        err,
-        msg: "Failed to update PuzzleCaptcha record"
-      }));
-      throw err;
-    }
-  }
-  async updatePuzzleCaptchaRecord(challenge, updates) {
-    const tables = this.getTables();
-    const timestamp = /* @__PURE__ */ new Date();
-    const baseSet = {
-      ...updates,
-      pendingStage: true,
-      ...updates.serverChecked === true && {
-        verifiedAtTimestamp: timestamp
-      },
-      ...updates.userSubmitted === true && {
-        submittedAtTimestamp: timestamp
-      },
-      ...updates.result?.status === CaptchaStatus.disapproved && {
-        failedAtTimestamp: timestamp
-      }
-    };
-    await tables.puzzlecaptcha.updateOne({ challenge }, { $set: baseSet });
-    this.centralStreamer?.streamPuzzleUpdate(
-      () => this.getPuzzleCaptchaRecordByChallenge(challenge),
-      (ts) => this.tables.puzzlecaptcha.updateOne(
-        { challenge, lastUpdatedTimestamp: { $lte: ts } },
-        {
-          $set: { storedAtTimestamp: ts },
-          $unset: { pendingStage: 1 }
-        }
-      ).then(() => {
-      })
-    );
-  }
-  /** @description Get serverChecked Dapp User image captcha commitments from the commitments table
-   */
-  async getCheckedDappUserCommitments() {
-    const filter = { [StoredStatusNames.serverChecked]: true };
-    const docs = await this.tables?.commitment.find(filter).lean();
-    return docs || [];
-  }
-  /** @description Get Dapp User captcha commitments from the commitments table that have not been counted towards the
-   * client's total.
-   *
-   * Served by the `pendingStage_partial` index. Records have
-   * `pendingStage: true` set on insert and on every mutation (see
-   * `updateDappUserCommitment`, `markDappUserCommitmentsChecked`,
-   * `approveDappUserCommitment`, `disapproveDappUserCommitment`,
-   * `storePendingImageCommitment`). `markDappUserCommitmentsStored` clears
-   * the flag after a successful stage, guarded by `lastUpdatedTimestamp`
-   * so an in-flight update isn't lost.
-   */
-  async getUnstoredDappUserCommitments(limit = 1e3, skip = 0) {
-    const docs = await this.tables?.commitment.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean();
-    return docs || [];
-  }
-  /** @description Mark a list of captcha commits as stored.
-   *
-   * `asOfTimestamp` defaults to "now" but the sweep should pass the time
-   * at which it fetched the batch. The lastUpdatedTimestamp guard prevents
-   * us from clearing pendingStage on a record that was mutated between
-   * fetch and mark-stored — those records will leave pendingStage set so
-   * the next sweep picks them up.
-   */
-  async markDappUserCommitmentsStored(commitmentIds, asOfTimestamp = /* @__PURE__ */ new Date()) {
-    await this.tables?.commitment.updateMany(
-      {
-        id: { $in: commitmentIds },
-        lastUpdatedTimestamp: { $lte: asOfTimestamp }
-      },
-      {
-        $set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
-        $unset: { pendingStage: 1 }
-      },
-      { upsert: false }
-    );
-  }
-  /** @description Mark a list of captcha commits as checked
-   */
-  async markDappUserCommitmentsChecked(commitmentIds) {
-    const timestamp = /* @__PURE__ */ new Date();
-    await this.tables?.commitment.updateMany({ id: { $in: commitmentIds } }, [
-      {
-        $set: {
-          serverChecked: true,
-          lastUpdatedTimestamp: timestamp,
-          pendingStage: true,
-          verifiedAtTimestamp: {
-            $ifNull: ["$verifiedAtTimestamp", timestamp]
-          }
-        }
-      }
-    ]);
-  }
-  /** @description Update an image captcha commitment
-   */
-  async updateDappUserCommitment(commitmentId, updates) {
-    const filter = { id: commitmentId };
-    const timestamp = /* @__PURE__ */ new Date();
-    const baseSet = {
-      ...updates,
-      lastUpdatedAtTimestamp: timestamp,
-      pendingStage: true
-    };
-    const pipelineExprs = {};
-    if (updates.userSubmitted === true) {
-      pipelineExprs.submittedAtTimestamp = {
-        $ifNull: ["$submittedAtTimestamp", timestamp]
-      };
-    }
-    if (updates.serverChecked === true) {
-      pipelineExprs.verifiedAtTimestamp = {
-        $ifNull: ["$verifiedAtTimestamp", timestamp]
-      };
-    }
-    if (updates.result?.status === CaptchaStatus.disapproved) {
-      pipelineExprs.failedAtTimestamp = {
-        $ifNull: ["$failedAtTimestamp", timestamp]
-      };
-    }
-    if (Object.keys(pipelineExprs).length === 0) {
-      await this.tables?.commitment.updateOne(filter, { $set: baseSet });
-      return;
-    }
-    await this.tables?.commitment.updateOne(filter, [
-      { $set: { ...baseSet, ...pipelineExprs } }
-    ]);
-  }
-  /**
-   * @description Get Dapp User PoW captcha commitments that have not been counted towards the client's total
-   * @param {number} limit Maximum number of records to return
-   * @param {number} skip Number of records to skip (for pagination)
-   * @returns {Promise<PoWCaptchaRecord[]>} Array of PoW captcha records
-   */
-  async getUnstoredDappUserPoWCommitments(limit = 1e3, skip = 0) {
-    const docs = await this.tables?.powcaptcha.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean();
-    return docs || [];
-  }
-  /** @description Mark a list of PoW captcha commits as stored.
-   *
-   * `asOfTimestamp` defaults to "now" but the sweep should pass the time
-   * at which it fetched the batch. See markDappUserCommitmentsStored for
-   * the guard rationale.
-   */
-  async markDappUserPoWCommitmentsStored(challenges, asOfTimestamp = /* @__PURE__ */ new Date()) {
-    await this.tables?.powcaptcha.updateMany(
-      {
-        challenge: { $in: challenges },
-        lastUpdatedTimestamp: { $lte: asOfTimestamp }
-      },
-      {
-        $set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
-        $unset: { pendingStage: 1 }
-      },
-      { upsert: false }
-    );
-  }
-  /** @description Mark a list of PoW captcha commits as checked by the server
-   */
-  async markDappUserPoWCommitmentsChecked(challenges) {
-    const timestamp = /* @__PURE__ */ new Date();
-    await this.tables?.powcaptcha.updateMany(
-      { challenge: { $in: challenges } },
-      [
-        {
-          $set: {
-            serverChecked: true,
-            lastUpdatedTimestamp: timestamp,
-            pendingStage: true,
-            verifiedAtTimestamp: {
-              $ifNull: ["$verifiedAtTimestamp", timestamp]
-            }
-          }
-        }
-      ],
-      { upsert: false }
-    );
-  }
-  /**
-   * Store a new session record
-   */
-  async storeSessionRecord(sessionRecord) {
-    try {
-      this.logger.debug(() => ({
-        data: { action: "storing", sessionRecord }
-      }));
-      const recordWithFlag = {
-        ...sessionRecord,
-        lastUpdatedTimestamp: sessionRecord.lastUpdatedTimestamp ?? sessionRecord.createdAt,
-        pendingStage: true
-      };
-      await this.tables.session.create(recordWithFlag);
-      this.centralStreamer?.streamSessionRecord(
-        recordWithFlag,
-        (ts) => this.tables.session.updateOne(
-          {
-            sessionId: sessionRecord.sessionId,
-            lastUpdatedTimestamp: { $lte: ts }
-          },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_STORE_FAILED", {
-        context: { error: err, sessionId: sessionRecord.sessionId },
-        logger: this.logger
-      });
-    }
-  }
-  /**
-   * Persist a synthetic Session record for a request that was 401'd at the
-   * request-time block middleware. The record is written with
-   * `blocked=true` + `deleted=true` so the captcha flow can't pick it up
-   * downstream, and with sentinel values for the schema-required fields
-   * the blocked request never had a chance to populate (score / threshold /
-   * captchaType / etc.).
-   *
-   * Designed for fire-and-forget: callers `void`-cast the promise and any
-   * Mongo error is swallowed-and-logged so the 401 response is never
-   * delayed by a persistence failure. The structured log line at the call
-   * site is the source of truth either way.
-   *
-   * Mirrors `storeSessionRecord` enough that the Traffic-page
-   * aggregations can read these records out of the central-streamer
-   * pipeline once the UI work lands.
-   */
-  async storeBlockedSession(record) {
-    try {
-      const stored = {
-        ...record,
-        blocked: true,
-        deleted: true,
-        // Stamp storedAtTimestamp so the existing TTL index on the
-        // sessions collection sweeps the record after one day.
-        storedAtTimestamp: record.storedAtTimestamp ?? record.createdAt,
-        lastUpdatedTimestamp: record.lastUpdatedTimestamp ?? record.createdAt
-      };
-      await this.tables.session.create(stored);
-      this.centralStreamer?.streamSessionRecord(
-        stored,
-        (ts) => this.tables.session.updateOne(
-          {
-            sessionId: stored.sessionId,
-            lastUpdatedTimestamp: { $lte: ts }
-          },
-          { $set: { storedAtTimestamp: ts } }
-        ).then(() => {
-        })
-      );
-    } catch (err) {
-      this.logger.warn(() => ({
-        err,
-        msg: "Failed to persist blocked session record",
-        data: { sessionId: record.sessionId, siteKey: record.siteKey }
-      }));
-    }
-  }
-  /**
-   * Get a session record by sessionId
-   */
-  async getSessionRecordBySessionId(sessionId) {
-    const filter = { sessionId };
-    const doc = await this.tables.session.findOne(filter, {
-      sessionId: 1,
-      token: 1,
-      score: 1,
-      threshold: 1,
-      scoreComponents: 1,
-      ipAddress: 1,
-      ipInfo: 1,
-      webView: 1,
-      iFrame: 1,
-      isEscalation: 1,
-      decryptedHeadHash: 1,
-      siteKey: 1,
-      reason: 1,
-      mode: 1,
-      solvedImagesCount: 1,
-      userSitekeyIpHash: 1,
-      simdReadings: 1,
-      dnsEvent: 1,
-      currentUrl: 1,
-      iframeUrl: 1,
-      // captchaType is required by the peek-before-consume path
-      // in `CaptchaManager.isValidRequest` — without it, every
-      // escalation peek would compare `undefined !== <requested>`
-      // and forcibly return INCORRECT_CAPTCHA_TYPE on the happy
-      // path too. Keep this projection in sync with whatever
-      // fields the read-only callers need.
-      captchaType: 1,
-      "headers.user-agent": 1,
-      "headers.accept": 1,
-      "headers.accept-language": 1,
-      "headers.accept-encoding": 1,
-      "headers.sec-ch-ua": 1,
-      "headers.sec-ch-ua-mobile": 1,
-      "headers.sec-ch-ua-platform": 1,
-      "headers.sec-ch-ua-platform-version": 1,
-      "headers.sec-fetch-dest": 1,
-      "headers.sec-fetch-mode": 1,
-      "headers.sec-fetch-site": 1,
-      "headers.sec-fetch-user": 1,
-      "headers.referer": 1,
-      "headers.origin": 1,
-      "headers.prosopo-user": 1,
-      "headers.prosopo-site-key": 1,
-      "headers.prosopo-type": 1,
-      "headers.x-tls-version": 1
-    }).lean();
-    return doc || void 0;
-  }
-  /**
-   * Get a session record by token
-   * Used to ensure that a token is not used more than once.
-   */
-  async getSessionRecordByToken(token) {
-    const filter = { token };
-    const record = await this.tables.session.findOne(filter).lean();
-    return record || void 0;
-  }
-  /**
-   * Check if a session exists and mark it as removed
-   * @returns The session record if it existed, undefined otherwise
-   */
-  async checkAndRemoveSession(sessionId) {
-    this.logger.debug(() => ({
-      data: { action: "checking and removing", sessionId }
-    }));
-    const filter = {
-      sessionId,
-      deleted: { $exists: false }
-    };
-    try {
-      const session = await this.tables.session.findOneAndUpdate(filter, {
-        deleted: true,
-        lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-        pendingStage: true
-      }).lean();
-      return session || void 0;
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_CHECK_REMOVE_FAILED", {
-        context: { error: err, sessionId },
-        logger: this.logger
-      });
-    }
-  }
-  /**
-   * Update a session record by sessionId. Pure Mongo write — callers in
-   * the provider package are responsible for refreshing the Redis cache
-   * via `RedisWriteQueue.patchCachedSession`, matching the existing
-   * caller-side caching pattern (see `frictionlessTasks.createSession`).
-   */
-  async updateSessionRecord(sessionId, updates, streamToCentral) {
-    try {
-      await this.tables.session.updateOne(
-        { sessionId },
-        {
-          $set: {
-            ...updates,
-            lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-            pendingStage: true
-          }
-        }
-      );
-      if (streamToCentral && this.centralStreamer) {
-        const streamer = this.centralStreamer;
-        const markStored = (ts) => this.tables.session.updateOne(
-          { sessionId, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        });
-        this.tables.session.findOne({ sessionId }).lean().then((record) => {
-          if (record) {
-            streamer.streamSessionRecord(record, markStored);
-          }
-        }).catch(() => {
-        });
-      }
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
-        context: { error: err, sessionId },
-        logger: this.logger
-      });
-    }
-  }
-  /**
-   * Atomically record SIMD CPU fingerprint readings on the session — only
-   * if they aren't already present. Uses a Mongo aggregation-pipeline
-   * update so `simdReadings` and `simdReadingsStage` are set together,
-   * first-hop-wins. Pure Mongo write — cache refresh is the caller's
-   * responsibility via `RedisWriteQueue.patchCachedSimdReadingsIfAbsent`.
-   */
-  async recordSessionSimdReadingsIfAbsent(sessionId, readings, stage) {
-    try {
-      await this.tables.session.updateOne({ sessionId }, [
-        {
-          $set: {
-            simdReadings: { $ifNull: ["$simdReadings", readings] },
-            simdReadingsStage: { $ifNull: ["$simdReadingsStage", stage] },
-            lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-            pendingStage: true
-          }
-        }
-      ]);
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
-        context: { error: err, sessionId, stage },
-        logger: this.logger
-      });
-    }
-  }
-  /**
-   * Merge a DNS sidecar observation into the session's `dnsEvent` subdoc
-   * using dotted-path `$set` so DNS-leg and HTTP-leg events on the same
-   * session don't clobber each other. Replaces the prior read-modify-write
-   * pattern that lost half the fields under any race (and 100% of the time
-   * when the read projection didn't include `dnsEvent`).
-   *
-   * `receivedAtIfAbsent` is written only on the first hit for a session
-   * via a `$cond` in an aggregation-pipeline update; later events leave
-   * the original timestamp alone.
-   */
-  async mergeSessionDnsEvent(sessionId, fields, receivedAtIfAbsent) {
-    const setStage = {
-      "dnsEvent.receivedAt": {
-        $ifNull: ["$dnsEvent.receivedAt", receivedAtIfAbsent]
-      },
-      lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-      pendingStage: true
-    };
-    if (fields.resolverIp !== void 0) {
-      setStage["dnsEvent.resolverIp"] = fields.resolverIp;
-    }
-    if (fields.peerIp !== void 0) {
-      setStage["dnsEvent.peerIp"] = fields.peerIp;
-    }
-    if (fields.pathValid !== void 0) {
-      setStage["dnsEvent.pathValid"] = fields.pathValid;
-    }
-    try {
-      const result = await this.tables.session.updateOne({ sessionId }, [
-        { $set: setStage }
-      ]);
-      return result.matchedCount > 0;
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
-        context: { error: err, sessionId },
-        logger: this.logger
-      });
-    }
-  }
-  /**
-   * Get an active session by user IP hash
-   * @param userSitekeyIpHash The hash of user, IP and sitekey combination
-   * @returns The session record if it exists and is not deleted, undefined otherwise
-   */
-  async getSessionByuserSitekeyIpHash(userSitekeyIpHash) {
-    this.logger.debug(() => ({
-      data: { action: "getting session by user IP hash", userSitekeyIpHash }
-    }));
-    const filter = {
-      userSitekeyIpHash,
-      deleted: { $exists: false }
-    };
-    try {
-      const session = await this.tables.session.findOne(filter).lean();
-      return session || void 0;
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
-        context: { error: err, userSitekeyIpHash },
-        logger: this.logger
-      });
-    }
-  }
-  /** Get unstored session records
-   * @description Get session records that have not been stored yet.
-   *
-   * Served by the `pendingStage_partial` index — see
-   * `getUnstoredDappUserCommitments` for the lifecycle of the flag.
-   * `checkAndRemoveSession` also flips the flag so consumed sessions
-   * propagate to the central DB via the next sweep.
-   * @param limit
-   * @param skip
-   */
-  getUnstoredSessionRecords(limit = 1e3, skip = 0) {
-    return Promise.resolve(this.tables?.session).then(
-      (tbl) => tbl?.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean()
-    ).then((docs) => docs || []);
-  }
-  /** Mark a list of session records as stored.
-   *
-   * `asOfTimestamp` defaults to "now" but the sweep should pass the time
-   * at which it fetched the batch. See markDappUserCommitmentsStored for
-   * the guard rationale.
-   */
-  async markSessionRecordsStored(sessionIds, asOfTimestamp = /* @__PURE__ */ new Date()) {
-    await this.tables?.session.updateMany(
-      {
-        sessionId: { $in: sessionIds },
-        lastUpdatedTimestamp: { $lte: asOfTimestamp }
-      },
-      {
-        $set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
-        $unset: { pendingStage: 1 }
-      },
-      { upsert: false }
-    );
-  }
-  /**
-   * @description Store a Dapp User's pending record
-   */
-  async storePendingImageCommitment(userAccount, requestHash, salt, deadlineTimestamp, requestedAtTimestamp, ipAddress, threshold, sessionId, ipInfo) {
-    if (!isHex(requestHash)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: {
-          failedFuncName: this.storePendingImageCommitment.name,
-          requestHash
-        }
-      });
-    }
-    const pendingRecord = {
-      userAccount,
-      pending: true,
-      salt,
-      requestHash,
-      deadlineTimestamp,
-      requestedAtTimestamp,
-      ipAddress,
-      sessionId,
-      threshold,
-      ipInfo,
-      // Deliberately NOT setting pendingStage here. Placeholder
-      // records have id: "" until the user submits a solution; if we
-      // flag them, the sweep picks them up via the partial index but
-      // then `markDappUserCommitmentsStored` runs
-      // `{ id: { $in: ["", ...] } }` which collapses to a single ""
-      // bound and scans every empty-id row via the `id_-1` index —
-      // turning a cheap sweep into a fresh cache evictor. The real
-      // commitment only gets `pendingStage: true` once `id` is
-      // populated by approve/disapprove, at which point staging it is
-      // meaningful.
-      // Placeholder fields required by schema but not needed for pending state
-      dappAccount: "",
-      providerAccount: "",
-      datasetId: "",
-      id: "",
-      // id is populated by the user's solution record when the user submits a solution, so we can leave it blank here
-      result: { status: CaptchaStatus.pending },
-      headers: {},
-      ja4: "",
-      userSignature: "",
-      userSubmitted: false,
-      serverChecked: false
-    };
-    await this.tables?.commitment.updateOne(
-      { requestHash },
-      { $set: pendingRecord },
-      { upsert: true }
-    );
-  }
-  /**
-   * @description Get a user's pending record
-   */
-  async getPendingImageCommitment(requestHash) {
-    if (!isHex(requestHash)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: {
-          failedFuncName: this.getPendingImageCommitment.name,
-          requestHash
-        }
-      });
-    }
-    const doc = await this.tables?.commitment.findOne({
-      requestHash,
-      pending: true
-    }).lean();
-    if (doc) {
-      return {
-        dappAccount: doc.dappAccount,
-        pending: doc.pending,
-        salt: doc.salt,
-        requestHash: doc.requestHash,
-        deadlineTimestamp: doc.deadlineTimestamp,
-        requestedAtTimestamp: doc.requestedAtTimestamp,
-        ipAddress: doc.ipAddress,
-        sessionId: doc.sessionId,
-        threshold: doc.threshold
-      };
-    }
-    throw new ProsopoDBError("DATABASE.PENDING_RECORD_NOT_FOUND", {
-      context: {
-        failedFuncName: this.getPendingImageCommitment.name,
-        requestHash
-      }
-    });
-  }
-  /**
-   * @description Mark a pending request as used
-   */
-  async updatePendingImageCommitmentStatus(requestHash) {
-    if (!isHex(requestHash)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: {
-          failedFuncName: this.updatePendingImageCommitmentStatus.name,
-          requestHash
-        }
-      });
-    }
-    await this.tables?.commitment.updateOne(
-      { requestHash },
-      {
-        $set: {
-          pending: false
-        }
-      }
-    );
-  }
-  /**
-   * @description Get all unsolved captchas
-   */
-  async getAllCaptchasByDatasetId(datasetId, state) {
-    const filter = {
-      datasetId,
-      solved: state === CaptchaStates.Solved
-    };
-    const cursor = this.tables?.captcha.find(filter).lean();
-    const docs = await cursor;
-    if (docs) {
-      return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
-    }
-    throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED");
-  }
-  /**
-   * @description Get all dapp user solutions by captchaIds
-   */
-  async getAllDappUserSolutions(captchaId) {
-    const filter = {
-      captchaId: { $in: captchaId }
-    };
-    const cursor = this.tables?.usersolution?.find(filter).lean();
-    const docs = await cursor;
-    if (docs) {
-      return docs.map(
-        ({ _id, ...keepAttrs }) => keepAttrs
-      );
-    }
-    throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED");
-  }
-  async getDatasetIdWithSolvedCaptchasOfSizeN(solvedCaptchaCount) {
-    const cursor = this.tables?.solution.aggregate([
-      {
-        $match: {}
-      },
-      {
-        $group: {
-          _id: "$datasetId",
-          count: { $sum: 1 }
-        }
-      },
-      {
-        $match: {
-          count: { $gte: solvedCaptchaCount }
-        }
-      },
-      {
-        $sample: { size: 1 }
-      }
-    ]);
-    const docs = await cursor;
-    if (docs?.length) {
-      return docs[0]._id;
-    }
-    throw new ProsopoDBError("DATABASE.DATASET_WITH_SOLUTIONS_GET_FAILED");
-  }
-  async getRandomSolvedCaptchasFromSingleDataset(datasetId, size) {
-    if (!isHex(datasetId)) {
-      throw new ProsopoDBError("DATABASE.INVALID_HASH", {
-        context: {
-          failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
-          datasetId
-        }
-      });
-    }
-    const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
-    const cursor = this.tables?.solution.aggregate([
-      { $match: { datasetId } },
-      { $sample: { size: sampleSize } },
-      {
-        $project: {
-          captchaId: 1,
-          captchaContentId: 1,
-          solution: 1
-        }
-      }
-    ]);
-    const docs = await cursor;
-    if (docs?.length) {
-      return docs;
-    }
-    throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", {
-      context: {
-        failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
-        datasetId,
-        size
-      }
-    });
-  }
-  /**
-   * @description Get dapp user solution by ID
-   * @param {string[]} commitmentId
-   */
-  async getDappUserSolutionById(commitmentId) {
-    const filter = {
-      commitmentId
-    };
-    const project = { _id: 0 };
-    const cursor = this.tables?.usersolution?.findOne(filter, project).lean();
-    const doc = await cursor;
-    if (doc) {
-      return doc;
-    }
-    throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", {
-      context: { failedFuncName: this.getCaptchaById.name, commitmentId }
-    });
-  }
-  /**
-   * @description Get dapp user commitment by user account
-   * @param commitmentId
-   */
-  async getDappUserCommitmentById(commitmentId) {
-    const filter = { id: commitmentId };
-    const commitmentCursor = this.tables?.commitment?.findOne(filter, {
-      id: 1,
-      result: 1,
-      serverChecked: 1,
-      requestedAtTimestamp: 1,
-      submittedAtTimestamp: 1,
-      verifiedAtTimestamp: 1,
-      failedAtTimestamp: 1,
-      ipAddress: 1,
-      sessionId: 1,
-      userAccount: 1,
-      dappAccount: 1,
-      headers: 1,
-      ipInfo: 1
-    }).lean();
-    const doc = await commitmentCursor;
-    return doc ? doc : void 0;
-  }
-  /**
-   * @description Get dapp user commitment by user account
-   * @param {string} userAccount
-   * @param {string} dappAccount
-   */
-  async getDappUserCommitmentByAccount(userAccount, dappAccount) {
-    const filter = {
-      userAccount,
-      dappAccount
-    };
-    const project = {
-      _id: 0,
-      result: 1
-    };
-    const sort = { sort: { _id: -1 } };
-    const docs = await this.tables?.commitment?.find(filter, project, sort).lean();
-    return docs ? docs : [];
-  }
-  /**
-   * @description Approve a dapp user's solution
-   * @param {string[]} commitmentId
-   * @param coords
-   */
-  async approveDappUserCommitment(commitmentId, coords) {
-    try {
-      const result = { status: CaptchaStatus.approved };
-      const updateDoc = {
-        result,
-        lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-        pendingStage: true,
-        ...coords ? { coords } : {}
-      };
-      const filter = { id: commitmentId };
-      await this.tables?.commitment?.findOneAndUpdate(filter, { $set: updateDoc }, { upsert: false }).lean();
-      this.centralStreamer?.streamImageUpdate(
-        () => this.tables.commitment.findOne({ id: commitmentId }).lean(),
-        (ts) => this.tables.commitment.updateOne(
-          { id: commitmentId, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", {
-        context: { error: err, commitmentId }
-      });
-    }
-  }
-  /**
-   * @description Disapprove a dapp user's solution
-   * @param {string} commitmentId
-   * @param coords
-   * @param reason
-   */
-  async disapproveDappUserCommitment(commitmentId, reason, coords) {
-    try {
-      const updateDoc = {
-        result: { status: CaptchaStatus.disapproved, reason },
-        lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
-        pendingStage: true,
-        ...coords ? { coords } : {}
-      };
-      const filter = { id: commitmentId };
-      await this.tables?.commitment?.findOneAndUpdate(filter, { $set: updateDoc }, { upsert: false }).lean();
-      this.centralStreamer?.streamImageUpdate(
-        () => this.tables.commitment.findOne({ id: commitmentId }).lean(),
-        (ts) => this.tables.commitment.updateOne(
-          { id: commitmentId, lastUpdatedTimestamp: { $lte: ts } },
-          {
-            $set: { storedAtTimestamp: ts },
-            $unset: { pendingStage: 1 }
-          }
-        ).then(() => {
-        })
-      );
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", {
-        context: { error: err, commitmentId }
-      });
-    }
-  }
-  /**
-   * @description Flag a dapp user's solutions as used by calculated solution
-   * @param {string[]} captchaIds
-   */
-  async flagProcessedDappUserSolutions(captchaIds) {
-    try {
-      await this.tables?.usersolution?.updateMany(
-        { captchaId: { $in: captchaIds } },
-        { $set: { processed: true } },
-        { upsert: false }
-      ).lean();
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.SOLUTION_FLAG_FAILED", {
-        context: { error: err, captchaIds }
-      });
-    }
-  }
-  /**
-   * @description Flag dapp users' commitments as used by calculated solution
-   * @param {string[]} commitmentIds
-   */
-  async flagProcessedDappUserCommitments(commitmentIds) {
-    try {
-      const distinctCommitmentIds = [...new Set(commitmentIds)];
-      await this.tables?.commitment?.updateMany(
-        { id: { $in: distinctCommitmentIds } },
-        { $set: { processed: true } },
-        { upsert: false }
-      ).lean();
-    } catch (err) {
-      throw new ProsopoDBError("DATABASE.COMMITMENT_FLAG_FAILED", {
-        context: { error: err, commitmentIds }
-      });
-    }
-  }
-  /**
-   * @description Get a scheduled task status record by task ID and status
-   */
-  async getScheduledTaskStatus(taskId, status) {
-    const filter = {
-      _id: taskId,
-      status
-    };
-    const cursor = await this.tables?.scheduler?.findOne(filter).lean();
-    return cursor ? cursor : void 0;
-  }
-  /**
-   * @description Get the most recent scheduled task status record for a given task
-   */
-  async getLastScheduledTaskStatus(task, status) {
-    const filter = { processName: task };
-    if (status) {
-      filter.status = status;
-    }
-    const sort = {
-      datetime: -1
-    };
-    const cursor = await this.tables?.scheduler?.findOne(filter).sort(sort).limit(1).lean();
-    return cursor ? cursor : void 0;
-  }
-  /**
-   * @description Create the status of a scheduled task
-   */
-  async createScheduledTaskStatus(taskName, status) {
-    const now = /* @__PURE__ */ new Date();
-    const doc = ScheduledTaskSchema.parse({
-      processName: taskName,
-      datetime: now,
-      status
-    });
-    const taskRecord = await this.tables?.scheduler.create(doc);
-    return taskRecord._id;
-  }
-  /**
-   * @description Update the status of a scheduled task and an optional result
-   */
-  async updateScheduledTaskStatus(taskId, status, result) {
-    const update = {
-      status,
-      updated: /* @__PURE__ */ new Date(),
-      ...result && { result }
-    };
-    const filter = { _id: taskId };
-    await this.tables?.scheduler.updateOne(
-      filter,
-      { $set: update },
-      {
-        upsert: false
-      }
-    );
-  }
-  /**
-   * @description Clean up the scheduled task status records
-   */
-  async cleanupScheduledTaskStatus(status) {
-    const filter = {
-      status
-    };
-    await this.tables?.scheduler.deleteMany(filter);
-  }
-  /**
-   * @description Update the client records
-   */
-  async updateClientRecords(clientRecords) {
-    const ops = clientRecords.map((record) => {
-      const clientRecord = {
-        account: record.account,
-        settings: record.settings,
-        tier: record.tier
-      };
-      const filter = {
-        account: record.account
-      };
-      return {
-        updateOne: {
-          filter,
-          update: {
-            $set: clientRecord
-          },
-          upsert: true
-        }
-      };
-    });
-    if (!ops || ops.length === 0) {
-      await this.logger.debug(() => ({ msg: "No client updates to apply" }));
-      return;
-    }
-    await this.tables?.client.bulkWrite(ops);
-  }
-  /**
-   * @description Remove client records by account
-   */
-  async removeClientRecords(accounts) {
-    if (!accounts || accounts.length === 0) {
-      return;
-    }
-    await this.tables?.client.deleteMany({
-      account: { $in: accounts }
-    });
-  }
-  /**
-   * @description Get all client records
-   */
-  async getAllClientRecords() {
-    const docs = await this.tables?.client.find().lean();
-    return docs || [];
-  }
-  /**
-   * @description Get a client record
-   */
-  async getClientRecord(account) {
-    const filter = { account };
-    const doc = await this.tables?.client.findOne(filter, {
-      account: 1,
-      settings: 1,
-      tier: 1
-    }).lean();
-    return doc ? doc : void 0;
-  }
-  /**
-   * @description Store a detector key
-   */
-  async storeDetectorKey(detectorKey) {
-    return this.tables?.detector.create({
-      detectorKey,
-      createdAt: /* @__PURE__ */ new Date()
-    });
-  }
-  /**
-   * @description Remove a detector key
-   * @param detectorKey The detector key to remove
-   * @param expirationInSeconds Optional expiration time in seconds (default is 10 minutes)
-   * */
-  async removeDetectorKey(detectorKey, expirationInSeconds) {
-    const filter = { detectorKey };
-    const expiresAt = new Date(
-      Date.now() + (expirationInSeconds || 10 * 60) * 1e3
-    );
-    await this.tables?.detector.updateOne(filter, {
-      $set: { expiresAt }
-    });
-  }
-  /**
-   * @description Get valid detector keys
-   */
-  async getDetectorKeys() {
-    const keyRecords = await this.tables?.detector.find(
-      {
-        $or: [{ expiresAt: { $exists: false } }, { expiresAt: null }]
-      },
-      { detectorKey: 1 }
-    ).sort({ createdAt: -1 }).lean();
-    return (keyRecords || []).map((record) => record.detectorKey);
-  }
-  /**
-   * Stores a decision machine artifact with a unique scope identifier.
-   *
-   * The combination of scope + dappAccount uniquely identifies a single artifact:
-   * - Global scope: One artifact per provider (dappAccount is null)
-   * - Dapp scope: One artifact per dapp account (dappAccount is specified)
-   *
-   * @param artifact - The decision machine artifact to store
-   */
-  async upsertDecisionMachineArtifact(artifact) {
-    const now = /* @__PURE__ */ new Date();
-    const dappAccount = artifact.dappAccount ?? null;
-    const kind = artifact.kind ?? DecisionMachineKind.Routing;
-    const filter = {
-      scope: artifact.scope,
-      dappAccount,
-      kind
-    };
-    await this.tables?.decisionMachine.updateOne(
-      filter,
-      {
-        $set: {
-          scope: artifact.scope,
-          dappAccount,
-          kind,
-          runtime: artifact.runtime,
-          language: artifact.language,
-          source: artifact.source,
-          name: artifact.name,
-          version: artifact.version,
-          captchaType: artifact.captchaType,
-          updatedAt: now
-        },
-        $setOnInsert: {
-          createdAt: now
-        }
-      },
-      { upsert: true }
-    );
-  }
-  /**
-   * Retrieves a single decision machine artifact by scope and optional dapp account.
-   *
-   * @param scope - The scope level (Global or Dapp)
-   * @param dappAccount - Required for Dapp scope, unused for Global scope
-   * @returns The matching artifact, or undefined if not found
-   */
-  async getDecisionMachineArtifact(scope, dappAccount, kind) {
-    const filter = {
-      scope,
-      dappAccount: dappAccount ?? null
-    };
-    if (kind !== void 0) {
-      filter.kind = kind;
-    }
-    const doc = await this.tables?.decisionMachine.findOne(filter).lean();
-    return doc ?? void 0;
-  }
-  /**
-   * Retrieves all decision machine artifacts.
-   *
-   * @returns Array of all decision machine artifacts
-   */
-  async getAllDecisionMachineArtifacts() {
-    const docs = await this.tables?.decisionMachine.find({}).lean();
-    return docs ?? [];
-  }
-  /**
-   * Retrieves a single decision machine artifact by MongoDB ObjectId.
-   *
-   * @param id - The MongoDB ObjectId as a string
-   * @returns The matching artifact, or undefined if not found
-   */
-  async getDecisionMachineArtifactById(id) {
-    const doc = await this.tables?.decisionMachine.findById(id).lean();
-    return doc ?? void 0;
-  }
-  /**
-   * Removes a decision machine artifact by MongoDB ObjectId.
-   *
-   * @param id - The MongoDB ObjectId as a string
-   * @returns true if deleted, false if not found
-   */
-  async removeDecisionMachineArtifact(id) {
-    const result = await this.tables?.decisionMachine.deleteOne({
-      _id: id
-    });
-    return (result?.deletedCount ?? 0) > 0;
-  }
-  /**
-   * Removes all decision machine artifacts.
-   *
-   * @returns The number of artifacts deleted
-   */
-  async removeAllDecisionMachineArtifacts() {
-    const result = await this.tables?.decisionMachine.deleteMany({});
-    return result?.deletedCount ?? 0;
-  }
-  /**
-   * @description set client context-specific entropy
-   */
-  async setClientContextEntropy(account, contextType, entropy) {
-    const filter = { account, contextType };
-    await this.tables?.clientContextEntropy.updateOne(
-      filter,
-      { $set: { account, contextType, entropy } },
-      { upsert: true }
-    );
-  }
-  /**
-   * @description get client context-specific entropy
-   */
-  async getClientContextEntropy(account, contextType) {
-    const filter = { account, contextType };
-    const doc = await this.tables?.clientContextEntropy.findOne(filter).lean();
-    return doc ? doc.entropy : void 0;
-  }
-  /** Sample captcha records from the database for a specific context */
-  async sampleContextEntropy(sampleSize, siteKey, contextType) {
-    const size = sampleSize ? Math.abs(Math.trunc(sampleSize)) : 1;
-    const max = 1e4;
-    if (size > max) {
-      throw new ProsopoDBError("DATABASE.CAPTCHA_SAMPLE_SIZE_EXCEEDED", {
-        context: {
-          failedFuncName: this.sampleContextEntropy.name,
-          sampleSize
-        }
-      });
-    }
-    const pipeline = [
-      {
-        $match: {
-          dappAccount: siteKey,
-          requestedAtTimestamp: {
-            $gt: new Date((/* @__PURE__ */ new Date()).getTime() - TWENTY_FOUR_HOURS_IN_MS)
-          }
-        }
-      },
-      { $sample: { size: max } },
-      {
-        $lookup: {
-          from: "sessions",
-          localField: "sessionId",
-          foreignField: "sessionId",
-          as: "sessionData"
-        }
-      },
-      {
-        $unwind: {
-          path: "$sessionData",
-          preserveNullAndEmptyArrays: false
-        }
-      }
-    ];
-    if (contextType === ContextType.Webview) {
-      pipeline.push({
-        $match: {
-          "sessionData.webView": true
-        }
-      });
-    } else if (contextType === ContextType.Default) {
-      pipeline.push({
-        $match: {
-          "sessionData.webView": false
-        }
-      });
-    }
-    pipeline.push(
-      { $sample: { size } },
-      {
-        $project: {
-          _id: 0,
-          sessionId: 1
-        }
-      }
-    );
-    const cursor = this.tables?.powcaptcha.aggregate(pipeline);
-    const docs = await cursor;
-    if (docs?.length === 0) {
-      return [];
-    }
-    return (await Promise.all(
-      docs.map(async (doc) => {
-        if (doc.sessionId) {
-          const tokenRecord = await this.getSessionRecordBySessionId(
-            doc.sessionId
-          );
-          return tokenRecord?.decryptedHeadHash;
-        }
-        return void 0;
-      })
-    )).filter((headHash) => headHash !== void 0);
-  }
-  async getSpamEmailDomain(domain) {
-    if (!this.tables?.spamEmailDomain) {
-      throw new ProsopoDBError("DATABASE.DATABASE_IMPORT_ERROR", {
-        context: { failedFuncName: this.getSpamEmailDomain.name }
-      });
-    }
-    const suffixCandidates = buildDomainSuffixCandidates(domain).slice(
-      0,
-      MAX_DOMAIN_SUFFIX_CANDIDATES
-    );
-    const query = suffixCandidates.length > 0 ? { domain: { $in: suffixCandidates } } : { domain };
-    return await this.tables.spamEmailDomain.findOne(query).exec();
-  }
-  async bulkUpdateSpamEmailDomains(domains, upsert) {
-    if (!this.tables?.spamEmailDomain) {
-      throw new ProsopoDBError("DATABASE.DATABASE_IMPORT_ERROR", {
-        context: { failedFuncName: this.bulkUpdateSpamEmailDomains.name }
-      });
-    }
-    const bulkOps = domains.map((op) => ({
-      updateOne: {
-        filter: op.filter,
-        update: { $set: op.update },
-        upsert
-      }
-    }));
-    if (bulkOps.length > 0) {
-      await this.tables.spamEmailDomain.bulkWrite(bulkOps);
-    }
-  }
-}
-export {
-  ProviderDatabase
+var ProviderDatabase = class extends MongoDatabase {
+	constructor(options) {
+		super(options.mongo.url, options.mongo.dbname, options.mongo.authSource, options.logger);
+		this.options = options;
+		this.tables = {};
+		this.indexesEnsured = false;
+		this.tables = {};
+		this.redisAccessRulesConnection = null;
+		this.redisConnection = null;
+		this.userAccessRulesStorage = null;
+	}
+	setCentralDbStreamer(streamer) {
+		this.centralStreamer = streamer;
+	}
+	hasCentralDbStreamer() {
+		return this.centralStreamer !== void 0;
+	}
+	async connect() {
+		await super.connect();
+		this.loadTables();
+		await this.setupRedis();
+	}
+	async setupRedis() {
+		this.redisConnection = connectToRedis({
+			url: this.options.redis?.url,
+			password: this.options.redis?.password,
+			logger: this.logger
+		});
+		this.redisAccessRulesConnection = setupRedisIndex(this.redisConnection, {
+			...accessRulesRedisIndex,
+			name: this.options.redis?.indexName || accessRulesRedisIndex.name
+		}, this.logger);
+		this.userAccessRulesStorage = createRedisAccessRulesStorage(this.redisAccessRulesConnection, this.logger);
+	}
+	loadTables() {
+		const tables = {};
+		PROVIDER_TABLES.map(({ collectionName, modelName, schema }) => {
+			if (this.connection) tables[collectionName] = this.connection.model(modelName, schema);
+		});
+		this.tables = tables;
+	}
+	getTables() {
+		if (!this.tables) throw new ProsopoDBError("DATABASE.TABLES_UNDEFINED", {
+			context: { failedFuncName: this.getTables.name },
+			logger: this.logger
+		});
+		return this.tables;
+	}
+	getRedisAccessRulesConnection() {
+		if (null === this.redisAccessRulesConnection) throw new ProsopoDBError("DATABASE.REDIS_ACCESS_RULES_CONNECTION_UNDEFINED");
+		return this.redisAccessRulesConnection;
+	}
+	getRedisConnection() {
+		if (null === this.redisConnection) throw new ProsopoDBError("DATABASE.REDIS_ACCESS_RULES_CONNECTION_UNDEFINED");
+		return this.redisConnection;
+	}
+	async ensureIndexes() {
+		const indexPromises = [];
+		if (!this.indexesEnsured) PROVIDER_TABLES.map(({ collectionName }) => {
+			indexPromises.push(new Promise((resolve) => {
+				if (this.connected) this.tables[collectionName].collection.dropIndexes().then(() => {
+					this.tables[collectionName].ensureIndexes().then(() => {
+						this.logger.info(() => ({ msg: `Indexes ensured for collection ${collectionName}` }));
+						resolve();
+					}).catch((err) => {
+						this.logger.warn(() => ({
+							err,
+							msg: `Error creating indexes for collection ${collectionName}`
+						}));
+						resolve();
+					});
+				});
+				else {
+					this.logger.info(() => ({ msg: `Skipping index creation for collection ${collectionName} as not connected` }));
+					resolve();
+				}
+			}));
+		});
+		await Promise.all(indexPromises);
+		this.indexesEnsured = true;
+	}
+	getUserAccessRulesStorage() {
+		if (null === this.userAccessRulesStorage) throw new ProsopoDBError("DATABASE.USER_ACCESS_RULES_STORAGE_UNDEFINED");
+		return this.userAccessRulesStorage;
+	}
+	/**
+	* @description Load a dataset to the database
+	* @param {Dataset}  dataset
+	*/
+	async storeDataset(dataset) {
+		try {
+			this.logger.debug(() => ({
+				data: { datasetId: dataset.datasetId },
+				msg: "Storing dataset in database"
+			}));
+			const parsedDataset = DatasetWithIdsAndTreeSchema.parse(dataset);
+			const datasetDoc = {
+				datasetId: parsedDataset.datasetId,
+				datasetContentId: parsedDataset.datasetContentId,
+				format: parsedDataset.format,
+				contentTree: parsedDataset.contentTree,
+				solutionTree: parsedDataset.solutionTree
+			};
+			const filter = { datasetId: parsedDataset.datasetId };
+			await this.tables.dataset?.updateOne(filter, { $set: datasetDoc }, { upsert: true });
+			const captchaDocs = parsedDataset.captchas.map(({ solution, ...captcha }, index) => ({
+				...captcha,
+				datasetId: parsedDataset.datasetId,
+				datasetContentId: parsedDataset.datasetContentId,
+				index,
+				solved: !!solution?.length
+			}));
+			this.logger.debug(() => ({ msg: "Inserting captcha records" }));
+			if (captchaDocs.length) await this.tables?.captcha.bulkWrite(captchaDocs.map((captchaDoc) => ({ updateOne: {
+				filter: { captchaId: captchaDoc.captchaId },
+				update: {
+					$set: captchaDoc,
+					$setOnInsert: { randomKey: Math.random() }
+				},
+				upsert: true
+			} })));
+			const captchaSolutionDocs = parsedDataset.captchas.filter(({ solution }) => solution?.length).map((captcha) => ({
+				captchaId: captcha.captchaId,
+				captchaContentId: captcha.captchaContentId,
+				solution: captcha.solution,
+				salt: captcha.salt,
+				datasetId: parsedDataset.datasetId,
+				datasetContentId: parsedDataset.datasetContentId
+			}));
+			this.logger.debug(() => ({ msg: "Inserting solution records" }));
+			if (captchaSolutionDocs.length) await this.tables?.solution.bulkWrite(captchaSolutionDocs.map((captchaSolutionDoc) => ({ updateOne: {
+				filter: { captchaId: captchaSolutionDoc.captchaId },
+				update: { $set: captchaSolutionDoc },
+				upsert: true
+			} })));
+			this.logger.debug(() => ({ msg: "Dataset stored in database" }));
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.DATASET_LOAD_FAILED", {
+				context: {
+					failedFuncName: this.storeDataset.name,
+					error: err
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/** @description Get solutions for a dataset
+	* @param {string} datasetId
+	*/
+	async getSolutions(datasetId) {
+		const filter = { datasetId };
+		const docs = await this.tables?.solution.find(filter).lean();
+		return docs ? docs : [];
+	}
+	/** @description Get a solution by captcha id
+	* @param {string} captchaId
+	*/
+	async getSolutionByCaptchaId(captchaId) {
+		const filter = { captchaId };
+		return await this.tables?.solution.findOne(filter).lean() || null;
+	}
+	/** @description Get a dataset from the database
+	* @param {string} datasetId
+	*/
+	async getDataset(datasetId) {
+		const filter = { datasetId };
+		const datasetDoc = await this.tables?.dataset.findOne(filter).lean();
+		if (datasetDoc) {
+			const { datasetContentId, format, contentTree, solutionTree } = datasetDoc;
+			const captchas = await this.tables?.captcha.find(filter).lean() || [];
+			const solutions = await this.tables?.solution.find(filter).lean() || [];
+			const solutionsKeyed = {};
+			for (const solution of solutions) solutionsKeyed[solution.captchaId] = solution;
+			return {
+				datasetId,
+				datasetContentId,
+				format,
+				contentTree: contentTree || [],
+				solutionTree: solutionTree || [],
+				captchas: captchas.map((captchaDoc) => {
+					const { captchaId, captchaContentId, items, target, salt, solved } = captchaDoc;
+					const solution = solutionsKeyed[captchaId];
+					return {
+						captchaId,
+						captchaContentId,
+						solved: !!solved,
+						salt,
+						items,
+						target,
+						solution: solved && solution ? solution.solution : []
+					};
+				})
+			};
+		}
+		throw new ProsopoDBError("DATABASE.DATASET_GET_FAILED", { context: {
+			failedFuncName: this.getDataset.name,
+			datasetId
+		} });
+	}
+	/**
+	* @description Get random captchas that are solved or not solved
+	* @param {boolean}  solved    `true` when captcha is solved
+	* @param {string}   datasetId  the id of the data set
+	* @param {number}   size       the number of records to be returned
+	*/
+	async getRandomCaptcha(solved, datasetId, size) {
+		if (!isHex(datasetId)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.getRandomCaptcha.name,
+			datasetId
+		} });
+		const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
+		const projection = {
+			_id: 0,
+			datasetId: 1,
+			datasetContentId: 1,
+			captchaId: 1,
+			captchaContentId: 1,
+			items: 1,
+			target: 1
+		};
+		const baseFilter = {
+			datasetId,
+			solved
+		};
+		const pivot = Math.random();
+		let docs = await this.tables?.captcha.find({
+			...baseFilter,
+			randomKey: { $gte: pivot }
+		}, projection).sort({ randomKey: 1 }).limit(sampleSize).lean() ?? [];
+		if (docs.length < sampleSize) {
+			const tail = await this.tables?.captcha.find({
+				...baseFilter,
+				randomKey: { $lt: pivot }
+			}, projection).sort({ randomKey: 1 }).limit(sampleSize - docs.length).lean() ?? [];
+			docs = docs.concat(tail);
+		}
+		if (docs.length === 0) {
+			const fallback = await this.tables?.captcha.aggregate([
+				{ $match: baseFilter },
+				{ $sample: { size: sampleSize } },
+				{ $project: projection }
+			]).exec() ?? [];
+			if (fallback.length > 0) return fallback.map(({ _id, ...keep }) => keep);
+		}
+		if (docs.length > 0) return docs;
+		throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", { context: {
+			failedFuncName: this.getRandomCaptcha.name,
+			solved,
+			datasetId,
+			size
+		} });
+	}
+	/**
+	* @description Get captchas by id
+	* @param {string[]} captchaId
+	*/
+	async getCaptchaById(captchaId) {
+		const filter = { captchaId: { $in: captchaId } };
+		const docs = await this.tables?.captcha.find(filter, {
+			_id: 0,
+			captchaId: 1,
+			datasetId: 1,
+			items: 1
+		}).lean();
+		if (docs?.length) return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+		throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", { context: {
+			failedFuncName: this.getCaptchaById.name,
+			captchaId
+		} });
+	}
+	/**
+	* @description Update a captcha
+	* @param {Captcha}  captcha
+	* @param {string}   datasetId  the id of the data set
+	*/
+	async updateCaptcha(captcha, datasetId) {
+		if (!isHex(datasetId)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.updateCaptcha.name,
+			datasetId
+		} });
+		try {
+			const filter = { datasetId };
+			await this.tables?.captcha.updateOne(filter, { $set: captcha }, { upsert: false });
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", { context: {
+				failedFuncName: this.getDatasetDetails.name,
+				error: err
+			} });
+		}
+	}
+	/**
+	* @description Remove captchas
+	*/
+	async removeCaptchas(captchaIds) {
+		const filter = { captchaId: { $in: captchaIds } };
+		await this.tables?.captcha.deleteMany(filter);
+	}
+	/**
+	* @description Get a dataset by Id
+	*/
+	/**
+	* Returns the most recently uploaded dataset's ID. Used as the per-provider
+	* default when a client doesn't pin a specific dataset (which it can't
+	* under DNS-based routing — clients don't know which provider they'll hit).
+	*/
+	async getMostRecentDatasetId() {
+		const datasetId = (await this.tables?.dataset.findOne().sort({ _id: -1 }).lean())?.datasetId;
+		return typeof datasetId === "string" ? datasetId : void 0;
+	}
+	async getDatasetDetails(datasetId) {
+		if (!isHex(datasetId)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.getDatasetDetails.name,
+			datasetId
+		} });
+		const filter = { datasetId };
+		const doc = await this.tables?.dataset.findOne(filter).lean();
+		if (doc) return doc;
+		throw new ProsopoDBError("DATABASE.DATASET_GET_FAILED", { context: {
+			failedFuncName: this.getDatasetDetails.name,
+			datasetId
+		} });
+	}
+	/**
+	* @description Store a Dapp User's captcha solution commitment
+	*/
+	async storeUserImageCaptchaSolution(captchas, commit) {
+		const commitmentRecord = UserCommitmentSchema.parse({
+			...commit,
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date()
+		});
+		if (captchas.length) {
+			const filter = { id: commit.id };
+			await this.tables?.commitment.updateOne(filter, commitmentRecord, { upsert: true });
+			const ops = captchas.map((captcha) => ({ updateOne: {
+				filter: {
+					commitmentId: commit.id,
+					captchaId: captcha.captchaId
+				},
+				update: { $set: {
+					captchaId: captcha.captchaId,
+					captchaContentId: captcha.captchaContentId,
+					salt: captcha.salt,
+					solution: captcha.solution,
+					commitmentId: commit.id,
+					processed: false
+				} },
+				upsert: true
+			} }));
+			await this.tables?.usersolution.bulkWrite(ops);
+			this.centralStreamer?.streamImageRecord(commitmentRecord, (ts) => this.tables.commitment.updateOne({ id: commit.id }, { $set: { storedAtTimestamp: ts } }).then(() => {}));
+		}
+	}
+	/**
+	* @description Adds a new PoW Captcha record to the database.
+	* @param {string} challenge The challenge string for the captcha.
+	* @param components The components of the PoW challenge.
+	* @param difficulty
+	* @param providerSignature
+	* @param ipAddress
+	* @param headers
+	* @param ja4
+	* @param sessionId
+	* @param serverChecked
+	* @param userSubmitted
+	* @param storedStatus
+	* @param userSignature
+	* @param ipInfo full ipinfo payload from the ipInfoMiddleware
+	* @returns {Promise<void>} A promise that resolves when the record is added.
+	*/
+	async storePowCaptchaRecord(challenge, components, difficulty, providerSignature, ipAddress, headers, ja4, sessionId, serverChecked = false, userSubmitted = false, userSignature, ipInfo) {
+		const tables = this.getTables();
+		const powCaptchaRecord = {
+			challenge,
+			userAccount: components.userAccount,
+			dappAccount: components.dappAccount,
+			requestedAtTimestamp: new Date(components.requestedAtTimestamp),
+			ipAddress,
+			headers,
+			ja4,
+			result: { status: CaptchaStatus.pending },
+			userSubmitted,
+			serverChecked,
+			difficulty,
+			providerSignature,
+			userSignature,
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+			pendingStage: true,
+			sessionId,
+			ipInfo
+		};
+		try {
+			await tables.powcaptcha.create(powCaptchaRecord);
+			this.logger.info(() => ({
+				data: {
+					challenge,
+					userSubmitted,
+					serverChecked,
+					countryCode: ipInfo?.isValid ? ipInfo.countryCode : void 0
+				},
+				msg: "PowCaptcha record added successfully"
+			}));
+			this.centralStreamer?.streamPowRecord(powCaptchaRecord, (ts) => this.tables.powcaptcha.updateOne({
+				challenge,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+				context: {
+					error,
+					challenge,
+					userSubmitted,
+					serverChecked,
+					ipInfo
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err: error,
+				msg: "Failed to add PowCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	/**
+	* @description Retrieves a PoW Captcha record by its challenge string.
+	* @param {string} challenge The challenge string to search for.
+	* @returns {Promise<PoWCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
+	*/
+	async getPowCaptchaRecordByChallenge(challenge) {
+		if (!this.tables) throw new ProsopoDBError("DATABASE.DATABASE_UNDEFINED", {
+			context: { failedFuncName: this.getPowCaptchaRecordByChallenge.name },
+			logger: this.logger
+		});
+		try {
+			const filter = { challenge };
+			const record = await this.tables.powcaptcha.findOne(filter, {
+				challenge: 1,
+				userAccount: 1,
+				dappAccount: 1,
+				requestedAtTimestamp: 1,
+				submittedAtTimestamp: 1,
+				verifiedAtTimestamp: 1,
+				failedAtTimestamp: 1,
+				ipAddress: 1,
+				headers: 1,
+				ja4: 1,
+				result: 1,
+				difficulty: 1,
+				sessionId: 1,
+				ipInfo: 1,
+				deviceCapability: 1,
+				behavioralDataPacked: 1,
+				serverChecked: 1,
+				userSubmitted: 1,
+				coords: 1
+			}).lean();
+			if (record) {
+				this.logger.info(() => ({
+					data: { challenge },
+					msg: "PowCaptcha record retrieved successfully"
+				}));
+				return record;
+			}
+			this.logger.info(() => ({
+				data: { challenge },
+				msg: "No PowCaptcha record found"
+			}));
+			return null;
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+				context: {
+					error,
+					challenge
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err,
+				msg: "Failed to retrieve PowCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	/**
+	* @description Updates a PoW Captcha record in the database.
+	* @param {string} challenge The challenge string of the captcha to be updated.
+	* @param result
+	* @param serverChecked
+	* @param userSubmitted
+	* @param userSignature
+	* @returns {Promise<void>} A promise that resolves when the record is updated.
+	*/
+	async updatePowCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords) {
+		const tables = this.getTables();
+		const timestamp = /* @__PURE__ */ new Date();
+		const isDisapproved = result.status === CaptchaStatus.disapproved;
+		assertCoordsSafe(coords, "coords");
+		const setStage = {
+			result,
+			serverChecked,
+			userSubmitted,
+			userSignature,
+			lastUpdatedTimestamp: timestamp,
+			pendingStage: true,
+			...coords && { coords }
+		};
+		if (userSubmitted) setStage.submittedAtTimestamp = { $ifNull: ["$submittedAtTimestamp", timestamp] };
+		if (isDisapproved) setStage.failedAtTimestamp = { $ifNull: ["$failedAtTimestamp", timestamp] };
+		try {
+			if ((await tables.powcaptcha.updateOne({ challenge }, [{ $set: setStage }])).matchedCount === 0) {
+				const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+					context: {
+						challenge,
+						...setStage
+					},
+					logger: this.logger
+				});
+				this.logger.info(() => ({
+					err,
+					msg: "No PowCaptcha record found to update"
+				}));
+				throw err;
+			}
+			this.logger.info(() => ({
+				data: {
+					challenge,
+					...setStage
+				},
+				msg: "PowCaptcha record updated successfully"
+			}));
+			this.centralStreamer?.streamPowUpdate(() => this.getPowCaptchaRecordByChallenge(challenge), (ts) => this.tables.powcaptcha.updateOne({
+				challenge,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+				context: {
+					error,
+					challenge,
+					...setStage
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err,
+				msg: "Failed to update PowCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	async updatePowCaptchaRecord(challenge, updates) {
+		await this.getTables().powcaptcha.updateOne({ challenge }, { $set: {
+			...updates,
+			pendingStage: true
+		} }, { upsert: false });
+		this.centralStreamer?.streamPowUpdate(() => this.getPowCaptchaRecordByChallenge(challenge), (ts) => this.tables.powcaptcha.updateOne({
+			challenge,
+			lastUpdatedTimestamp: { $lte: ts }
+		}, {
+			$set: { storedAtTimestamp: ts },
+			$unset: { pendingStage: 1 }
+		}).then(() => {}));
+	}
+	async storePuzzleCaptchaRecord(challenge, components, targetX, targetY, originX, originY, tolerance, providerSignature, ipAddress, headers, ja4, sessionId, ipInfo) {
+		const tables = this.getTables();
+		const puzzleCaptchaRecord = {
+			challenge,
+			userAccount: components.userAccount,
+			dappAccount: components.dappAccount,
+			requestedAtTimestamp: new Date(components.requestedAtTimestamp),
+			ipAddress,
+			headers,
+			ja4,
+			result: { status: CaptchaStatus.pending },
+			userSubmitted: false,
+			serverChecked: false,
+			targetX,
+			targetY,
+			originX,
+			originY,
+			tolerance,
+			providerSignature,
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+			pendingStage: true,
+			sessionId,
+			ipInfo
+		};
+		try {
+			await tables.puzzlecaptcha.create(puzzleCaptchaRecord);
+			this.logger.info(() => ({
+				data: {
+					challenge,
+					countryCode: ipInfo?.isValid ? ipInfo.countryCode : void 0
+				},
+				msg: "PuzzleCaptcha record added successfully"
+			}));
+			this.centralStreamer?.streamPuzzleRecord(puzzleCaptchaRecord, (ts) => this.tables.puzzlecaptcha.updateOne({
+				challenge,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+				context: {
+					error,
+					challenge,
+					ipInfo
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err: error,
+				msg: "Failed to add PuzzleCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	/**
+	* @description Retrieves a Puzzle Captcha record by its challenge string.
+	* @param {string} challenge The challenge string to search for.
+	* @returns {Promise<PuzzleCaptchaRecord | null>} A promise that resolves with the found record or null if not found.
+	*/
+	async getPuzzleCaptchaRecordByChallenge(challenge) {
+		if (!this.tables) throw new ProsopoDBError("DATABASE.DATABASE_UNDEFINED", {
+			context: { failedFuncName: this.getPuzzleCaptchaRecordByChallenge.name },
+			logger: this.logger
+		});
+		try {
+			const filter = { challenge };
+			const record = await this.tables.puzzlecaptcha.findOne(filter, {
+				challenge: 1,
+				userAccount: 1,
+				dappAccount: 1,
+				requestedAtTimestamp: 1,
+				submittedAtTimestamp: 1,
+				ipAddress: 1,
+				headers: 1,
+				ja4: 1,
+				result: 1,
+				targetX: 1,
+				targetY: 1,
+				originX: 1,
+				originY: 1,
+				tolerance: 1,
+				puzzleEvents: 1,
+				sessionId: 1,
+				ipInfo: 1,
+				deviceCapability: 1,
+				behavioralDataPacked: 1,
+				serverChecked: 1,
+				userSubmitted: 1,
+				coords: 1
+			}).lean();
+			if (record) {
+				this.logger.info(() => ({
+					data: { challenge },
+					msg: "PuzzleCaptcha record retrieved successfully"
+				}));
+				return record;
+			}
+			this.logger.info(() => ({
+				data: { challenge },
+				msg: "No PuzzleCaptcha record found"
+			}));
+			return null;
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+				context: {
+					error,
+					challenge
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err,
+				msg: "Failed to retrieve PuzzleCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	/**
+	* @description Updates a Puzzle Captcha record result in the database.
+	* @param {string} challenge The challenge string of the captcha to be updated.
+	* @param result
+	* @param serverChecked
+	* @param userSubmitted
+	* @param userSignature
+	* @param coords
+	* @param lastUpdatedTimestamp
+	* @returns {Promise<void>} A promise that resolves when the record is updated.
+	*/
+	async updatePuzzleCaptchaRecordResult(challenge, result, serverChecked = false, userSubmitted = false, userSignature, coords, lastUpdatedTimestamp) {
+		const tables = this.getTables();
+		const timestamp = lastUpdatedTimestamp ?? /* @__PURE__ */ new Date();
+		const isDisapproved = result.status === CaptchaStatus.disapproved;
+		assertCoordsSafe(coords, "coords");
+		const setStage = {
+			result,
+			serverChecked,
+			userSubmitted,
+			userSignature,
+			lastUpdatedTimestamp: timestamp,
+			pendingStage: true,
+			...coords && { coords },
+			...userSubmitted && { submittedAtTimestamp: timestamp },
+			...isDisapproved && { failedAtTimestamp: timestamp }
+		};
+		try {
+			if ((await tables.puzzlecaptcha.updateOne({ challenge }, { $set: setStage })).matchedCount === 0) {
+				const err = new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED", {
+					context: {
+						challenge,
+						...setStage
+					},
+					logger: this.logger
+				});
+				this.logger.info(() => ({
+					err,
+					msg: "No PuzzleCaptcha record found to update"
+				}));
+				throw err;
+			}
+			this.logger.info(() => ({
+				data: {
+					challenge,
+					...setStage
+				},
+				msg: "PuzzleCaptcha record updated successfully"
+			}));
+			this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), (ts) => this.tables.puzzlecaptcha.updateOne({
+				challenge,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (error) {
+			const err = new ProsopoDBError("DATABASE.CAPTCHA_UPDATE_FAILED", {
+				context: {
+					error,
+					challenge,
+					...setStage
+				},
+				logger: this.logger
+			});
+			this.logger.error(() => ({
+				err,
+				msg: "Failed to update PuzzleCaptcha record"
+			}));
+			throw err;
+		}
+	}
+	async updatePuzzleCaptchaRecord(challenge, updates) {
+		const tables = this.getTables();
+		const timestamp = /* @__PURE__ */ new Date();
+		const baseSet = {
+			...updates,
+			pendingStage: true,
+			...updates.serverChecked === true && { verifiedAtTimestamp: timestamp },
+			...updates.userSubmitted === true && { submittedAtTimestamp: timestamp },
+			...updates.result?.status === CaptchaStatus.disapproved && { failedAtTimestamp: timestamp }
+		};
+		await tables.puzzlecaptcha.updateOne({ challenge }, { $set: baseSet });
+		this.centralStreamer?.streamPuzzleUpdate(() => this.getPuzzleCaptchaRecordByChallenge(challenge), (ts) => this.tables.puzzlecaptcha.updateOne({
+			challenge,
+			lastUpdatedTimestamp: { $lte: ts }
+		}, {
+			$set: { storedAtTimestamp: ts },
+			$unset: { pendingStage: 1 }
+		}).then(() => {}));
+	}
+	/** @description Get serverChecked Dapp User image captcha commitments from the commitments table
+	*/
+	async getCheckedDappUserCommitments() {
+		const filter = { [StoredStatusNames.serverChecked]: true };
+		return await this.tables?.commitment.find(filter).lean() || [];
+	}
+	/** @description Get Dapp User captcha commitments from the commitments table that have not been counted towards the
+	* client's total.
+	*
+	* Served by the `pendingStage_partial` index. Records have
+	* `pendingStage: true` set on insert and on every mutation (see
+	* `updateDappUserCommitment`, `markDappUserCommitmentsChecked`,
+	* `approveDappUserCommitment`, `disapproveDappUserCommitment`,
+	* `storePendingImageCommitment`). `markDappUserCommitmentsStored` clears
+	* the flag after a successful stage, guarded by `lastUpdatedTimestamp`
+	* so an in-flight update isn't lost.
+	*/
+	async getUnstoredDappUserCommitments(limit = 1e3, skip = 0) {
+		return await this.tables?.commitment.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean() || [];
+	}
+	/** @description Mark a list of captcha commits as stored.
+	*
+	* `asOfTimestamp` defaults to "now" but the sweep should pass the time
+	* at which it fetched the batch. The lastUpdatedTimestamp guard prevents
+	* us from clearing pendingStage on a record that was mutated between
+	* fetch and mark-stored — those records will leave pendingStage set so
+	* the next sweep picks them up.
+	*/
+	async markDappUserCommitmentsStored(commitmentIds, asOfTimestamp = /* @__PURE__ */ new Date()) {
+		await this.tables?.commitment.updateMany({
+			id: { $in: commitmentIds },
+			lastUpdatedTimestamp: { $lte: asOfTimestamp }
+		}, {
+			$set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
+			$unset: { pendingStage: 1 }
+		}, { upsert: false });
+	}
+	/** @description Mark a list of captcha commits as checked
+	*/
+	async markDappUserCommitmentsChecked(commitmentIds) {
+		const timestamp = /* @__PURE__ */ new Date();
+		await this.tables?.commitment.updateMany({ id: { $in: commitmentIds } }, [{ $set: {
+			serverChecked: true,
+			lastUpdatedTimestamp: timestamp,
+			pendingStage: true,
+			verifiedAtTimestamp: { $ifNull: ["$verifiedAtTimestamp", timestamp] }
+		} }]);
+	}
+	/** @description Update an image captcha commitment
+	*/
+	async updateDappUserCommitment(commitmentId, updates) {
+		const filter = { id: commitmentId };
+		const timestamp = /* @__PURE__ */ new Date();
+		const baseSet = {
+			...updates,
+			lastUpdatedAtTimestamp: timestamp,
+			pendingStage: true
+		};
+		const pipelineExprs = {};
+		if (updates.userSubmitted === true) pipelineExprs.submittedAtTimestamp = { $ifNull: ["$submittedAtTimestamp", timestamp] };
+		if (updates.serverChecked === true) pipelineExprs.verifiedAtTimestamp = { $ifNull: ["$verifiedAtTimestamp", timestamp] };
+		if (updates.result?.status === CaptchaStatus.disapproved) pipelineExprs.failedAtTimestamp = { $ifNull: ["$failedAtTimestamp", timestamp] };
+		if (Object.keys(pipelineExprs).length === 0) {
+			await this.tables?.commitment.updateOne(filter, { $set: baseSet });
+			return;
+		}
+		await this.tables?.commitment.updateOne(filter, [{ $set: {
+			...baseSet,
+			...pipelineExprs
+		} }]);
+	}
+	/**
+	* @description Get Dapp User PoW captcha commitments that have not been counted towards the client's total
+	* @param {number} limit Maximum number of records to return
+	* @param {number} skip Number of records to skip (for pagination)
+	* @returns {Promise<PoWCaptchaRecord[]>} Array of PoW captcha records
+	*/
+	async getUnstoredDappUserPoWCommitments(limit = 1e3, skip = 0) {
+		return await this.tables?.powcaptcha.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean() || [];
+	}
+	/** @description Mark a list of PoW captcha commits as stored.
+	*
+	* `asOfTimestamp` defaults to "now" but the sweep should pass the time
+	* at which it fetched the batch. See markDappUserCommitmentsStored for
+	* the guard rationale.
+	*/
+	async markDappUserPoWCommitmentsStored(challenges, asOfTimestamp = /* @__PURE__ */ new Date()) {
+		await this.tables?.powcaptcha.updateMany({
+			challenge: { $in: challenges },
+			lastUpdatedTimestamp: { $lte: asOfTimestamp }
+		}, {
+			$set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
+			$unset: { pendingStage: 1 }
+		}, { upsert: false });
+	}
+	/** @description Mark a list of PoW captcha commits as checked by the server
+	*/
+	async markDappUserPoWCommitmentsChecked(challenges) {
+		const timestamp = /* @__PURE__ */ new Date();
+		await this.tables?.powcaptcha.updateMany({ challenge: { $in: challenges } }, [{ $set: {
+			serverChecked: true,
+			lastUpdatedTimestamp: timestamp,
+			pendingStage: true,
+			verifiedAtTimestamp: { $ifNull: ["$verifiedAtTimestamp", timestamp] }
+		} }], { upsert: false });
+	}
+	/**
+	* Store a new session record
+	*/
+	async storeSessionRecord(sessionRecord) {
+		try {
+			this.logger.debug(() => ({ data: {
+				action: "storing",
+				sessionRecord
+			} }));
+			const recordWithFlag = {
+				...sessionRecord,
+				lastUpdatedTimestamp: sessionRecord.lastUpdatedTimestamp ?? sessionRecord.createdAt,
+				pendingStage: true
+			};
+			await this.tables.session.create(recordWithFlag);
+			this.centralStreamer?.streamSessionRecord(recordWithFlag, (ts) => this.tables.session.updateOne({
+				sessionId: sessionRecord.sessionId,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_STORE_FAILED", {
+				context: {
+					error: err,
+					sessionId: sessionRecord.sessionId
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/**
+	* Persist a synthetic Session record for a request that was 401'd at the
+	* request-time block middleware. The record is written with
+	* `blocked=true` + `deleted=true` so the captcha flow can't pick it up
+	* downstream, and with sentinel values for the schema-required fields
+	* the blocked request never had a chance to populate (score / threshold /
+	* captchaType / etc.).
+	*
+	* Designed for fire-and-forget: callers `void`-cast the promise and any
+	* Mongo error is swallowed-and-logged so the 401 response is never
+	* delayed by a persistence failure. The structured log line at the call
+	* site is the source of truth either way.
+	*
+	* Mirrors `storeSessionRecord` enough that the Traffic-page
+	* aggregations can read these records out of the central-streamer
+	* pipeline once the UI work lands.
+	*/
+	async storeBlockedSession(record) {
+		try {
+			const stored = {
+				...record,
+				blocked: true,
+				deleted: true,
+				storedAtTimestamp: record.storedAtTimestamp ?? record.createdAt,
+				lastUpdatedTimestamp: record.lastUpdatedTimestamp ?? record.createdAt
+			};
+			await this.tables.session.create(stored);
+			this.centralStreamer?.streamSessionRecord(stored, (ts) => this.tables.session.updateOne({
+				sessionId: stored.sessionId,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, { $set: { storedAtTimestamp: ts } }).then(() => {}));
+		} catch (err) {
+			this.logger.warn(() => ({
+				err,
+				msg: "Failed to persist blocked session record",
+				data: {
+					sessionId: record.sessionId,
+					siteKey: record.siteKey
+				}
+			}));
+		}
+	}
+	/**
+	* Get a session record by sessionId
+	*/
+	async getSessionRecordBySessionId(sessionId) {
+		const filter = { sessionId };
+		return await this.tables.session.findOne(filter, {
+			sessionId: 1,
+			token: 1,
+			score: 1,
+			threshold: 1,
+			scoreComponents: 1,
+			ipAddress: 1,
+			ipInfo: 1,
+			webView: 1,
+			iFrame: 1,
+			isEscalation: 1,
+			decryptedHeadHash: 1,
+			siteKey: 1,
+			reason: 1,
+			mode: 1,
+			solvedImagesCount: 1,
+			userSitekeyIpHash: 1,
+			simdReadings: 1,
+			dnsEvent: 1,
+			currentUrl: 1,
+			iframeUrl: 1,
+			captchaType: 1,
+			"headers.user-agent": 1,
+			"headers.accept": 1,
+			"headers.accept-language": 1,
+			"headers.accept-encoding": 1,
+			"headers.sec-ch-ua": 1,
+			"headers.sec-ch-ua-mobile": 1,
+			"headers.sec-ch-ua-platform": 1,
+			"headers.sec-ch-ua-platform-version": 1,
+			"headers.sec-fetch-dest": 1,
+			"headers.sec-fetch-mode": 1,
+			"headers.sec-fetch-site": 1,
+			"headers.sec-fetch-user": 1,
+			"headers.referer": 1,
+			"headers.origin": 1,
+			"headers.prosopo-user": 1,
+			"headers.prosopo-site-key": 1,
+			"headers.prosopo-type": 1,
+			"headers.x-tls-version": 1
+		}).lean() || void 0;
+	}
+	/**
+	* Get a session record by token
+	* Used to ensure that a token is not used more than once.
+	*/
+	async getSessionRecordByToken(token) {
+		const filter = { token };
+		return await this.tables.session.findOne(filter).lean() || void 0;
+	}
+	/**
+	* Check if a session exists and mark it as removed
+	* @returns The session record if it existed, undefined otherwise
+	*/
+	async checkAndRemoveSession(sessionId) {
+		this.logger.debug(() => ({ data: {
+			action: "checking and removing",
+			sessionId
+		} }));
+		const filter = {
+			sessionId,
+			deleted: { $exists: false }
+		};
+		try {
+			return await this.tables.session.findOneAndUpdate(filter, {
+				deleted: true,
+				lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+				pendingStage: true
+			}).lean() || void 0;
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_CHECK_REMOVE_FAILED", {
+				context: {
+					error: err,
+					sessionId
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/**
+	* Update a session record by sessionId. Pure Mongo write — callers in
+	* the provider package are responsible for refreshing the Redis cache
+	* via `RedisWriteQueue.patchCachedSession`, matching the existing
+	* caller-side caching pattern (see `frictionlessTasks.createSession`).
+	*/
+	async updateSessionRecord(sessionId, updates, streamToCentral) {
+		try {
+			await this.tables.session.updateOne({ sessionId }, { $set: {
+				...updates,
+				lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+				pendingStage: true
+			} });
+			if (streamToCentral && this.centralStreamer) {
+				const streamer = this.centralStreamer;
+				const markStored = (ts) => this.tables.session.updateOne({
+					sessionId,
+					lastUpdatedTimestamp: { $lte: ts }
+				}, {
+					$set: { storedAtTimestamp: ts },
+					$unset: { pendingStage: 1 }
+				}).then(() => {});
+				this.tables.session.findOne({ sessionId }).lean().then((record) => {
+					if (record) streamer.streamSessionRecord(record, markStored);
+				}).catch(() => {});
+			}
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
+				context: {
+					error: err,
+					sessionId
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/**
+	* Atomically record SIMD CPU fingerprint readings on the session — only
+	* if they aren't already present. Uses a Mongo aggregation-pipeline
+	* update so `simdReadings` and `simdReadingsStage` are set together,
+	* first-hop-wins. Pure Mongo write — cache refresh is the caller's
+	* responsibility via `RedisWriteQueue.patchCachedSimdReadingsIfAbsent`.
+	*/
+	async recordSessionSimdReadingsIfAbsent(sessionId, readings, stage) {
+		try {
+			await this.tables.session.updateOne({ sessionId }, [{ $set: {
+				simdReadings: { $ifNull: ["$simdReadings", readings] },
+				simdReadingsStage: { $ifNull: ["$simdReadingsStage", stage] },
+				lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+				pendingStage: true
+			} }]);
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
+				context: {
+					error: err,
+					sessionId,
+					stage
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/**
+	* Merge a DNS sidecar observation into the session's `dnsEvent` subdoc
+	* using dotted-path `$set` so DNS-leg and HTTP-leg events on the same
+	* session don't clobber each other. Replaces the prior read-modify-write
+	* pattern that lost half the fields under any race (and 100% of the time
+	* when the read projection didn't include `dnsEvent`).
+	*
+	* `receivedAtIfAbsent` is written only on the first hit for a session
+	* via a `$cond` in an aggregation-pipeline update; later events leave
+	* the original timestamp alone.
+	*/
+	async mergeSessionDnsEvent(sessionId, fields, receivedAtIfAbsent) {
+		const setStage = {
+			"dnsEvent.receivedAt": { $ifNull: ["$dnsEvent.receivedAt", receivedAtIfAbsent] },
+			lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+			pendingStage: true
+		};
+		if (fields.resolverIp !== void 0) setStage["dnsEvent.resolverIp"] = fields.resolverIp;
+		if (fields.peerIp !== void 0) setStage["dnsEvent.peerIp"] = fields.peerIp;
+		if (fields.pathValid !== void 0) setStage["dnsEvent.pathValid"] = fields.pathValid;
+		try {
+			return (await this.tables.session.updateOne({ sessionId }, [{ $set: setStage }])).matchedCount > 0;
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
+				context: {
+					error: err,
+					sessionId
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/**
+	* Get an active session by user IP hash
+	* @param userSitekeyIpHash The hash of user, IP and sitekey combination
+	* @returns The session record if it exists and is not deleted, undefined otherwise
+	*/
+	async getSessionByuserSitekeyIpHash(userSitekeyIpHash) {
+		this.logger.debug(() => ({ data: {
+			action: "getting session by user IP hash",
+			userSitekeyIpHash
+		} }));
+		const filter = {
+			userSitekeyIpHash,
+			deleted: { $exists: false }
+		};
+		try {
+			return await this.tables.session.findOne(filter).lean() || void 0;
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SESSION_GET_FAILED", {
+				context: {
+					error: err,
+					userSitekeyIpHash
+				},
+				logger: this.logger
+			});
+		}
+	}
+	/** Get unstored session records
+	* @description Get session records that have not been stored yet.
+	*
+	* Served by the `pendingStage_partial` index — see
+	* `getUnstoredDappUserCommitments` for the lifecycle of the flag.
+	* `checkAndRemoveSession` also flips the flag so consumed sessions
+	* propagate to the central DB via the next sweep.
+	* @param limit
+	* @param skip
+	*/
+	getUnstoredSessionRecords(limit = 1e3, skip = 0) {
+		return Promise.resolve(this.tables?.session).then((tbl) => tbl?.find({ pendingStage: true }).sort({ _id: 1 }).skip(skip).limit(limit).lean()).then((docs) => docs || []);
+	}
+	/** Mark a list of session records as stored.
+	*
+	* `asOfTimestamp` defaults to "now" but the sweep should pass the time
+	* at which it fetched the batch. See markDappUserCommitmentsStored for
+	* the guard rationale.
+	*/
+	async markSessionRecordsStored(sessionIds, asOfTimestamp = /* @__PURE__ */ new Date()) {
+		await this.tables?.session.updateMany({
+			sessionId: { $in: sessionIds },
+			lastUpdatedTimestamp: { $lte: asOfTimestamp }
+		}, {
+			$set: { storedAtTimestamp: /* @__PURE__ */ new Date() },
+			$unset: { pendingStage: 1 }
+		}, { upsert: false });
+	}
+	/**
+	* @description Store a Dapp User's pending record
+	*/
+	async storePendingImageCommitment(userAccount, requestHash, salt, deadlineTimestamp, requestedAtTimestamp, ipAddress, threshold, sessionId, ipInfo) {
+		if (!isHex(requestHash)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.storePendingImageCommitment.name,
+			requestHash
+		} });
+		const pendingRecord = {
+			userAccount,
+			pending: true,
+			salt,
+			requestHash,
+			deadlineTimestamp,
+			requestedAtTimestamp,
+			ipAddress,
+			sessionId,
+			threshold,
+			ipInfo,
+			dappAccount: "",
+			providerAccount: "",
+			datasetId: "",
+			id: "",
+			result: { status: CaptchaStatus.pending },
+			headers: {},
+			ja4: "",
+			userSignature: "",
+			userSubmitted: false,
+			serverChecked: false
+		};
+		await this.tables?.commitment.updateOne({ requestHash }, { $set: pendingRecord }, { upsert: true });
+	}
+	/**
+	* @description Get a user's pending record
+	*/
+	async getPendingImageCommitment(requestHash) {
+		if (!isHex(requestHash)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.getPendingImageCommitment.name,
+			requestHash
+		} });
+		const doc = await this.tables?.commitment.findOne({
+			requestHash,
+			pending: true
+		}).lean();
+		if (doc) return {
+			dappAccount: doc.dappAccount,
+			pending: doc.pending,
+			salt: doc.salt,
+			requestHash: doc.requestHash,
+			deadlineTimestamp: doc.deadlineTimestamp,
+			requestedAtTimestamp: doc.requestedAtTimestamp,
+			ipAddress: doc.ipAddress,
+			sessionId: doc.sessionId,
+			threshold: doc.threshold
+		};
+		throw new ProsopoDBError("DATABASE.PENDING_RECORD_NOT_FOUND", { context: {
+			failedFuncName: this.getPendingImageCommitment.name,
+			requestHash
+		} });
+	}
+	/**
+	* @description Mark a pending request as used
+	*/
+	async updatePendingImageCommitmentStatus(requestHash) {
+		if (!isHex(requestHash)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.updatePendingImageCommitmentStatus.name,
+			requestHash
+		} });
+		await this.tables?.commitment.updateOne({ requestHash }, { $set: { pending: false } });
+	}
+	/**
+	* @description Get all unsolved captchas
+	*/
+	async getAllCaptchasByDatasetId(datasetId, state) {
+		const filter = {
+			datasetId,
+			solved: state === CaptchaStates.Solved
+		};
+		const docs = await this.tables?.captcha.find(filter).lean();
+		if (docs) return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+		throw new ProsopoDBError("DATABASE.CAPTCHA_GET_FAILED");
+	}
+	/**
+	* @description Get all dapp user solutions by captchaIds
+	*/
+	async getAllDappUserSolutions(captchaId) {
+		const filter = { captchaId: { $in: captchaId } };
+		const docs = await this.tables?.usersolution?.find(filter).lean();
+		if (docs) return docs.map(({ _id, ...keepAttrs }) => keepAttrs);
+		throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED");
+	}
+	async getDatasetIdWithSolvedCaptchasOfSizeN(solvedCaptchaCount) {
+		const docs = await this.tables?.solution.aggregate([
+			{ $match: {} },
+			{ $group: {
+				_id: "$datasetId",
+				count: { $sum: 1 }
+			} },
+			{ $match: { count: { $gte: solvedCaptchaCount } } },
+			{ $sample: { size: 1 } }
+		]);
+		if (docs?.length) return docs[0]._id;
+		throw new ProsopoDBError("DATABASE.DATASET_WITH_SOLUTIONS_GET_FAILED");
+	}
+	async getRandomSolvedCaptchasFromSingleDataset(datasetId, size) {
+		if (!isHex(datasetId)) throw new ProsopoDBError("DATABASE.INVALID_HASH", { context: {
+			failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
+			datasetId
+		} });
+		const sampleSize = size ? Math.abs(Math.trunc(size)) : 1;
+		const docs = await this.tables?.solution.aggregate([
+			{ $match: { datasetId } },
+			{ $sample: { size: sampleSize } },
+			{ $project: {
+				captchaId: 1,
+				captchaContentId: 1,
+				solution: 1
+			} }
+		]);
+		if (docs?.length) return docs;
+		throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", { context: {
+			failedFuncName: this.getRandomSolvedCaptchasFromSingleDataset.name,
+			datasetId,
+			size
+		} });
+	}
+	/**
+	* @description Get dapp user solution by ID
+	* @param {string[]} commitmentId
+	*/
+	async getDappUserSolutionById(commitmentId) {
+		const filter = { commitmentId };
+		const doc = await this.tables?.usersolution?.findOne(filter, { _id: 0 }).lean();
+		if (doc) return doc;
+		throw new ProsopoDBError("DATABASE.SOLUTION_GET_FAILED", { context: {
+			failedFuncName: this.getCaptchaById.name,
+			commitmentId
+		} });
+	}
+	/**
+	* @description Get dapp user commitment by user account
+	* @param commitmentId
+	*/
+	async getDappUserCommitmentById(commitmentId) {
+		const filter = { id: commitmentId };
+		const doc = await this.tables?.commitment?.findOne(filter, {
+			id: 1,
+			result: 1,
+			serverChecked: 1,
+			requestedAtTimestamp: 1,
+			submittedAtTimestamp: 1,
+			verifiedAtTimestamp: 1,
+			failedAtTimestamp: 1,
+			ipAddress: 1,
+			sessionId: 1,
+			userAccount: 1,
+			dappAccount: 1,
+			headers: 1,
+			ipInfo: 1
+		}).lean();
+		return doc ? doc : void 0;
+	}
+	/**
+	* @description Get dapp user commitment by user account
+	* @param {string} userAccount
+	* @param {string} dappAccount
+	*/
+	async getDappUserCommitmentByAccount(userAccount, dappAccount) {
+		const filter = {
+			userAccount,
+			dappAccount
+		};
+		const docs = await this.tables?.commitment?.find(filter, {
+			_id: 0,
+			result: 1
+		}, { sort: { _id: -1 } }).lean();
+		return docs ? docs : [];
+	}
+	/**
+	* @description Approve a dapp user's solution
+	* @param {string[]} commitmentId
+	* @param coords
+	*/
+	async approveDappUserCommitment(commitmentId, coords) {
+		try {
+			const updateDoc = {
+				result: { status: CaptchaStatus.approved },
+				lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+				pendingStage: true,
+				...coords ? { coords } : {}
+			};
+			const filter = { id: commitmentId };
+			await this.tables?.commitment?.findOneAndUpdate(filter, { $set: updateDoc }, { upsert: false }).lean();
+			this.centralStreamer?.streamImageUpdate(() => this.tables.commitment.findOne({ id: commitmentId }).lean(), (ts) => this.tables.commitment.updateOne({
+				id: commitmentId,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", { context: {
+				error: err,
+				commitmentId
+			} });
+		}
+	}
+	/**
+	* @description Disapprove a dapp user's solution
+	* @param {string} commitmentId
+	* @param coords
+	* @param reason
+	*/
+	async disapproveDappUserCommitment(commitmentId, reason, coords) {
+		try {
+			const updateDoc = {
+				result: {
+					status: CaptchaStatus.disapproved,
+					reason
+				},
+				lastUpdatedTimestamp: /* @__PURE__ */ new Date(),
+				pendingStage: true,
+				...coords ? { coords } : {}
+			};
+			const filter = { id: commitmentId };
+			await this.tables?.commitment?.findOneAndUpdate(filter, { $set: updateDoc }, { upsert: false }).lean();
+			this.centralStreamer?.streamImageUpdate(() => this.tables.commitment.findOne({ id: commitmentId }).lean(), (ts) => this.tables.commitment.updateOne({
+				id: commitmentId,
+				lastUpdatedTimestamp: { $lte: ts }
+			}, {
+				$set: { storedAtTimestamp: ts },
+				$unset: { pendingStage: 1 }
+			}).then(() => {}));
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SOLUTION_APPROVE_FAILED", { context: {
+				error: err,
+				commitmentId
+			} });
+		}
+	}
+	/**
+	* @description Flag a dapp user's solutions as used by calculated solution
+	* @param {string[]} captchaIds
+	*/
+	async flagProcessedDappUserSolutions(captchaIds) {
+		try {
+			await this.tables?.usersolution?.updateMany({ captchaId: { $in: captchaIds } }, { $set: { processed: true } }, { upsert: false }).lean();
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.SOLUTION_FLAG_FAILED", { context: {
+				error: err,
+				captchaIds
+			} });
+		}
+	}
+	/**
+	* @description Flag dapp users' commitments as used by calculated solution
+	* @param {string[]} commitmentIds
+	*/
+	async flagProcessedDappUserCommitments(commitmentIds) {
+		try {
+			const distinctCommitmentIds = [...new Set(commitmentIds)];
+			await this.tables?.commitment?.updateMany({ id: { $in: distinctCommitmentIds } }, { $set: { processed: true } }, { upsert: false }).lean();
+		} catch (err) {
+			throw new ProsopoDBError("DATABASE.COMMITMENT_FLAG_FAILED", { context: {
+				error: err,
+				commitmentIds
+			} });
+		}
+	}
+	/**
+	* @description Get a scheduled task status record by task ID and status
+	*/
+	async getScheduledTaskStatus(taskId, status) {
+		const filter = {
+			_id: taskId,
+			status
+		};
+		const cursor = await this.tables?.scheduler?.findOne(filter).lean();
+		return cursor ? cursor : void 0;
+	}
+	/**
+	* @description Get the most recent scheduled task status record for a given task
+	*/
+	async getLastScheduledTaskStatus(task, status) {
+		const filter = { processName: task };
+		if (status) filter.status = status;
+		const cursor = await this.tables?.scheduler?.findOne(filter).sort({ datetime: -1 }).limit(1).lean();
+		return cursor ? cursor : void 0;
+	}
+	/**
+	* @description Create the status of a scheduled task
+	*/
+	async createScheduledTaskStatus(taskName, status) {
+		const now = /* @__PURE__ */ new Date();
+		const doc = ScheduledTaskSchema.parse({
+			processName: taskName,
+			datetime: now,
+			status
+		});
+		return (await this.tables?.scheduler.create(doc))._id;
+	}
+	/**
+	* @description Update the status of a scheduled task and an optional result
+	*/
+	async updateScheduledTaskStatus(taskId, status, result) {
+		const update = {
+			status,
+			updated: /* @__PURE__ */ new Date(),
+			...result && { result }
+		};
+		const filter = { _id: taskId };
+		await this.tables?.scheduler.updateOne(filter, { $set: update }, { upsert: false });
+	}
+	/**
+	* @description Clean up the scheduled task status records
+	*/
+	async cleanupScheduledTaskStatus(status) {
+		const filter = { status };
+		await this.tables?.scheduler.deleteMany(filter);
+	}
+	/**
+	* @description Update the client records
+	*/
+	async updateClientRecords(clientRecords) {
+		const ops = clientRecords.map((record) => {
+			const clientRecord = {
+				account: record.account,
+				settings: record.settings,
+				tier: record.tier
+			};
+			return { updateOne: {
+				filter: { account: record.account },
+				update: { $set: clientRecord },
+				upsert: true
+			} };
+		});
+		if (!ops || ops.length === 0) {
+			await this.logger.debug(() => ({ msg: "No client updates to apply" }));
+			return;
+		}
+		await this.tables?.client.bulkWrite(ops);
+	}
+	/**
+	* @description Remove client records by account
+	*/
+	async removeClientRecords(accounts) {
+		if (!accounts || accounts.length === 0) return;
+		await this.tables?.client.deleteMany({ account: { $in: accounts } });
+	}
+	/**
+	* @description Get all client records
+	*/
+	async getAllClientRecords() {
+		return await this.tables?.client.find().lean() || [];
+	}
+	/**
+	* @description Get a client record
+	*/
+	async getClientRecord(account) {
+		const filter = { account };
+		const doc = await this.tables?.client.findOne(filter, {
+			account: 1,
+			settings: 1,
+			tier: 1
+		}).lean();
+		return doc ? doc : void 0;
+	}
+	/**
+	* @description Store a detector key
+	*/
+	async storeDetectorKey(detectorKey) {
+		return this.tables?.detector.create({
+			detectorKey,
+			createdAt: /* @__PURE__ */ new Date()
+		});
+	}
+	/**
+	* @description Remove a detector key
+	* @param detectorKey The detector key to remove
+	* @param expirationInSeconds Optional expiration time in seconds (default is 10 minutes)
+	* */
+	async removeDetectorKey(detectorKey, expirationInSeconds) {
+		const filter = { detectorKey };
+		const expiresAt = new Date(Date.now() + (expirationInSeconds || 600) * 1e3);
+		await this.tables?.detector.updateOne(filter, { $set: { expiresAt } });
+	}
+	/**
+	* @description Get valid detector keys
+	*/
+	async getDetectorKeys() {
+		return (await this.tables?.detector.find({ $or: [{ expiresAt: { $exists: false } }, { expiresAt: null }] }, { detectorKey: 1 }).sort({ createdAt: -1 }).lean() || []).map((record) => record.detectorKey);
+	}
+	/**
+	* Stores a decision machine artifact with a unique scope identifier.
+	*
+	* The combination of scope + dappAccount uniquely identifies a single artifact:
+	* - Global scope: One artifact per provider (dappAccount is null)
+	* - Dapp scope: One artifact per dapp account (dappAccount is specified)
+	*
+	* @param artifact - The decision machine artifact to store
+	*/
+	async upsertDecisionMachineArtifact(artifact) {
+		const now = /* @__PURE__ */ new Date();
+		const dappAccount = artifact.dappAccount ?? null;
+		const kind = artifact.kind ?? DecisionMachineKind.Routing;
+		const filter = {
+			scope: artifact.scope,
+			dappAccount,
+			kind
+		};
+		await this.tables?.decisionMachine.updateOne(filter, {
+			$set: {
+				scope: artifact.scope,
+				dappAccount,
+				kind,
+				runtime: artifact.runtime,
+				language: artifact.language,
+				source: artifact.source,
+				name: artifact.name,
+				version: artifact.version,
+				captchaType: artifact.captchaType,
+				updatedAt: now
+			},
+			$setOnInsert: { createdAt: now }
+		}, { upsert: true });
+	}
+	/**
+	* Retrieves a single decision machine artifact by scope and optional dapp account.
+	*
+	* @param scope - The scope level (Global or Dapp)
+	* @param dappAccount - Required for Dapp scope, unused for Global scope
+	* @returns The matching artifact, or undefined if not found
+	*/
+	async getDecisionMachineArtifact(scope, dappAccount, kind) {
+		const filter = {
+			scope,
+			dappAccount: dappAccount ?? null
+		};
+		if (kind !== void 0) filter.kind = kind;
+		return await this.tables?.decisionMachine.findOne(filter).lean() ?? void 0;
+	}
+	/**
+	* Retrieves all decision machine artifacts.
+	*
+	* @returns Array of all decision machine artifacts
+	*/
+	async getAllDecisionMachineArtifacts() {
+		return await this.tables?.decisionMachine.find({}).lean() ?? [];
+	}
+	/**
+	* Retrieves a single decision machine artifact by MongoDB ObjectId.
+	*
+	* @param id - The MongoDB ObjectId as a string
+	* @returns The matching artifact, or undefined if not found
+	*/
+	async getDecisionMachineArtifactById(id) {
+		return await this.tables?.decisionMachine.findById(id).lean() ?? void 0;
+	}
+	/**
+	* Removes a decision machine artifact by MongoDB ObjectId.
+	*
+	* @param id - The MongoDB ObjectId as a string
+	* @returns true if deleted, false if not found
+	*/
+	async removeDecisionMachineArtifact(id) {
+		return ((await this.tables?.decisionMachine.deleteOne({ _id: id }))?.deletedCount ?? 0) > 0;
+	}
+	/**
+	* Removes all decision machine artifacts.
+	*
+	* @returns The number of artifacts deleted
+	*/
+	async removeAllDecisionMachineArtifacts() {
+		return (await this.tables?.decisionMachine.deleteMany({}))?.deletedCount ?? 0;
+	}
+	/**
+	* @description set client context-specific entropy
+	*/
+	async setClientContextEntropy(account, contextType, entropy) {
+		const filter = {
+			account,
+			contextType
+		};
+		await this.tables?.clientContextEntropy.updateOne(filter, { $set: {
+			account,
+			contextType,
+			entropy
+		} }, { upsert: true });
+	}
+	/**
+	* @description get client context-specific entropy
+	*/
+	async getClientContextEntropy(account, contextType) {
+		const filter = {
+			account,
+			contextType
+		};
+		const doc = await this.tables?.clientContextEntropy.findOne(filter).lean();
+		return doc ? doc.entropy : void 0;
+	}
+	/** Sample captcha records from the database for a specific context */
+	async sampleContextEntropy(sampleSize, siteKey, contextType) {
+		const size = sampleSize ? Math.abs(Math.trunc(sampleSize)) : 1;
+		const max = 1e4;
+		if (size > max) throw new ProsopoDBError("DATABASE.CAPTCHA_SAMPLE_SIZE_EXCEEDED", { context: {
+			failedFuncName: this.sampleContextEntropy.name,
+			sampleSize
+		} });
+		const pipeline = [
+			{ $match: {
+				dappAccount: siteKey,
+				requestedAtTimestamp: { $gt: new Date((/* @__PURE__ */ new Date()).getTime() - TWENTY_FOUR_HOURS_IN_MS) }
+			} },
+			{ $sample: { size: max } },
+			{ $lookup: {
+				from: "sessions",
+				localField: "sessionId",
+				foreignField: "sessionId",
+				as: "sessionData"
+			} },
+			{ $unwind: {
+				path: "$sessionData",
+				preserveNullAndEmptyArrays: false
+			} }
+		];
+		if (contextType === ContextType.Webview) pipeline.push({ $match: { "sessionData.webView": true } });
+		else if (contextType === ContextType.Default) pipeline.push({ $match: { "sessionData.webView": false } });
+		pipeline.push({ $sample: { size } }, { $project: {
+			_id: 0,
+			sessionId: 1
+		} });
+		const docs = await this.tables?.powcaptcha.aggregate(pipeline);
+		if (docs?.length === 0) return [];
+		return (await Promise.all(docs.map(async (doc) => {
+			if (doc.sessionId) return (await this.getSessionRecordBySessionId(doc.sessionId))?.decryptedHeadHash;
+		}))).filter((headHash) => headHash !== void 0);
+	}
+	async getSpamEmailDomain(domain) {
+		if (!this.tables?.spamEmailDomain) throw new ProsopoDBError("DATABASE.DATABASE_IMPORT_ERROR", { context: { failedFuncName: this.getSpamEmailDomain.name } });
+		const suffixCandidates = buildDomainSuffixCandidates(domain).slice(0, MAX_DOMAIN_SUFFIX_CANDIDATES);
+		const query = suffixCandidates.length > 0 ? { domain: { $in: suffixCandidates } } : { domain };
+		return await this.tables.spamEmailDomain.findOne(query).exec();
+	}
+	async bulkUpdateSpamEmailDomains(domains, upsert) {
+		if (!this.tables?.spamEmailDomain) throw new ProsopoDBError("DATABASE.DATABASE_IMPORT_ERROR", { context: { failedFuncName: this.bulkUpdateSpamEmailDomains.name } });
+		const bulkOps = domains.map((op) => ({ updateOne: {
+			filter: op.filter,
+			update: { $set: op.update },
+			upsert
+		} }));
+		if (bulkOps.length > 0) await this.tables.spamEmailDomain.bulkWrite(bulkOps);
+	}
 };
+//#endregion
+export { ProviderDatabase };