@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

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

@@ -0,0 +1,169 @@
+export type AttributeMap = Record<string, unknown>;
+/**
+ * Input payload for DynamoDB batch write operations.
+ */
+export type BatchWriteItemInput = {
+    /**
+     * DynamoDB batch write request items by table name.
+     */
+    RequestItems: Record<string, WriteRequest[]>;
+};
+/**
+ * Output payload from DynamoDB batch write operations.
+ */
+export type BatchWriteItemOutput = {
+    /**
+     * Unprocessed write requests to retry.
+     */
+    UnprocessedItems?: Record<string, WriteRequest[]>;
+};
+/**
+ * DynamoDB batch get keys and projection configuration.
+ */
+export type KeysAndAttributes = {
+    /**
+     * Keys to read in a batch get request.
+     */
+    Keys: AttributeMap[];
+    /**
+     * Optional projection expression to limit returned attributes.
+     */
+    ProjectionExpression?: string;
+};
+/**
+ * Input payload for DynamoDB batch get operations.
+ */
+export type BatchGetItemInput = {
+    /**
+     * DynamoDB batch get request items by table name.
+     */
+    RequestItems: Record<string, KeysAndAttributes>;
+};
+/**
+ * Output payload from DynamoDB batch get operations.
+ */
+export type BatchGetItemOutput = {
+    /**
+     * Response items keyed by table name.
+     */
+    Responses?: Record<string, AttributeMap[]>;
+    /**
+     * Unprocessed keys to retry.
+     */
+    UnprocessedKeys?: Record<string, KeysAndAttributes>;
+};
+/**
+ * Input payload for DynamoDB get item operations.
+ */
+export type GetItemInput = {
+    /**
+     * DynamoDB table name.
+     */
+    TableName: string;
+    /**
+     * Key attributes for the item.
+     */
+    Key: AttributeMap;
+};
+/**
+ * Output payload from DynamoDB get item operations.
+ */
+export type GetItemOutput = {
+    /**
+     * Returned item attributes.
+     */
+    Item?: AttributeMap;
+};
+/**
+ * DynamoDB batch write request entry.
+ */
+export type WriteRequest = {
+    /**
+     * Put request for an item.
+     */
+    PutRequest?: {
+        Item: AttributeMap;
+    };
+    /**
+     * Delete request for an item.
+     */
+    DeleteRequest?: {
+        Key: AttributeMap;
+    };
+};
+/**
+ * DynamoDB client interface for batch writes/reads and get operations.
+ */
+export type DynamoBatchWriter = {
+    /**
+     * Execute a DynamoDB batch write operation.
+     * @param input Batch write input payload.
+     * @returns Batch write output payload.
+     */
+    batchWriteItem(input: BatchWriteItemInput): Promise<BatchWriteItemOutput>;
+    /**
+     * Execute a DynamoDB batch get operation.
+     * @param input Batch get input payload.
+     * @returns Batch get output payload.
+     */
+    batchGetItem(input: BatchGetItemInput): Promise<BatchGetItemOutput>;
+    /**
+     * Execute a DynamoDB get item operation.
+     * @param input Get item input payload.
+     * @returns Get item output payload.
+     */
+    getItem(input: GetItemInput): Promise<GetItemOutput>;
+};
+/**
+ * Input payload for DynamoDB query operations.
+ */
+export type QueryInput = {
+    /**
+     * DynamoDB table name.
+     */
+    TableName: string;
+    /**
+     * Key condition expression for the query.
+     */
+    KeyConditionExpression: string;
+    /**
+     * Expression attribute name mappings.
+     */
+    ExpressionAttributeNames?: Record<string, string>;
+    /**
+     * Expression attribute values for the query.
+     */
+    ExpressionAttributeValues: AttributeMap;
+    /**
+     * Exclusive start key for pagination.
+     */
+    ExclusiveStartKey?: AttributeMap;
+    /**
+     * Maximum number of items to return.
+     */
+    Limit?: number;
+};
+/**
+ * Output payload from DynamoDB query operations.
+ */
+export type QueryOutput = {
+    /**
+     * Items returned by the query.
+     */
+    Items?: AttributeMap[];
+    /**
+     * Last evaluated key for pagination.
+     */
+    LastEvaluatedKey?: AttributeMap;
+};
+/**
+ * DynamoDB client interface with query support.
+ */
+export type DynamoQueryClient = DynamoBatchWriter & {
+    /**
+     * Execute a DynamoDB query operation.
+     * @param input Query input payload.
+     * @returns Query output payload.
+     */
+    query(input: QueryInput): Promise<QueryOutput>;
+};

