@resistdesign/voltra 3.0.0-alpha.35 → 3.0.0-alpha.37

package/api/index.js

@@ -1,8 +1,8 @@
 import { ITEM_RELATIONSHIP_DAC_RESOURCE_NAME, ComparisonOperators } from '../chunk-7AMEFPPP.js';
-import { getNoErrorDescriptor, getErrorDescriptor, ERROR_MESSAGE_CONSTANTS, validateTypeOperationAllowed, getValidityValue, validateTypeInfoValue, validateTypeInfoFieldValue } from '../chunk-WTD5BBJP.js';
-import { mergeStringPaths, getPathString, getPathArray } from '../chunk-GYWRAW3Y.js';
+import { getNoErrorDescriptor, getErrorDescriptor, ERROR_MESSAGE_CONSTANTS, validateTypeOperationAllowed, getValidityValue, validateTypeInfoValue, validateTypeInfoFieldValue } from '../chunk-YCTVEW2I.js';
+import { mergeStringPaths, getPathString, getPathArray } from '../chunk-WNFRDIBW.js';
 import '../chunk-I2KLQ2HA.js';
-import { QueryCommand, GetItemCommand, BatchGetItemCommand, BatchWriteItemCommand, DynamoDBClient, PutItemCommand, UpdateItemCommand, DeleteItemCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
+import { QueryCommand, PutItemCommand, ConditionalCheckFailedException, GetItemCommand, BatchGetItemCommand, BatchWriteItemCommand, DynamoDBClient, UpdateItemCommand, DeleteItemCommand, ScanCommand } from '@aws-sdk/client-dynamodb';
 import { marshall, unmarshall } from '@aws-sdk/util-dynamodb';
 import { S3, PutObjectCommand, HeadObjectCommand, CopyObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
@@ -1171,6 +1171,25 @@ var createAwsSdkV3DynamoClient = (client) => ({
       Item: response.Item ? fromAwsKey(response.Item) : void 0
     };
   },
+  putItem: async (input) => {
+    try {
+      await client.send(
+        new PutItemCommand({
+          TableName: input.TableName,
+          Item: toAwsKey(input.Item),
+          ConditionExpression: input.ConditionExpression,
+          ExpressionAttributeNames: input.ExpressionAttributeNames,
+          ExpressionAttributeValues: input.ExpressionAttributeValues ? toAwsKey(input.ExpressionAttributeValues) : void 0
+        })
+      );
+      return {};
+    } catch (error) {
+      if (error instanceof ConditionalCheckFailedException) {
+        return { conditionFailed: true };
+      }
+      throw error;
+    }
+  },
   query: async (input) => {
     const response = await client.send(
       new QueryCommand({
@@ -3324,18 +3343,53 @@ async function structuredHandler(event) {
 }
 
 // src/api/Indexing/structured/StructuredStringLike.ts
-var MAX_INDEXED_STRING_LENGTH = 128;
-var MAX_TOKENS_PER_VALUE = 256;
-var MAX_NGRAM_SIZE = 3;
+var DEFAULT_MAX_INDEXED_STRING_LENGTH = 128;
+var DEFAULT_MAX_TOKENS_PER_VALUE = 256;
+var DEFAULT_MIN_NGRAM_SIZE = 1;
+var DEFAULT_MAX_NGRAM_SIZE = 3;
 var LIKE_WILDCARD_REGEX = /[%_]/;
 var NORMALIZED_WHITESPACE_REGEX = /\s+/g;
 var STRUCTURED_STRING_CONTAINS_TOKEN_PREFIX = "__str__:";
+var DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG = {
+  minNgramSize: DEFAULT_MIN_NGRAM_SIZE,
+  maxNgramSize: DEFAULT_MAX_NGRAM_SIZE,
+  maxIndexedStringLength: DEFAULT_MAX_INDEXED_STRING_LENGTH,
+  maxTokensPerValue: DEFAULT_MAX_TOKENS_PER_VALUE
+};
+var clampInteger = (value, fallback, minimum = 1) => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(minimum, Math.floor(value));
+};
+var resolveStructuredStringTokenizerConfig = (config) => {
+  const minNgramSize = clampInteger(
+    config?.minNgramSize,
+    DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG.minNgramSize
+  );
+  const maxNgramSize = clampInteger(
+    config?.maxNgramSize,
+    DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG.maxNgramSize
+  );
+  return {
+    minNgramSize: Math.min(minNgramSize, maxNgramSize),
+    maxNgramSize: Math.max(minNgramSize, maxNgramSize),
+    maxIndexedStringLength: clampInteger(
+      config?.maxIndexedStringLength,
+      DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG.maxIndexedStringLength
+    ),
+    maxTokensPerValue: clampInteger(
+      config?.maxTokensPerValue,
+      DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG.maxTokensPerValue
+    )
+  };
+};
 var normalizeStructuredLikeString = (value) => value.toLowerCase().trim().replace(NORMALIZED_WHITESPACE_REGEX, " ");
-var toNgrams = (normalized) => {
+var toNgrams = (normalized, config) => {
   const tokens = [];
   const seen = /* @__PURE__ */ new Set();
-  const limited = normalized.slice(0, MAX_INDEXED_STRING_LENGTH);
-  for (let size = 1; size <= MAX_NGRAM_SIZE; size += 1) {
+  const limited = normalized.slice(0, config.maxIndexedStringLength);
+  for (let size = config.minNgramSize; size <= config.maxNgramSize; size += 1) {
     if (limited.length < size) {
       break;
     }
@@ -3344,7 +3398,7 @@ var toNgrams = (normalized) => {
       if (!seen.has(token)) {
         seen.add(token);
         tokens.push(token);
-        if (tokens.length >= MAX_TOKENS_PER_VALUE) {
+        if (tokens.length >= config.maxTokensPerValue) {
           return tokens;
         }
       }
@@ -3353,26 +3407,28 @@ var toNgrams = (normalized) => {
   return tokens;
 };
 var toContainsToken = (token) => `${STRUCTURED_STRING_CONTAINS_TOKEN_PREFIX}${token}`;
-var buildStructuredStringContainsTokens = (value) => {
+var buildStructuredStringContainsTokens = (value, tokenizerConfig) => {
+  const config = resolveStructuredStringTokenizerConfig(tokenizerConfig);
   const normalized = normalizeStructuredLikeString(value);
   if (!normalized.length) {
     return [];
   }
-  return toNgrams(normalized).map(toContainsToken);
+  return toNgrams(normalized, config).map(toContainsToken);
 };
-var buildStructuredLikePatternTokens = (value) => {
+var buildStructuredLikePatternTokens = (value, tokenizerConfig) => {
+  const config = resolveStructuredStringTokenizerConfig(tokenizerConfig);
   const normalized = normalizeStructuredLikeString(value);
   const pattern = LIKE_WILDCARD_REGEX.test(normalized) ? normalized : `%${normalized}%`;
   const literalSegments = pattern.split(LIKE_WILDCARD_REGEX).map((segment) => segment.trim()).filter((segment) => segment.length > 0);
   const tokens = [];
   const seen = /* @__PURE__ */ new Set();
   for (const segment of literalSegments) {
-    for (const token of toNgrams(segment)) {
+    for (const token of toNgrams(segment, config)) {
       const containsToken = toContainsToken(token);
       if (!seen.has(containsToken)) {
         seen.add(containsToken);
         tokens.push(containsToken);
-        if (tokens.length >= MAX_TOKENS_PER_VALUE) {
+        if (tokens.length >= config.maxTokensPerValue) {
           return tokens;
         }
       }
@@ -3505,6 +3561,9 @@ function addPosting(index, field, value, docId) {
   index.set(field, fieldIndex);
 }
 var StructuredInMemoryIndex = class {
+  constructor(tokenizer) {
+    this.tokenizer = tokenizer;
+  }
   eqIndex = /* @__PURE__ */ new Map();
   containsIndex = /* @__PURE__ */ new Map();
   rangeIndex = /* @__PURE__ */ new Map();
@@ -3525,7 +3584,10 @@ var StructuredInMemoryIndex = class {
       }
       addPosting(this.eqIndex, field, value, docId);
       if (typeof value === "string") {
-        for (const token of buildStructuredStringContainsTokens(value)) {
+        for (const token of buildStructuredStringContainsTokens(
+          value,
+          this.tokenizer
+        )) {
           addPosting(this.containsIndex, field, token, docId);
         }
       }
@@ -3612,10 +3674,17 @@ var normalizeFields = (fields) => {
   return normalized;
 };
 var StructuredInMemoryBackend = class {
+  /**
+   * @param tokenizer Optional tokenizer overrides for structured string contains behavior.
+   */
+  constructor(tokenizer) {
+    this.tokenizer = tokenizer;
+    this.index = new StructuredInMemoryIndex(tokenizer);
+  }
   docFields = /* @__PURE__ */ new Map();
-  index = new StructuredInMemoryIndex();
+  index;
   rebuildIndex() {
-    const nextIndex = new StructuredInMemoryIndex();
+    const nextIndex = new StructuredInMemoryIndex(this.tokenizer);
     for (const [docId, fields] of this.docFields.entries()) {
       nextIndex.addDocument(docId, fields);
     }
@@ -3705,7 +3774,8 @@ var structuredRangeIndexSchema = {
 };
 var structuredDocFieldsSchema = {
   partitionKey: "docId",
-  fieldsAttribute: "fields"
+  fieldsAttribute: "fields",
+  versionAttribute: "version"
 };
 function serializeStructuredValue(value) {
   if (value === null) {
@@ -3745,8 +3815,8 @@ function buildStructuredRangeItem(field, value, docId) {
     docId
   };
 }
-function buildStructuredDocFieldsItem(docId, fields) {
-  return { docId, fields };
+function buildStructuredDocFieldsItem(docId, fields, version) {
+  return { docId, fields, version };
 }
 
 // src/api/Indexing/structured/StructuredWriter.ts
@@ -3762,7 +3832,7 @@ function normalizeFields2(fields) {
   }
   return normalized;
 }
-function buildTermEntries(docId, fields) {
+function buildTermEntries(docId, fields, options) {
   const entries = [];
   for (const [field, value] of Object.entries(fields)) {
     if (Array.isArray(value)) {
@@ -3773,7 +3843,10 @@ function buildTermEntries(docId, fields) {
     } else {
       entries.push(buildStructuredTermItem(field, value, "eq", docId));
       if (typeof value === "string") {
-        for (const token of buildStructuredStringContainsTokens(value)) {
+        for (const token of buildStructuredStringContainsTokens(
+          value,
+          options.tokenizer
+        )) {
           entries.push(buildStructuredTermItem(field, token, "contains", docId));
         }
       }
@@ -3830,9 +3903,11 @@ var StructuredDdbWriter = class {
   /**
    * @param dependencies Writer dependencies for persistence.
    */
-  constructor(dependencies3) {
+  constructor(dependencies3, options = {}) {
     this.dependencies = dependencies3;
+    this.options = options;
   }
+  options;
   /**
    * Write structured fields for a document, diffing term/range entries.
    * @param docId Document id to write.
@@ -3841,29 +3916,52 @@ var StructuredDdbWriter = class {
    */
   async write(docId, fields) {
     const normalized = normalizeFields2(fields);
-    const previousFields = await this.dependencies.loadDocFields(docId);
-    const previousNormalized = previousFields ? normalizeFields2(previousFields) : {};
-    const previousTerms = buildTermEntries(docId, previousNormalized);
-    const nextTerms = buildTermEntries(docId, normalized);
-    const previousRanges = buildRangeEntries(docId, previousNormalized);
-    const nextRanges = buildRangeEntries(docId, normalized);
-    const termDiff = diffEntries(previousTerms, nextTerms, termEntryKey);
-    const rangeDiff = diffEntries(previousRanges, nextRanges, rangeEntryKey);
-    if (termDiff.toDelete.length > 0) {
-      await this.dependencies.deleteTermEntries(toTermKeys(termDiff.toDelete));
-    }
-    if (rangeDiff.toDelete.length > 0) {
-      await this.dependencies.deleteRangeEntries(
-        toRangeKeys(rangeDiff.toDelete)
+    const maxRetries = this.options.maxConcurrentWriteRetries ?? 8;
+    let attempts = 0;
+    while (attempts <= maxRetries) {
+      const previousState = await this.dependencies.loadDocFieldsState(docId);
+      const previousNormalized = previousState ? normalizeFields2(previousState.fields) : {};
+      const expectedVersion = previousState?.version;
+      const previousTerms = buildTermEntries(
+        docId,
+        previousNormalized,
+        this.options
       );
+      const nextTerms = buildTermEntries(docId, normalized, this.options);
+      const previousRanges = buildRangeEntries(docId, previousNormalized);
+      const nextRanges = buildRangeEntries(docId, normalized);
+      const termDiff = diffEntries(previousTerms, nextTerms, termEntryKey);
+      const rangeDiff = diffEntries(previousRanges, nextRanges, rangeEntryKey);
+      const noDiff = termDiff.toAdd.length === 0 && termDiff.toDelete.length === 0 && rangeDiff.toAdd.length === 0 && rangeDiff.toDelete.length === 0;
+      if (noDiff) {
+        return;
+      }
+      const swapped = await this.dependencies.putDocFieldsIfVersion(
+        docId,
+        expectedVersion,
+        normalized
+      );
+      if (!swapped) {
+        attempts += 1;
+        continue;
+      }
+      if (termDiff.toDelete.length > 0) {
+        await this.dependencies.deleteTermEntries(toTermKeys(termDiff.toDelete));
+      }
+      if (rangeDiff.toDelete.length > 0) {
+        await this.dependencies.deleteRangeEntries(
+          toRangeKeys(rangeDiff.toDelete)
+        );
+      }
+      if (termDiff.toAdd.length > 0) {
+        await this.dependencies.putTermEntries(termDiff.toAdd);
+      }
+      if (rangeDiff.toAdd.length > 0) {
+        await this.dependencies.putRangeEntries(rangeDiff.toAdd);
+      }
+      return;
     }
-    if (termDiff.toAdd.length > 0) {
-      await this.dependencies.putTermEntries(termDiff.toAdd);
-    }
-    if (rangeDiff.toAdd.length > 0) {
-      await this.dependencies.putRangeEntries(rangeDiff.toAdd);
-    }
-    await this.dependencies.putDocFields(docId, normalized);
+    throw new Error("Structured writer concurrent write retries exceeded.");
   }
 };
 
@@ -4052,7 +4150,7 @@ var StructuredDdbWriterDependencies = class {
     this.rangeTableName = config.tables.rangeIndex;
     this.docFieldsTableName = config.tables.docFields;
   }
-  async loadDocFields(docId) {
+  async loadDocFieldsState(docId) {
     const response = await this.client.getItem({
       TableName: this.docFieldsTableName,
       Key: { [structuredDocFieldsSchema.partitionKey]: docId }
@@ -4061,22 +4159,40 @@ var StructuredDdbWriterDependencies = class {
       return void 0;
     }
     const item = response.Item;
-    return item.fields;
+    if (!item.fields) {
+      return void 0;
+    }
+    return {
+      fields: item.fields,
+      version: typeof item.version === "number" && Number.isFinite(item.version) ? item.version : 0
+    };
   }
-  async putDocFields(docId, fields) {
-    const requestItems = {
-      [this.docFieldsTableName]: [
-        {
-          PutRequest: {
-            Item: {
-              [structuredDocFieldsSchema.partitionKey]: docId,
-              [structuredDocFieldsSchema.fieldsAttribute]: fields
-            }
-          }
+  async putDocFieldsIfVersion(docId, expectedVersion, fields) {
+    if (typeof expectedVersion === "undefined") {
+      const createResult = await this.client.putItem({
+        TableName: this.docFieldsTableName,
+        Item: buildStructuredDocFieldsItem(docId, fields, 1),
+        ConditionExpression: "attribute_not_exists(#docId)",
+        ExpressionAttributeNames: {
+          "#docId": structuredDocFieldsSchema.partitionKey
         }
-      ]
-    };
-    await batchWriteWithRetry(this.client, requestItems);
+      });
+      return !createResult.conditionFailed;
+    }
+    const nextVersion = expectedVersion + 1;
+    const updateResult = await this.client.putItem({
+      TableName: this.docFieldsTableName,
+      Item: buildStructuredDocFieldsItem(docId, fields, nextVersion),
+      ConditionExpression: "(#version = :expectedVersion) OR (attribute_not_exists(#version) AND :expectedVersion = :zero)",
+      ExpressionAttributeNames: {
+        "#version": structuredDocFieldsSchema.versionAttribute
+      },
+      ExpressionAttributeValues: {
+        ":expectedVersion": expectedVersion,
+        ":zero": 0
+      }
+    });
+    return !updateResult.conditionFailed;
   }
   async putTermEntries(entries) {
     await this.batchWrite(
@@ -4154,7 +4270,11 @@ var StructuredDdbBackend = class {
   constructor(config) {
     this.reader = new StructuredDdbReader(config);
     this.writer = new StructuredDdbWriter(
-      new StructuredDdbWriterDependencies(config)
+      new StructuredDdbWriterDependencies(config),
+      {
+        ...config.writerOptions,
+        tokenizer: config.writerOptions?.tokenizer ?? config.tokenizer
+      }
     );
   }
 };
@@ -4354,7 +4474,7 @@ var compareArray = (fieldCriterion, fieldValue) => {
   }
 };
 var getFilterTypeInfoDataItemsBySearchCriteria = (searchCriteria, items, typeInfoName, typeInfoMap) => {
-  const { fields = {} } = {};
+  const { fields = {} } = typeInfoMap?.[typeInfoName] || {};
   const { logicalOperator = "AND" /* AND */, fieldCriteria = [] } = searchCriteria;
   const filteredItems = [];
   for (const currentItem of items) {
@@ -7006,7 +7126,7 @@ var buildTerm = (fieldName, mode, value) => ({
   mode,
   value
 });
-var buildWhereForCriterion = (criterion) => {
+var buildWhereForCriterion = (criterion, tokenizer) => {
   const { fieldName, operator = "EQUALS" /* EQUALS */, value } = criterion;
   switch (operator) {
     case "EQUALS" /* EQUALS */:
@@ -7017,7 +7137,7 @@ var buildWhereForCriterion = (criterion) => {
       if (typeof value !== "string") {
         return buildTerm(fieldName, "contains", value);
       }
-      const tokens = buildStructuredLikePatternTokens(value);
+      const tokens = buildStructuredLikePatternTokens(value, tokenizer);
       const tokenClauses = tokens.map(
         (token) => buildTerm(fieldName, "contains", token)
       );
@@ -7063,12 +7183,12 @@ var buildWhereForCriterion = (criterion) => {
       };
   }
 };
-var criteriaToStructuredWhere = (criteria) => {
+var criteriaToStructuredWhere = (criteria, tokenizer) => {
   if (!criteria || !Array.isArray(criteria.fieldCriteria)) {
     return void 0;
   }
   const clauses = criteria.fieldCriteria.map(
-    (criterion) => buildWhereForCriterion(criterion)
+    (criterion) => buildWhereForCriterion(criterion, tokenizer)
   );
   if (clauses.length === 0) {
     return void 0;
@@ -7115,6 +7235,37 @@ var TypeInfoORMService = class {
   }
   dacRoleCache = {};
   indexingRelationshipDriver;
+  /**
+   * Emit list routing decision observability events without impacting runtime behavior.
+   */
+  emitListRoutingDecision = (typeName, path, reason, criteriaCount) => {
+    const hook = this.config.indexing?.observability?.onListRoutingDecision;
+    if (!hook) {
+      return;
+    }
+    try {
+      hook({
+        typeName,
+        path,
+        reason,
+        criteriaCount
+      });
+    } catch (_error) {
+    }
+  };
+  /**
+   * Emit structured index write observability events without impacting behavior.
+   */
+  emitStructuredIndexWrite = (typeName, docId, action, indexedFieldCount) => {
+    const hook = this.config.indexing?.observability?.onStructuredIndexWrite;
+    if (!hook) {
+      return;
+    }
+    try {
+      hook({ typeName, docId, action, indexedFieldCount });
+    } catch (_error) {
+    }
+  };
   resolveAccessingRole = async (context) => {
     const { useDAC } = this.config;
     if (!useDAC) {
@@ -7374,14 +7525,278 @@ var TypeInfoORMService = class {
     return typeInfo;
   };
   /**
-   * @returns Resolved index field name, if available.
+   * @returns Resolved full-text index field names.
    */
-  resolveFullTextIndexField = (typeName, override) => {
+  resolveFullTextIndexFields = (typeName, override) => {
     if (override) {
-      return override;
+      return [override];
+    }
+    const defaults = this.config.indexing?.fullText?.defaultIndexFieldByType?.[typeName];
+    if (typeof defaults === "string") {
+      return [defaults];
+    }
+    if (!Array.isArray(defaults)) {
+      return [];
+    }
+    const seen = /* @__PURE__ */ new Set();
+    const fields = [];
+    for (const field of defaults) {
+      if (typeof field !== "string") {
+        continue;
+      }
+      const trimmed = field.trim();
+      if (!trimmed || seen.has(trimmed)) {
+        continue;
+      }
+      seen.add(trimmed);
+      fields.push(trimmed);
+    }
+    return fields;
+  };
+  /**
+   * @returns True when the operator maps to full-text search.
+   */
+  isFullTextSearchOperator = (operator) => operator === "LIKE" /* LIKE */ || operator === "CONTAINS" /* CONTAINS */ || operator === "STARTS_WITH" /* STARTS_WITH */;
+  /**
+   * @returns Explicitly indexed structured field names for a type.
+   */
+  resolveStructuredIndexedFields = (typeName) => {
+    const configured = this.config.indexing?.structured?.indexedFieldsByType?.[typeName];
+    if (!Array.isArray(configured)) {
+      return /* @__PURE__ */ new Set();
+    }
+    const fields = /* @__PURE__ */ new Set();
+    for (const field of configured) {
+      if (typeof field !== "string") {
+        continue;
+      }
+      const trimmed = field.trim();
+      if (trimmed) {
+        fields.add(trimmed);
+      }
+    }
+    return fields;
+  };
+  /**
+   * @returns True when the field type and operator can be served by structured indexing.
+   */
+  isStructuredOperatorSupportedForField = (field, operator) => {
+    const { array: isArray = false, type } = field;
+    if (isArray) {
+      return operator === "CONTAINS" /* CONTAINS */;
+    }
+    if (type === "string") {
+      return operator === "EQUALS" /* EQUALS */ || operator === "IN" /* IN */ || operator === "LIKE" /* LIKE */ || operator === "GREATER_THAN_OR_EQUAL" /* GREATER_THAN_OR_EQUAL */ || operator === "LESS_THAN_OR_EQUAL" /* LESS_THAN_OR_EQUAL */ || operator === "BETWEEN" /* BETWEEN */;
+    }
+    if (type === "number") {
+      return operator === "EQUALS" /* EQUALS */ || operator === "IN" /* IN */ || operator === "GREATER_THAN_OR_EQUAL" /* GREATER_THAN_OR_EQUAL */ || operator === "LESS_THAN_OR_EQUAL" /* LESS_THAN_OR_EQUAL */ || operator === "BETWEEN" /* BETWEEN */;
+    }
+    if (type === "boolean") {
+      return operator === "EQUALS" /* EQUALS */ || operator === "IN" /* IN */;
+    }
+    return false;
+  };
+  /**
+   * @returns True when criteria can be evaluated using structured indexing.
+   */
+  canUseStructuredIndexForCriteria = (typeName, criteria) => {
+    if (!criteria?.fieldCriteria?.length) {
+      return false;
+    }
+    const typeInfo = this.getTypeInfo(typeName);
+    const { fields = {} } = typeInfo;
+    const indexedFields = this.resolveStructuredIndexedFields(typeName);
+    if (indexedFields.size === 0) {
+      return false;
+    }
+    for (const criterion of criteria.fieldCriteria) {
+      const { fieldName } = criterion;
+      const field = fields[fieldName];
+      if (!field || field.typeReference || !indexedFields.has(fieldName)) {
+        return false;
+      }
+      const operator = criterion.operator ?? "EQUALS" /* EQUALS */;
+      if (!this.isStructuredOperatorSupportedForField(field, operator)) {
+        return false;
+      }
+    }
+    return true;
+  };
+  /**
+   * @returns Full-text query plan derived from a field criterion.
+   */
+  toFullTextSearchPlan = (criterion) => {
+    const operator = criterion.operator ?? "EQUALS" /* EQUALS */;
+    if (!this.isFullTextSearchOperator(operator)) {
+      return void 0;
+    }
+    if (typeof criterion.value !== "string") {
+      throw {
+        message: "INDEXING_UNSUPPORTED_CRITERIA" /* INDEXING_UNSUPPORTED_CRITERIA */,
+        operator,
+        fieldName: criterion.fieldName
+      };
+    }
+    const query = criterion.value.trim();
+    if (!query) {
+      throw {
+        message: "INDEXING_UNSUPPORTED_CRITERIA" /* INDEXING_UNSUPPORTED_CRITERIA */,
+        operator,
+        fieldName: criterion.fieldName
+      };
+    }
+    if (operator === "CONTAINS" /* CONTAINS */) {
+      return {
+        mode: "exact",
+        query
+      };
+    }
+    if (operator === "STARTS_WITH" /* STARTS_WITH */) {
+      return {
+        mode: "lossy",
+        query: `${query}*`
+      };
+    }
+    return {
+      mode: "lossy",
+      query
+    };
+  };
+  /**
+   * @returns Auto full-text search plan for list criteria, if applicable.
+   */
+  resolveAutoFullTextCriteriaPlan = (typeName, criteria) => {
+    if (!criteria?.fieldCriteria?.length) {
+      return void 0;
+    }
+    const configuredIndexFields = new Set(
+      this.resolveFullTextIndexFields(typeName)
+    );
+    if (configuredIndexFields.size === 0) {
+      return void 0;
+    }
+    const fullTextCandidates = [];
+    let hasNonFullTextCriteria = false;
+    for (const criterion of criteria.fieldCriteria) {
+      const indexField = criterion.fieldName;
+      if (!configuredIndexFields.has(indexField)) {
+        hasNonFullTextCriteria = true;
+        continue;
+      }
+      const plan = this.toFullTextSearchPlan(criterion);
+      if (!plan) {
+        hasNonFullTextCriteria = true;
+        continue;
+      }
+      fullTextCandidates.push({
+        ...plan,
+        indexField
+      });
+    }
+    if (fullTextCandidates.length === 0) {
+      return void 0;
+    }
+    if (hasNonFullTextCriteria || fullTextCandidates.length > 1 || criteria.logicalOperator === "OR" /* OR */) {
+      throw {
+        message: "INDEXING_UNSUPPORTED_COMBINATION" /* INDEXING_UNSUPPORTED_COMBINATION */,
+        typeName
+      };
+    }
+    return fullTextCandidates[0];
+  };
+  /**
+   * @returns Encoded cursor for full-scan compare pagination.
+   */
+  encodeFullScanCompareCursor = (offset) => JSON.stringify({ fullScanCompareOffset: offset });
+  /**
+   * @returns Decoded offset for full-scan compare pagination.
+   */
+  decodeFullScanCompareCursor = (cursor) => {
+    if (!cursor) {
+      return 0;
+    }
+    try {
+      const parsed = JSON.parse(cursor);
+      const offset = parsed.fullScanCompareOffset;
+      if (!Number.isFinite(offset) || offset < 0) {
+        throw new Error("Invalid full scan cursor offset");
+      }
+      return offset;
+    } catch (_error) {
+      throw {
+        message: "INVALID_CURSOR" /* INVALID_CURSOR */,
+        cursor
+      };
     }
-    return this.config.indexing?.fullText?.defaultIndexFieldByType?.[typeName];
   };
+  /**
+   * Execute a criteria list via full scan + in-memory compare.
+   *
+   * This is the universal fallback strategy for criteria/operators that are not
+   * supported by indexed query planners.
+   *
+   * @returns List results with cursor.
+   */
+  async listByFullScanAndCompare(typeName, config, cleanSelectedFields, useDAC, context) {
+    const driver = this.getDriverInternal(typeName);
+    const { criteria, sortFields, itemsPerPage = 10, cursor } = config;
+    const allItems = [];
+    let scanCursor;
+    while (true) {
+      const page = await driver.listItems({
+        itemsPerPage: 250,
+        cursor: scanCursor
+      });
+      allItems.push(...page.items ?? []);
+      if (!page.cursor || page.cursor === scanCursor) {
+        break;
+      }
+      scanCursor = page.cursor;
+    }
+    const filtered = criteria ? getFilterTypeInfoDataItemsBySearchCriteria(
+      criteria,
+      allItems,
+      typeName,
+      this.config.typeInfoMap
+    ) : allItems;
+    const sorted = getSortedItems(sortFields, filtered);
+    let index = this.decodeFullScanCompareCursor(cursor);
+    const cleanedItems = [];
+    while (index < sorted.length && cleanedItems.length < itemsPerPage) {
+      const item = sorted[index];
+      index += 1;
+      let fieldsResources;
+      if (useDAC) {
+        const {
+          allowed: readAllowed,
+          denied: readDenied,
+          fieldsResources: nextFieldsResources = {}
+        } = await this.getItemDACValidation(
+          item,
+          typeName,
+          "READ" /* READ */,
+          context
+        );
+        const listDenied = readDenied || !readAllowed;
+        if (listDenied) {
+          continue;
+        }
+        fieldsResources = nextFieldsResources;
+      }
+      cleanedItems.push(
+        this.getCleanItem(
+          typeName,
+          item,
+          fieldsResources,
+          cleanSelectedFields
+        )
+      );
+    }
+    return {
+      items: cleanedItems,
+      cursor: index < sorted.length ? this.encodeFullScanCompareCursor(index) : void 0
+    };
+  }
   /**
    * @param value Value to check.
    * @returns True when the value is a supported structured value.
@@ -7393,9 +7808,13 @@ var TypeInfoORMService = class {
   buildStructuredFields = (typeName, item) => {
     const typeInfo = this.getTypeInfo(typeName);
     const fieldMap = this.config.indexing?.structured?.fieldMapByType?.[typeName];
+    const indexedFields = this.resolveStructuredIndexedFields(typeName);
     const withoutRefs = removeTypeReferenceFieldsFromDataItem(typeInfo, item);
     const fields = {};
     for (const [fieldName, value] of Object.entries(withoutRefs)) {
+      if (!indexedFields.has(fieldName)) {
+        continue;
+      }
       if (typeof value === "undefined") {
         continue;
       }
@@ -7444,88 +7863,94 @@ var TypeInfoORMService = class {
    */
   async indexFullTextDocument(typeName, item, indexFieldOverride) {
     const { fullText } = this.config.indexing ?? {};
-    const indexField = this.resolveFullTextIndexField(
+    const indexFields = this.resolveFullTextIndexFields(
       typeName,
       indexFieldOverride
     );
-    if (!fullText || !indexField) {
+    if (!fullText || indexFields.length === 0) {
       return;
     }
-    const qualifiedIndexField = qualifyIndexField(typeName, indexField);
     const { primaryField } = this.getTypeInfo(typeName);
-    if (!(indexField in item)) {
-      throw {
-        message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
-        typeName,
-        indexField
-      };
+    for (const indexField of indexFields) {
+      const qualifiedIndexField = qualifyIndexField(typeName, indexField);
+      if (!(indexField in item)) {
+        throw {
+          message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
+          typeName,
+          indexField
+        };
+      }
+      await indexDocument({
+        backend: fullText.backend,
+        document: item,
+        primaryField: String(primaryField),
+        indexField,
+        indexFieldQualified: qualifiedIndexField
+      });
     }
-    await indexDocument({
-      backend: fullText.backend,
-      document: item,
-      primaryField: String(primaryField),
-      indexField,
-      indexFieldQualified: qualifiedIndexField
-    });
   }
   /**
    * @returns Promise resolved once removal is complete.
    */
   async removeFullTextDocument(typeName, item, indexFieldOverride) {
     const { fullText } = this.config.indexing ?? {};
-    const indexField = this.resolveFullTextIndexField(
+    const indexFields = this.resolveFullTextIndexFields(
       typeName,
       indexFieldOverride
     );
-    if (!fullText || !indexField) {
+    if (!fullText || indexFields.length === 0) {
       return;
     }
-    const qualifiedIndexField = qualifyIndexField(typeName, indexField);
     const { primaryField } = this.getTypeInfo(typeName);
-    if (!(indexField in item)) {
-      throw {
-        message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
-        typeName,
-        indexField
-      };
+    for (const indexField of indexFields) {
+      const qualifiedIndexField = qualifyIndexField(typeName, indexField);
+      if (!(indexField in item)) {
+        throw {
+          message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
+          typeName,
+          indexField
+        };
+      }
+      await removeDocument({
+        backend: fullText.backend,
+        document: item,
+        primaryField: String(primaryField),
+        indexField,
+        indexFieldQualified: qualifiedIndexField
+      });
     }
-    await removeDocument({
-      backend: fullText.backend,
-      document: item,
-      primaryField: String(primaryField),
-      indexField,
-      indexFieldQualified: qualifiedIndexField
-    });
   }
   /**
    * @returns Promise resolved once replacement is complete.
    */
   async replaceFullTextDocument(typeName, previousItem, nextItem, indexFieldOverride) {
     const { fullText } = this.config.indexing ?? {};
-    const indexField = this.resolveFullTextIndexField(
+    const indexFields = this.resolveFullTextIndexFields(
       typeName,
       indexFieldOverride
     );
-    if (!fullText || !indexField) {
+    if (!fullText || indexFields.length === 0) {
       return;
     }
-    const qualifiedIndexField = qualifyIndexField(typeName, indexField);
     const { primaryField } = this.getTypeInfo(typeName);
-    if (!(indexField in previousItem)) {
-      throw {
-        message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
-        typeName,
-        indexField
-      };
+    for (const indexField of indexFields) {
+      const qualifiedIndexField = qualifyIndexField(typeName, indexField);
+      if (!(indexField in previousItem)) {
+        throw {
+          message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
+          typeName,
+          indexField
+        };
+      }
+      await replaceFullTextDocument({
+        backend: fullText.backend,
+        previousDocument: previousItem,
+        nextDocument: nextItem,
+        primaryField: String(primaryField),
+        indexField,
+        indexFieldQualified: qualifiedIndexField
+      });
     }
-    await replaceFullTextDocument({
-      backend: fullText.backend,
-      previousDocument: previousItem,
-      nextDocument: nextItem,
-      primaryField: String(primaryField),
-      indexField,
-      indexFieldQualified: qualifiedIndexField
-    });
   }
   /**
    * @returns Promise resolved once indexing is complete.
@@ -7549,6 +7974,12 @@ var TypeInfoORMService = class {
       primaryFieldName
     );
     const fields = this.buildStructuredFields(typeName, item);
+    this.emitStructuredIndexWrite(
+      typeName,
+      String(docId),
+      "upsert",
+      Object.keys(fields).length
+    );
     await structured.writer.write(docId, fields);
   }
   /**
@@ -7572,6 +8003,7 @@ var TypeInfoORMService = class {
       item[primaryFieldName],
       primaryFieldName
     );
+    this.emitStructuredIndexWrite(typeName, String(docId), "remove", 0);
     await structured.writer.write(docId, {});
   }
   /**
@@ -8249,7 +8681,7 @@ var TypeInfoORMService = class {
     this.validateReadOperation(typeName, cleanSelectedFields);
     const { typeInfoMap, useDAC, indexing } = this.config;
     this.getTypeInfo(typeName);
-    const { criteria, text, itemsPerPage, cursor, sortFields } = config;
+    const { criteria, itemsPerPage, cursor, sortFields } = config;
     const { fieldCriteria = [] } = criteria || {};
     const searchFieldValidationResults = validateSearchFields(
       typeName,
@@ -8260,55 +8692,36 @@ var TypeInfoORMService = class {
       const hasStructured = !!indexing?.structured?.reader;
       const hasFullText = !!indexing?.fullText?.backend;
       const hasCriteria = !!criteria && fieldCriteria.length > 0;
-      const hasText = !!text;
-      const shouldUseIndexing = !!hasCriteria || !!hasText;
-      if (hasStructured || hasFullText) {
-        if (!shouldUseIndexing) ; else {
-          if (hasCriteria && hasText) {
-            throw {
-              message: "INDEXING_UNSUPPORTED_COMBINATION" /* INDEXING_UNSUPPORTED_COMBINATION */,
-              typeName
-            };
-          }
-          if (hasCriteria && !hasStructured) {
-            throw {
-              message: "INDEXING_MISSING_BACKEND" /* INDEXING_MISSING_BACKEND */,
-              typeName,
-              backend: "structured.reader"
-            };
-          }
-          if (hasText && !hasFullText) {
-            throw {
-              message: "INDEXING_MISSING_BACKEND" /* INDEXING_MISSING_BACKEND */,
-              typeName,
-              backend: "fullText"
-            };
-          }
+      if (hasCriteria && (hasStructured || hasFullText)) {
+        try {
           let docIds = [];
           let nextCursor = void 0;
-          if (hasText) {
-            const indexField = this.resolveFullTextIndexField(
+          const fullTextPlan = this.resolveAutoFullTextCriteriaPlan(
+            typeName,
+            criteria
+          );
+          if (fullTextPlan && hasFullText) {
+            this.emitListRoutingDecision(
               typeName,
-              text?.indexField
+              "fullText",
+              "fullTextPlan",
+              fieldCriteria.length
+            );
+            const qualifiedIndexField = qualifyIndexField(
+              typeName,
+              fullTextPlan.indexField
             );
-            if (!indexField) {
-              throw {
-                message: "INDEXING_MISSING_INDEX_FIELD" /* INDEXING_MISSING_INDEX_FIELD */,
-                typeName
-              };
-            }
-            const qualifiedIndexField = qualifyIndexField(typeName, indexField);
             const fullTextBackend = indexing?.fullText?.backend;
-            const searchResult = text?.mode === "exact" ? await searchExact({
+            const searchResult = fullTextPlan.mode === "exact" ? await searchExact({
               backend: fullTextBackend,
-              query: text.query,
+              query: fullTextPlan.query,
               indexField: qualifiedIndexField,
               limit: itemsPerPage,
               cursor,
               limits: indexing?.limits
             }) : await searchLossy({
               backend: fullTextBackend,
-              query: text?.query ?? "",
+              query: fullTextPlan.query,
               indexField: qualifiedIndexField,
               limit: itemsPerPage,
               cursor,
@@ -8316,9 +8729,25 @@ var TypeInfoORMService = class {
             });
             docIds = searchResult.docIds;
             nextCursor = searchResult.nextCursor;
-          } else {
-            const where = criteriaToStructuredWhere(criteria);
-            if (!where) {
+          } else if (hasStructured) {
+            if (!this.canUseStructuredIndexForCriteria(typeName, criteria)) {
+              throw {
+                message: "INDEXING_UNSUPPORTED_CRITERIA" /* INDEXING_UNSUPPORTED_CRITERIA */,
+                typeName
+              };
+            }
+            this.emitListRoutingDecision(
+              typeName,
+              "structured",
+              "structuredEligible",
+              fieldCriteria.length
+            );
+            const tokenizer = indexing?.structured?.tokenizer;
+            const whereWithTokenizer = criteriaToStructuredWhere(
+              criteria,
+              tokenizer
+            );
+            if (!whereWithTokenizer) {
               throw {
                 message: "INDEXING_UNSUPPORTED_CRITERIA" /* INDEXING_UNSUPPORTED_CRITERIA */,
                 typeName
@@ -8326,7 +8755,7 @@ var TypeInfoORMService = class {
             }
             const mappedWhere = this.applyStructuredFieldMap(
               typeName,
-              where,
+              whereWithTokenizer,
               indexing?.structured?.fieldMapByType?.[typeName]
             );
             const structuredReader = indexing?.structured?.reader;
@@ -8340,6 +8769,11 @@ var TypeInfoORMService = class {
             );
             docIds = page.candidateIds;
             nextCursor = page.cursor;
+          } else {
+            throw {
+              message: "INDEXING_UNSUPPORTED_CRITERIA" /* INDEXING_UNSUPPORTED_CRITERIA */,
+              typeName
+            };
           }
           const driver2 = this.getDriverInternal(typeName);
           const items = [];
@@ -8392,8 +8826,37 @@ var TypeInfoORMService = class {
             items: sortedItems,
             cursor: nextCursor
           };
+        } catch (_error) {
+          this.emitListRoutingDecision(
+            typeName,
+            "fullScanCompare",
+            "indexedPathFailedOrUnsupported",
+            fieldCriteria.length
+          );
+          return this.listByFullScanAndCompare(
+            typeName,
+            config,
+            cleanSelectedFields,
+            useDAC,
+            context
+          );
         }
       }
+      if (hasCriteria) {
+        this.emitListRoutingDecision(
+          typeName,
+          "fullScanCompare",
+          "criteriaWithoutIndexedPath",
+          fieldCriteria.length
+        );
+        return this.listByFullScanAndCompare(
+          typeName,
+          config,
+          cleanSelectedFields,
+          useDAC,
+          context
+        );
+      }
       const driver = this.getDriverInternal(typeName);
       const fieldsResourcesCache = [];
       const results = await executeDriverListItems(