@resistdesign/voltra 3.0.0-alpha.36 → 3.0.0-alpha.38

package/api/Indexing/ddb/Types.d.ts

@@ -74,6 +74,40 @@ export type GetItemOutput = {
      */
     Item?: AttributeMap;
 };
+/**
+ * Input payload for DynamoDB put item operations.
+ */
+export type PutItemInput = {
+    /**
+     * DynamoDB table name.
+     */
+    TableName: string;
+    /**
+     * Item attributes to store.
+     */
+    Item: AttributeMap;
+    /**
+     * Optional conditional expression.
+     */
+    ConditionExpression?: string;
+    /**
+     * Optional expression attribute names.
+     */
+    ExpressionAttributeNames?: Record<string, string>;
+    /**
+     * Optional expression attribute values.
+     */
+    ExpressionAttributeValues?: AttributeMap;
+};
+/**
+ * Output payload from DynamoDB put item operations.
+ */
+export type PutItemOutput = {
+    /**
+     * True when conditional write failed.
+     */
+    conditionFailed?: boolean;
+};
 /**
  * DynamoDB batch write request entry.
  */
@@ -113,6 +147,12 @@ export type DynamoBatchWriter = {
      * @returns Get item output payload.
      */
     getItem(input: GetItemInput): Promise<GetItemOutput>;
+    /**
+     * Execute a DynamoDB put item operation.
+     * @param input Put item input payload.
+     * @returns Put item output payload.
+     */
+    putItem(input: PutItemInput): Promise<PutItemOutput>;
 };
 /**
  * Input payload for DynamoDB query operations.

package/api/Indexing/structured/StructuredDdb.d.ts

@@ -89,6 +89,23 @@ export type StructuredDocFieldsItem = StructuredDocFieldsKey & {
      * Structured fields stored for the document.
      */
     fields: StructuredDocFieldsRecord;
+    /**
+     * Monotonic version used for optimistic concurrency control.
+     */
+    version: number;
+};
+/**
+ * Loaded document fields state with version.
+ */
+export type StructuredDocFieldsState = {
+    /**
+     * Structured fields persisted for the document.
+     */
+    fields: StructuredDocFieldsRecord;
+    /**
+     * Monotonic version for optimistic writes.
+     */
+    version: number;
 };
 /**
  * Schema metadata for the structured term index table.
@@ -115,6 +132,7 @@ export declare const structuredRangeIndexSchema: {
 export declare const structuredDocFieldsSchema: {
     readonly partitionKey: "docId";
     readonly fieldsAttribute: "fields";
+    readonly versionAttribute: "version";
 };
 /**
  * Serialize a structured value for DynamoDB key usage.
@@ -163,4 +181,4 @@ export declare function buildStructuredRangeItem(field: string, value: WhereValu
  * @param fields Structured fields to store.
  * @returns Structured doc fields item.
  */
-export declare function buildStructuredDocFieldsItem(docId: DocId, fields: StructuredDocFieldsRecord): StructuredDocFieldsItem;
+export declare function buildStructuredDocFieldsItem(docId: DocId, fields: StructuredDocFieldsRecord, version: number): StructuredDocFieldsItem;

package/api/Indexing/structured/StructuredDdbBackend.d.ts

@@ -7,7 +7,8 @@ import type { DynamoQueryClient } from "../ddb/Types";
 import type { DocId } from "../Types";
 import type { StructuredSearchDependencies } from "./SearchStructured";
 import type { StructuredQueryOptions, WhereValue } from "./Types";
-import { StructuredDdbWriter } from "./StructuredWriter";
+import type { StructuredStringTokenizerConfig } from "./StructuredStringLike";
+import { StructuredDdbWriter, type StructuredWriterOptions } from "./StructuredWriter";
 /**
  * Deployment-specific DynamoDB table names required for structured indexing.
  */