package/api/Indexing/docId.d.ts

@@ -0,0 +1,27 @@
+import type { DocId } from "./Types";
+/**
+ * Compare two document ids for sorting.
+ * @returns -1 if left < right, 1 if left > right, or 0 if equal.
+ * */
+export declare function compareDocId(
+/**
+ * Left document id to compare.
+ */
+left: DocId, 
+/**
+ * Right document id to compare.
+ */
+right: DocId): number;
+/**
+ * Normalize a document id and enforce that a primary field exists.
+ * @returns Normalized document id as a string.
+ * */
+export declare function normalizeDocId(
+/**
+ * Raw document id value to normalize.
+ */
+value: unknown, 
+/**
+ * Primary field name used for error messaging.
+ */
+primaryField: string): DocId;

package/api/Indexing/exact/ExactDdb.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @packageDocumentation
+ *
+ * DynamoDB schema helpers for the exact (position-aware) postings table.
+ * The exact index stores token positions per document to support phrase queries.
+ */
+import type { DocId } from "../Types";
+/**
+ * DynamoDB key shape for exact postings items.
+ */
+export type ExactDdbKey = {
+    /**
+     * Token value stored in the exact index.
+     */
+    token: string;
+    /**
+     * Field name the token was indexed under.
+     */
+    indexField: string;
+    /**
+     * Document id containing the token.
+     */
+    docId: DocId;
+};
+/**
+ * DynamoDB item shape for exact postings entries.
+ */
+export type ExactDdbItem = ExactDdbKey & {
+    /**
+     * Token positions within the document.
+     */
+    positions: number[];
+};
+/**
+ * Schema metadata for the exact postings table.
+ */
+export declare const exactDdbSchema: {
+    readonly partitionKey: "token";
+    readonly sortKey: "docId";
+    readonly positionsAttribute: "positions";
+};
+/**
+ * Build the DynamoDB key for an exact postings item.
+ * @param token Token value stored in the exact index.
+ * @param indexField Field name the token was indexed under.
+ * @param docId Document id containing the token.
+ * @returns Exact postings key for DynamoDB.
+ */
+export declare function buildExactDdbKey(token: string, indexField: string, docId: DocId): ExactDdbKey;
+/**
+ * Build a DynamoDB item for an exact postings entry.
+ * @param token Token value stored in the exact index.
+ * @param indexField Field name the token was indexed under.
+ * @param docId Document id containing the token.
+ * @param positions Token positions within the document.
+ * @returns Exact postings item for DynamoDB.
+ */
+export declare function buildExactDdbItem(token: string, indexField: string, docId: DocId, positions: number[]): ExactDdbItem;