@@ -24,6 +25,8 @@ export type StructuredTableNames = {
 type StructuredDdbConfig = {
     client: DynamoQueryClient;
     tables: StructuredTableNames;
+    writerOptions?: StructuredWriterOptions;
+    tokenizer?: Partial<StructuredStringTokenizerConfig>;
 };
 /**
  * Read-only structured queries against DynamoDB term/range indexes.

package/api/Indexing/structured/StructuredInMemoryBackend.d.ts

@@ -8,12 +8,18 @@ import type { DocId } from "../Types";
 import type { StructuredSearchDependencies } from "./SearchStructured";
 import type { StructuredWriter } from "./Handlers";
 import type { StructuredDocFieldsRecord } from "./StructuredDdb";
+import type { StructuredStringTokenizerConfig } from "./StructuredStringLike";
 /**
  * In-memory structured backend for tests and local usage.
  */
 export declare class StructuredInMemoryBackend implements StructuredSearchDependencies, StructuredWriter {
+    private readonly tokenizer?;
     private docFields;
     private index;
+    /**
+     * @param tokenizer Optional tokenizer overrides for structured string contains behavior.
+     */
+    constructor(tokenizer?: Partial<StructuredStringTokenizerConfig> | undefined);
     private rebuildIndex;
     private buildPage;
     /**

package/api/Indexing/structured/StructuredInMemoryIndex.d.ts

@@ -1,9 +1,12 @@
 import type { DocId } from "../Types";
+import { type StructuredStringTokenizerConfig } from "./StructuredStringLike";
 import type { CandidatePage, StructuredQueryOptions, WhereValue } from "./Types";
 /**
  * In-memory structured index that builds term/contains/range postings.
  */
 export declare class StructuredInMemoryIndex {
+    private readonly tokenizer?;
+    constructor(tokenizer?: Partial<StructuredStringTokenizerConfig> | undefined);
     private eqIndex;
     private containsIndex;
     private rangeIndex;

package/api/Indexing/structured/StructuredStringLike.d.ts

@@ -3,6 +3,35 @@ import type { WhereValue } from "./Types";
  * Prefix marker for structured string contains tokens.
  */
 export declare const STRUCTURED_STRING_CONTAINS_TOKEN_PREFIX = "__str__:";
+/**
+ * Tokenizer settings for structured string contains/LIKE behavior.
+ */
+export type StructuredStringTokenizerConfig = {
+    /**
+     * Minimum ngram size to generate.
+     */
+    minNgramSize: number;
+    /**
+     * Maximum ngram size to generate.
+     */
+    maxNgramSize: number;
+    /**
+     * Maximum source string length to tokenize.
+     */
+    maxIndexedStringLength: number;
+    /**
+     * Maximum number of tokens emitted per value.
+     */
+    maxTokensPerValue: number;
+};
+/**
+ * Safe defaults that preserve current behavior.
+ */
+export declare const DEFAULT_STRUCTURED_STRING_TOKENIZER_CONFIG: StructuredStringTokenizerConfig;
+/**
+ * Resolve tokenizer config with validation and sane defaults.
+ */
+export declare const resolveStructuredStringTokenizerConfig: (config?: Partial<StructuredStringTokenizerConfig>) => StructuredStringTokenizerConfig;
 /**
  * Normalize a string for structured LIKE matching.
  * - lowercase
@@ -13,12 +42,12 @@ export declare const normalizeStructuredLikeString: (value: string) => string;
 /**
  * Build contains tokens for an indexed structured string field value.
  */
-export declare const buildStructuredStringContainsTokens: (value: string) => string[];
+export declare const buildStructuredStringContainsTokens: (value: string, tokenizerConfig?: Partial<StructuredStringTokenizerConfig>) => string[];
 /**
  * Build contains tokens for a SQL-like pattern. `%` and `_` are wildcard
  * markers; when no wildcard exists, value behaves as `%value%`.
  */
-export declare const buildStructuredLikePatternTokens: (value: string) => string[];
+export declare const buildStructuredLikePatternTokens: (value: string, tokenizerConfig?: Partial<StructuredStringTokenizerConfig>) => string[];
 /**
  * True when this contains query value is a generated string token.
  */

package/api/Indexing/structured/StructuredWriter.d.ts

@@ -1,5 +1,6 @@
 import type { DocId } from "../Types";
-import type { StructuredDocFieldsRecord, StructuredRangeIndexItem, StructuredRangeIndexKey, StructuredTermIndexItem, StructuredTermIndexKey } from "./StructuredDdb";
+import type { StructuredDocFieldsState, StructuredDocFieldsRecord, StructuredRangeIndexItem, StructuredRangeIndexKey, StructuredTermIndexItem, StructuredTermIndexKey } from "./StructuredDdb";
+import { type StructuredStringTokenizerConfig } from "./StructuredStringLike";
 /**
  * Dependencies required to persist structured index entries.
  */
@@ -9,14 +10,15 @@ export type StructuredWriterDependencies = {
      * @param docId Document id to load.
      * @returns Stored fields or undefined when missing.
      */
-    loadDocFields(docId: DocId): Promise<StructuredDocFieldsRecord | undefined>;
+    loadDocFieldsState(docId: DocId): Promise<StructuredDocFieldsState | undefined>;
     /**
-     * Store the latest fields for a document.
+     * Compare-and-swap the latest fields for a document.
      * @param docId Document id to store.
+     * @param expectedVersion Version expected by the caller.
      * @param fields Structured fields to persist.
-     * @returns Promise resolved once stored.
+     * @returns True when swap succeeds, false on version mismatch.
      */
-    putDocFields(docId: DocId, fields: StructuredDocFieldsRecord): Promise<void>;
+    putDocFieldsIfVersion(docId: DocId, expectedVersion: number | undefined, fields: StructuredDocFieldsRecord): Promise<boolean>;
     /**
      * Store term index entries.
      * @param entries Term entries to store.
@@ -42,15 +44,26 @@ export type StructuredWriterDependencies = {
      */
     deleteRangeEntries(entries: StructuredRangeIndexKey[]): Promise<void>;
 };
+export type StructuredWriterOptions = {
+    /**
+     * Optional tokenizer settings for string contains indexing.
+     */
+    tokenizer?: Partial<StructuredStringTokenizerConfig>;
+    /**
+     * Maximum compare-and-swap retries for concurrent writes.
+     */
+    maxConcurrentWriteRetries?: number;
+};
 /**
  * Writer that diffs structured fields and persists term/range entries.
  */
 export declare class StructuredDdbWriter {
     private readonly dependencies;
+    private readonly options;
     /**
      * @param dependencies Writer dependencies for persistence.
      */
-    constructor(dependencies: StructuredWriterDependencies);
+    constructor(dependencies: StructuredWriterDependencies, options?: StructuredWriterOptions);
     /**
      * Write structured fields for a document, diffing term/range entries.
      * @param docId Document id to write.

package/api/ORM/TypeInfoORMService.d.ts

@@ -5,9 +5,9 @@
  * and optionally provide DAC and indexing integrations. The constructor validates
  * configuration once, and each call resolves drivers as needed.
  */
-import { LiteralValue, TypeInfo, TypeInfoDataItem, TypeInfoMap, TypeOperation } from "../../common/TypeParsing/TypeInfo";
+import { LiteralValue, TypeInfo, TypeInfoDataItem, TypeInfoField, TypeInfoMap, TypeOperation } from "../../common/TypeParsing/TypeInfo";
 import { CustomTypeInfoFieldValidatorMap } from "../../common/TypeParsing/Validation";
-import { ListItemsConfig, ListItemsResults, ListRelationshipsConfig } from "../../common/SearchTypes";
+import { ComparisonOperators, FieldCriterion, ListItemsConfig, ListItemsResults, ListRelationshipsConfig, SearchCriteria } from "../../common/SearchTypes";
 import { DeleteRelationshipResults, RelationshipOperation, TypeInfoORMAPI, TypeInfoORMContext } from "../../common/TypeInfoORM";
 import { DataItemDBDriver, IndexingRelationshipDriver, ItemRelationshipDBDriver } from "./drivers";
 import { BaseItemRelationshipInfo, ItemRelationshipInfo, ItemRelationshipInfoKeys, ItemRelationshipInfoType, ItemRelationshipOriginatingItemInfo } from "../../common/ItemRelationshipInfoTypes";
@@ -18,6 +18,7 @@ import type { StructuredWriter } from "../Indexing/structured/Handlers";
 import type { ResolvedSearchLimits } from "../Indexing/Handler/Config";
 import type { StructuredDocFieldsRecord } from "../Indexing/structured/StructuredDdb";
 import type { Where, WhereValue } from "../Indexing/structured/Types";
+import type { StructuredStringTokenizerConfig } from "../Indexing/structured/StructuredStringLike";
 import type { RelationalBackend } from "./drivers/IndexingRelationshipDriver";
 /**
  * Strip a relationship item down to its identifying keys.
@@ -91,9 +92,9 @@ export type TypeInfoORMIndexingConfig = {
          */
         backend: IndexBackend;
         /**
-         * Default index field names by type.
+         * Default index field name(s) by type.
          */
-        defaultIndexFieldByType?: Record<string, string>;
+        defaultIndexFieldByType?: Record<string, string | string[]>;
     };
     /**
      * Structured indexing configuration.
@@ -107,6 +108,15 @@ export type TypeInfoORMIndexingConfig = {
          * Optional writer for structured indexing.
          */
         writer?: StructuredWriter;
+        /**
+         * Explicitly indexed field names by type. Fields not listed are excluded
+         * from structured indexing and structured query routing.
+         */
+        indexedFieldsByType?: Record<string, string[]>;
+        /**
+         * Optional tokenizer overrides for structured string contains/LIKE behavior.
+         */
+        tokenizer?: Partial<StructuredStringTokenizerConfig>;
         /**
          * Field name mapping per type.
          */
@@ -137,6 +147,29 @@ export type TypeInfoORMIndexingConfig = {
      * Optional search limits for indexing queries.
      */
     limits?: ResolvedSearchLimits;
+    /**
+     * Optional observability hooks for indexing/routing diagnostics.
+     */
+    observability?: {
+        /**
+         * Called when list routing chooses a query execution path.
+         */
+        onListRoutingDecision?: (event: {
+            typeName: string;
+            path: "fullText" | "structured" | "fullScanCompare";
+            reason: "fullTextPlan" | "structuredEligible" | "criteriaWithoutIndexedPath" | "indexedPathFailedOrUnsupported";
+            criteriaCount: number;
+        }) => void;
+        /**
+         * Called when structured indexing writes/removes document entries.
+         */
+        onStructuredIndexWrite?: (event: {
+            typeName: string;
+            docId: string;
+            action: "upsert" | "remove";
+            indexedFieldCount: number;
+        }) => void;
+    };
 };
 /**
  * The basis for the configuration for the TypeInfoORMService.
@@ -187,6 +220,46 @@ export declare class TypeInfoORMService implements TypeInfoORMAPI {
     protected config: TypeInfoORMServiceConfig;
     protected dacRoleCache: Record<string, DACRole>;
     protected indexingRelationshipDriver?: IndexingRelationshipDriver;
+    /**
+     * Emit list routing decision observability events without impacting runtime behavior.
+     */
+    protected emitListRoutingDecision: (
+    /**
+     * Type being listed.
+     */
+    typeName: string, 
+    /**
+     * Selected routing path.
+     */
+    path: "fullText" | "structured" | "fullScanCompare", 
+    /**
+     * Why this path was selected.
+     */
+    reason: "fullTextPlan" | "structuredEligible" | "criteriaWithoutIndexedPath" | "indexedPathFailedOrUnsupported", 
+    /**
+     * Number of criteria considered.
+     */
+    criteriaCount: number) => void;
+    /**
+     * Emit structured index write observability events without impacting behavior.
+     */
+    protected emitStructuredIndexWrite: (
+    /**
+     * Type being indexed.
+     */
+    typeName: string, 
+    /**
+     * Indexed document id.
+     */
+    docId: string, 
+    /**
+     * Structured indexing action.
+     */
+    action: "upsert" | "remove", 
+    /**
+     * Number of indexed fields in the write payload.
+     */
+    indexedFieldCount: number) => void;
     /**
      * @param config ORM service configuration.
      */
@@ -267,17 +340,129 @@ export declare class TypeInfoORMService implements TypeInfoORMAPI {
      */
     protected getTypeInfo: (typeName: string) => TypeInfo;
     /**
-     * @returns Resolved index field name, if available.
+     * @returns Resolved full-text index field names.
      */
-    protected resolveFullTextIndexField: (
+    protected resolveFullTextIndexFields: (
     /**
-     * Type name used to resolve the default index field.
+     * Type name used to resolve the default index field(s).
      */
     typeName: string, 
     /**
      * Optional override for the index field.
      */
-    override?: string) => string | undefined;
+    override?: string) => string[];
+    /**
+     * @returns True when the operator maps to full-text search.
+     */
+    protected isFullTextSearchOperator: (
+    /**
+     * Operator to evaluate.
+     */
+    operator: ComparisonOperators) => boolean;
+    /**
+     * @returns Explicitly indexed structured field names for a type.
+     */
+    protected resolveStructuredIndexedFields: (
+    /**
+     * Type name used to resolve indexed structured fields.
+     */
+    typeName: string) => Set<string>;
+    /**
+     * @returns True when the field type and operator can be served by structured indexing.
+     */
+    protected isStructuredOperatorSupportedForField: (
+    /**
+     * Field definition from TypeInfo.
+     */
+    field: TypeInfoField, 
+    /**
+     * Search operator to evaluate.
+     */
+    operator: ComparisonOperators) => boolean;
+    /**
+     * @returns True when criteria can be evaluated using structured indexing.
+     */
+    protected canUseStructuredIndexForCriteria: (
+    /**
+     * Type being listed.
+     */
+    typeName: string, 
+    /**
+     * Criteria to evaluate.
+     */
+    criteria?: SearchCriteria) => boolean;
+    /**
+     * @returns Full-text query plan derived from a field criterion.
+     */
+    protected toFullTextSearchPlan: (
+    /**
+     * Criterion to map.
+     */
+    criterion: FieldCriterion) => {
+        mode: "lossy" | "exact";
+        query: string;
+    } | undefined;
+    /**
+     * @returns Auto full-text search plan for list criteria, if applicable.
+     */
+    protected resolveAutoFullTextCriteriaPlan: (
+    /**
+     * Type being listed.
+     */
+    typeName: string, 
+    /**
+     * Search criteria from list config.
+     */
+    criteria?: SearchCriteria) => {
+        mode: "lossy" | "exact";
+        query: string;
+        indexField: string;
+    } | undefined;
+    /**
+     * @returns Encoded cursor for full-scan compare pagination.
+     */
+    protected encodeFullScanCompareCursor: (
+    /**
+     * Next offset in filtered/sorted results.
+     */
+    offset: number) => string;
+    /**
+     * @returns Decoded offset for full-scan compare pagination.
+     */
+    protected decodeFullScanCompareCursor: (
+    /**
+     * Cursor from list config.
+     */
+    cursor?: string) => number;
+    /**
+     * 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.
+     */
+    protected listByFullScanAndCompare(
+    /**
+     * Type name to list.
+     */
+    typeName: string, 
+    /**
+     * Original list config.
+     */
+    config: ListItemsConfig, 
+    /**
+     * Selected fields for cleaned response.
+     */
+    cleanSelectedFields: (keyof TypeInfoDataItem)[] | undefined, 
+    /**
+     * Whether DAC checks are enabled.
+     */
+    useDAC: boolean, 
+    /**
+     * Optional request context.
+     */
+    context?: TypeInfoORMContext): Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;
     /**
      * @param value Value to check.
      * @returns True when the value is a supported structured value.

package/api/ORM/indexing/criteriaToStructuredWhere.d.ts

@@ -6,6 +6,7 @@
  */
 import { SearchCriteria } from "../../../common/SearchTypes";
 import type { Where } from "../../Indexing/structured/Types";
+import { type StructuredStringTokenizerConfig } from "../../Indexing/structured/StructuredStringLike";
 /**
  * Translate {@link SearchCriteria.fieldCriteria} into a structured WHERE tree.
  * @returns Structured where clause or undefined when no criteria exist.
@@ -14,4 +15,8 @@ export declare const criteriaToStructuredWhere: (
 /**
  * Search criteria to translate.
  */
-criteria?: SearchCriteria) => Where | undefined;
+criteria?: SearchCriteria, 
+/**
+ * Optional tokenizer settings used to generate LIKE tokens.
+ */
+tokenizer?: Partial<StructuredStringTokenizerConfig>) => Where | undefined;