package/api/Indexing/exact/ExactIndex.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @packageDocumentation
+ *
+ * In-memory exact index that stores token positions per document. Useful for
+ * tests and local workflows where you want phrase verification without DynamoDB.
+ */
+import type { DocId } from "../Types";
+/**
+ * Paging options for exact phrase verification.
+ */
+export type ExactQueryOptions = {
+    /**
+     * Maximum number of verified results to return.
+     */
+    limit?: number;
+    /**
+     * Resume cursor using the last processed doc id.
+     */
+    lastDocId?: DocId;
+};
+/**
+ * Results for exact phrase verification.
+ */
+export type ExactQueryResult = {
+    /**
+     * Verified document ids matching the phrase.
+     */
+    docIds: DocId[];
+    /**
+     * Cursor to resume verification for remaining candidates.
+     */
+    nextCursor?: DocId;
+};
+/**
+ * In-memory exact index for token positions and phrase checks.
+ */
+export declare class ExactIndex {
+    private postings;
+    private buildTokenKey;
+    /**
+     * Add exact token positions for a document.
+     * @param token Token value to store positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @param positions Token positions within the document.
+     * @returns Nothing.
+     */
+    addPositions(token: string, indexField: string, docId: DocId, positions: number[]): void;
+    /**
+     * Remove exact token positions for a document.
+     * @param token Token value to remove positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Nothing.
+     */
+    removePositions(token: string, indexField: string, docId: DocId): void;
+    /**
+     * Add a document by enumerating positions for each token.
+     * @param docId Document id to add.
+     * @param indexField Field name the tokens are indexed under.
+     * @param tokens Token list for the document.
+     * @returns Nothing.
+     */
+    addDocument(docId: DocId, indexField: string, tokens: string[]): void;
+    /**
+     * Load exact positions for a token in a document.
+     * @param token Token value to retrieve positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Positions array or undefined if not found.
+     */
+    getPositions(token: string, indexField: string, docId: DocId): number[] | undefined;
+    /**
+     * Check if a document contains an exact phrase.
+     * @param docId Document id to verify.
+     * @param indexField Field name the tokens are indexed under.
+     * @param phraseTokens Token sequence representing the phrase.
+     * @returns True when the phrase exists in the document.
+     */
+    hasPhrase(docId: DocId, indexField: string, phraseTokens: string[]): boolean;
+    /**
+     * Verify candidate documents against a phrase, with optional paging.
+     * @param phraseTokens Token sequence representing the phrase.
+     * @param indexField Field name the tokens are indexed under.
+     * @param candidates Candidate document ids to verify.
+     * @param options Paging options for verification.
+     * @returns Verified results and optional next cursor.
+     */
+    verifyCandidates(phraseTokens: string[], indexField: string, candidates: DocId[], options?: ExactQueryOptions): ExactQueryResult;
+}

package/api/Indexing/exact/ExactS3.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @packageDocumentation
+ *
+ * S3 key helpers for the exact (position-aware) index. The S3 layout stores
+ * token postings with positions encoded in JSON for batch retrieval.
+ */
+import type { DocId } from "../Types";
+/**
+ * Location of an exact postings object in S3.
+ */
+export type ExactS3Pointer = {
+    /**
+     * Bucket name containing the exact postings object.
+     */
+    bucket: string;
+    /**
+     * Object key for the exact postings object.
+     */
+    key: string;
+};
+/**
+ * Build the S3 key for an exact postings object.
+ * @param token Token value stored in the exact index.
+ * @param indexField Field name the token was indexed under.
+ * @param docId Document id containing the token.
+ * @returns Object key for the exact postings JSON.
+ */
+export declare function buildExactS3Key(token: string, indexField: string, docId: DocId): string;
+/**
+ * Store exact token positions for a pointer.
+ * @param pointer Bucket/key pair for the postings object.
+ * @param positions Token positions within the document.
+ * @returns Promise resolved once positions are stored.
+ */
+export declare function storeExactPositions(pointer: ExactS3Pointer, positions: number[]): Promise<void>;
+/**
+ * Load exact token positions for a pointer.
+ * @param pointer Bucket/key pair for the postings object.
+ * @returns Positions array (empty when not found).
+ */
+export declare function loadExactPositions(pointer: ExactS3Pointer): Promise<number[]>;

package/api/Indexing/fieldQualification.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared helpers for qualifying index fields by type name.
+ */
+/**
+ * Build a fully-qualified index field name.
+ * @param typeName Type name used to scope the field.
+ * @param fieldName Field name to qualify.
+ * @returns Qualified index field name.
+ */
+export declare function qualifyIndexField(typeName: string, fieldName: string): string;

package/api/Indexing/fulltext/FullTextDdbBackend.d.ts

@@ -0,0 +1,210 @@
+import type { DocId, DocTokenKey, DocumentRecord, TokenStats } from "../Types";
+import type { SearchTrace } from "../Trace";
+import type { DynamoBatchWriter, DynamoQueryClient, WriteRequest } from "../ddb/Types";
+export type { BatchGetItemInput, BatchGetItemOutput, BatchWriteItemInput, BatchWriteItemOutput, DynamoBatchWriter, DynamoQueryClient, GetItemInput, GetItemOutput, KeysAndAttributes, QueryInput, QueryOutput, WriteRequest, } from "../ddb/Types";
+/**
+ * Deployment-specific DynamoDB table names required for fulltext storage.
+ */
+export type FullTextTableNames = {
+    lossyPostings: string;
+    exactPostings: string;
+    docMirror: string;
+    tokenStats: string;
+    docTokens: string;
+    docTokenPositions: string;
+};
+/**
+ * Configuration for the DynamoDB fulltext writer.
+ *
+ * Table names are required and should be injected per deployment.
+ */
+export type FullTextDdbWriterConfig = {
+    /**
+     * DynamoDB client used for batch writes and gets.
+     */
+    client: DynamoBatchWriter;
+    /**
+     * Table names for fulltext indexing storage.
+     */
+    tables: FullTextTableNames;
+};
+type TableWrite = {
+    tableName: string;
+    request: WriteRequest;
+};
+/**
+ * Write-only DynamoDB helper for indexing documents and token stats.
+ */
+export declare class FullTextDdbWriter {
+    protected client: DynamoBatchWriter;
+    protected lossyTableName: string;
+    protected exactTableName: string;
+    protected mirrorTableName: string;
+    protected docTokensTableName: string;
+    protected docTokenPositionsTableName: string;
+    protected tokenStatsTableName: string;
+    /**
+     * @param config Writer configuration including client and table names.
+     */
+    constructor(config: FullTextDdbWriterConfig);
+    /**
+     * Build a token stats write request for a document frequency delta.
+     * @param token Token value to update stats for.
+     * @param indexField Field name the token was indexed under.
+     * @param delta Delta to apply to document frequency.
+     * @returns Write request or undefined when no update is needed.
+     */
+    protected buildTokenStatsWrite(token: string, indexField: string, delta: number): Promise<TableWrite | undefined>;
+    private loadMirrorContent;
+    /**
+     * Write a document to lossy/exact postings and token stats tables.
+     * @param document Document record to index.
+     * @param primaryField Field name used as the document id.
+     * @param indexField Field name containing the text to index.
+     * @returns Promise resolved once all writes complete.
+     */
+    writeDocument(document: DocumentRecord, primaryField: string, indexField: string): Promise<void>;
+}
+/**
+ * Configuration for the DynamoDB fulltext backend.
+ */
+/**
+ * Configuration for the combined fulltext backend.
+ *
+ * Table names are required and should be injected per deployment.
+ */
+export type FullTextDdbBackendConfig = FullTextDdbWriterConfig & {
+    /**
+     * DynamoDB client with query support.
+     */
+    client: DynamoQueryClient;
+};
+/**
+ * Page of lossy postings results.
+ */
+export type LossyPostingsPage = {
+    /**
+     * Document ids in the page.
+     */
+    docIds: DocId[];
+    /**
+     * Doc id used to resume paging, if more results exist.
+     */
+    lastEvaluatedDocId?: DocId;
+};
+/**
+ * Paging options for lossy postings queries.
+ */
+export type LossyPostingsPageOptions = {
+    /**
+     * Exclusive starting doc id for paging.
+     */
+    exclusiveStartDocId?: DocId;
+    /**
+     * Maximum number of doc ids to return.
+     */
+    limit?: number;
+};
+/**
+ * Read/write DynamoDB backend that adds query helpers to {@link FullTextDdbWriter}.
+ */
+export declare class FullTextDdbBackend extends FullTextDdbWriter {
+    private readonly queryClient;
+    private activeTrace;
+    /**
+     * @param config Backend configuration including query client and table names.
+     */
+    constructor(config: FullTextDdbBackendConfig);
+    /**
+     * Attach or clear an active search trace for metrics.
+     * @param trace Trace instance to record metrics into.
+     * @returns Nothing.
+     */
+    setActiveTrace(trace: SearchTrace | undefined): void;
+    private recordQuery;
+    private recordBatchGet;
+    private recordItemRead;
+    /**
+     * Add a lossy posting for a token.
+     * @param token Token value to add.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Promise resolved once posting is added.
+     */
+    addLossyPosting(token: string, indexField: string, docId: DocId): Promise<void>;
+    /**
+     * Remove a lossy posting for a token.
+     * @param token Token value to remove.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Promise resolved once posting is removed.
+     */
+    removeLossyPosting(token: string, indexField: string, docId: DocId): Promise<void>;
+    /**
+     * Load all lossy postings for a token.
+     * @param token Token value to load postings for.
+     * @param indexField Field name the token was indexed under.
+     * @returns Document ids containing the token.
+     */
+    loadLossyPostings(token: string, indexField: string): Promise<DocId[]>;
+    /**
+     * Query a page of lossy postings for a token.
+     * @param token Token value to query postings for.
+     * @param indexField Field name the token was indexed under.
+     * @param options Paging options for the query.
+     * @returns Postings page with optional cursor.
+     */
+    queryLossyPostingsPage(token: string, indexField: string, options?: LossyPostingsPageOptions): Promise<LossyPostingsPage>;
+    /**
+     * Add exact token positions for a document.
+     * @param token Token value to store positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @param positions Token positions within the document.
+     * @returns Promise resolved once positions are stored.
+     */
+    addExactPositions(token: string, indexField: string, docId: DocId, positions: number[]): Promise<void>;
+    /**
+     * Remove exact token positions for a document.
+     * @param token Token value to remove positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Promise resolved once positions are removed.
+     */
+    removeExactPositions(token: string, indexField: string, docId: DocId): Promise<void>;
+    /**
+     * Load exact positions for a token in a document.
+     * @param token Token value to load positions for.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id containing the token.
+     * @returns Positions array or undefined when missing.
+     */
+    loadExactPositions(token: string, indexField: string, docId: DocId): Promise<number[] | undefined>;
+    /**
+     * Batch load exact positions for token keys.
+     * @param keys Token keys to load positions for.
+     * @returns Positions arrays aligned with the input keys.
+     */
+    batchLoadExactPositions(keys: DocTokenKey[]): Promise<(number[] | undefined)[]>;
+    /**
+     * Check whether a document contains a token.
+     * @param docId Document id to check.
+     * @param indexField Field name the token was indexed under.
+     * @param token Token value to check.
+     * @returns True when the document contains the token.
+     */
+    hasDocToken(docId: DocId, indexField: string, token: string): Promise<boolean>;
+    /**
+     * Batch check whether documents contain tokens.
+     * @param keys Token keys to check.
+     * @returns Booleans aligned with the input keys.
+     */
+    batchHasDocTokens(keys: DocTokenKey[]): Promise<boolean[]>;
+    /**
+     * Load token stats for a token.
+     * @param token Token value to load stats for.
+     * @param indexField Field name the token was indexed under.
+     * @returns Token stats or undefined when missing.
+     */
+    loadTokenStats(token: string, indexField: string): Promise<TokenStats | undefined>;
+}