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

package/api/Indexing/Cursor.d.ts

@@ -0,0 +1,101 @@
+import type { DocId } from "./Types";
+/**
+ * The supported ordering strategy for cursors.
+ * */
+export type SortingStrategy = "docIdAsc";
+/**
+ * Cursor planner metadata used to resume searches efficiently.
+ * */
+export type PlannerMetadata = {
+    /**
+     * Token selected as the primary postings list for paging.
+     */
+    primaryToken: string;
+    /**
+     * Optional token stats version used to validate planner choice.
+     */
+    statsVersion?: number;
+    /**
+     * Sorting strategy applied to doc id traversal.
+     */
+    sorting?: SortingStrategy;
+};
+/**
+ * Cursor state for lossy search pagination.
+ * */
+export type LossyCursorState = {
+    /**
+     * Last document id returned in the previous page.
+     */
+    lastDocId?: DocId;
+    /**
+     * Planner metadata used to resume efficient paging.
+     */
+    plan?: PlannerMetadata;
+};
+/**
+ * Cursor state for exact search pagination, including lossy and verification phases.
+ * */
+export type ExactCursorState = {
+    /**
+     * Lossy phase cursor state for candidate retrieval.
+     */
+    lossy?: LossyCursorState;
+    /**
+     * Verification phase cursor state for exact phrase checks.
+     */
+    verification?: {
+        /**
+         * Last verified document id in the verification phase.
+         */
+        lastDocId?: DocId;
+        /**
+         * Pending candidates to continue verifying.
+         */
+        pendingCandidates?: DocId[];
+        /**
+         * Offset into the pending candidates list.
+         */
+        pendingOffset?: number;
+    };
+    /**
+     * Planner metadata used to resume efficient paging.
+     */
+    plan?: PlannerMetadata;
+};
+/**
+ * Encode a lossy cursor state into a URL-safe string.
+ * @returns URL-safe cursor string, or undefined when there is no state to encode.
+ * */
+export declare function encodeLossyCursor(
+/**
+ * Lossy cursor state to encode.
+ */
+state?: LossyCursorState): string | undefined;
+/**
+ * Decode a lossy cursor string back into state.
+ * @returns Parsed lossy cursor state, or undefined when cursor is missing.
+ * */
+export declare function decodeLossyCursor(
+/**
+ * Cursor string to decode.
+ */
+cursor?: string): LossyCursorState | undefined;
+/**
+ * Encode an exact cursor state into a URL-safe string.
+ * @returns URL-safe cursor string, or undefined when there is no state to encode.
+ * */
+export declare function encodeExactCursor(
+/**
+ * Exact cursor state to encode.
+ */
+state?: ExactCursorState): string | undefined;
+/**
+ * Decode an exact cursor string back into state.
+ * @returns Parsed exact cursor state, or undefined when cursor is missing.
+ * */
+export declare function decodeExactCursor(
+/**
+ * Cursor string to decode.
+ */
+cursor?: string): ExactCursorState | undefined;

package/api/Indexing/Handler/Config.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Optional limits for search execution.
+ */
+export type SearchLimits = {
+    /**
+     * Maximum number of tokens processed for a query.
+     */
+    maxTokens?: number;
+    /**
+     * Maximum number of postings pages fetched.
+     */
+    maxPostingsPages?: number;
+    /**
+     * Maximum number of candidates verified for exact matches.
+     */
+    maxCandidatesVerified?: number;
+    /**
+     * Soft time budget in milliseconds before stopping.
+     */
+    softTimeBudgetMs?: number;
+};
+/**
+ * Fully resolved search limits with defaults applied.
+ */
+export type ResolvedSearchLimits = Required<SearchLimits>;
+/**
+ * Default search limits applied when none are provided.
+ */
+export declare const SEARCH_DEFAULTS: ResolvedSearchLimits;
+/**
+ * Maximum caps enforced for requested search limits.
+ */
+export declare const SEARCH_CAPS: ResolvedSearchLimits;
+/**
+ * Resolve and clamp search limits against defaults and caps.
+ * @param limits Optional requested limits to apply.
+ * @returns Resolved and clamped limits.
+ */
+export declare function resolveSearchLimits(limits?: SearchLimits): ResolvedSearchLimits;

package/api/Indexing/Handler.d.ts

@@ -0,0 +1,166 @@
+import { type SearchLimits } from "./Handler/Config";
+import type { DocumentRecord, IndexBackend } from "./Types";
+/**
+ * Event payload to index a document.
+ * */
+export type IndexDocumentEvent = {
+    /**
+     * Action discriminator for indexing.
+     */
+    action: "indexDocument";
+    /**
+     * Document record to index.
+     */
+    document: DocumentRecord;
+    /**
+     * Optional primary field name (defaults to "id").
+     */
+    primaryField?: string;
+    /**
+     * Optional index field name (defaults to "text").
+     */
+    indexField?: string;
+    /**
+     * Optional qualified index field key used for persistence.
+     */
+    indexFieldQualified?: string;
+};
+/**
+ * Event payload to remove a document from the index.
+ * */
+export type RemoveDocumentEvent = {
+    /**
+     * Action discriminator for removals.
+     */
+    action: "removeDocument";
+    /**
+     * Document record to remove.
+     */
+    document: DocumentRecord;
+    /**
+     * Optional primary field name (defaults to "id").
+     */
+    primaryField?: string;
+    /**
+     * Optional index field name (defaults to "text").
+     */
+    indexField?: string;
+    /**
+     * Optional qualified index field key used for persistence.
+     */
+    indexFieldQualified?: string;
+};
+/**
+ * Event payload to run a lossy search.
+ * */
+export type SearchLossyEvent = {
+    /**
+     * Action discriminator for lossy search.
+     */
+    action: "searchLossy";
+    /**
+     * Query string to search for.
+     */
+    query: string;
+    /**
+     * Optional index field name (defaults to "text").
+     */
+    indexField?: string;
+    /**
+     * Optional maximum number of results to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+    /**
+     * Optional limits override for search execution.
+     */
+    limits?: SearchLimits;
+};
+/**
+ * Event payload to run an exact search.
+ * */
+export type SearchExactEvent = {
+    /**
+     * Action discriminator for exact search.
+     */
+    action: "searchExact";
+    /**
+     * Query string to search for.
+     */
+    query: string;
+    /**
+     * Optional index field name (defaults to "text").
+     */
+    indexField?: string;
+    /**
+     * Optional maximum number of results to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+    /**
+     * Optional limits override for search execution.
+     */
+    limits?: SearchLimits;
+};
+/**
+ * Union of supported handler events.
+ * */
+export type HandlerEvent = IndexDocumentEvent | RemoveDocumentEvent | SearchLossyEvent | SearchExactEvent;
+/**
+ * Dependencies required by the handler.
+ * */
+export type HandlerDependencies = {
+    /**
+     * Index backend used for all operations.
+     */
+    backend: IndexBackend;
+};
+/**
+ * Basic lambda response shape.
+ * */
+export type LambdaResponse = {
+    /**
+     * HTTP status code for the response.
+     */
+    statusCode: number;
+    /**
+     * Serialized response body.
+     */
+    body: string;
+};
+/**
+ * Configure the handler with concrete implementations.
+ *
+ * Example index event:
+ * { "action": "indexDocument", "document": { "id": 42, "text": "Hello world" }, "primaryField": "id", "indexField": "text" }
+ *
+ * Example remove event:
+ * { "action": "removeDocument", "document": { "id": 42, "text": "Hello world" } }
+ *
+ * Example lossy search event:
+ * { "action": "searchLossy", "query": "hello world", "indexField": "text", "limit": 10 }
+ *
+ * Example exact search event:
+ * { "action": "searchExact", "query": "\"hello world\"", "indexField": "text", "limit": 10 }
+ * @returns Nothing.
+ */
+export declare function setHandlerDependencies(
+/**
+ * Concrete dependencies used by the handler.
+ */
+value: HandlerDependencies): void;
+/**
+ * Handle index and search actions for a backend.
+ * @returns Lambda response with status and body payload.
+ * */
+export declare function handler(
+/**
+ * Handler event describing the action to execute.
+ */
+event: HandlerEvent): Promise<LambdaResponse>;

package/api/Indexing/Trace.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime counters and metadata collected during a search.
+ * */
+export type SearchTrace = {
+    /**
+     * Epoch timestamp when the search started.
+     */
+    startTimeMs: number;
+    /**
+     * Total number of tokens processed for the query.
+     */
+    tokenCount?: number;
+    /**
+     * Hash of the normalized query text for correlation.
+     */
+    queryHash?: string;
+    /**
+     * Hash of the primary token chosen for paging.
+     */
+    primaryTokenHash?: string;
+    /**
+     * Number of postings pages read.
+     */
+    postingsPages: number;
+    /**
+     * Number of candidates verified for exact matching.
+     */
+    candidatesVerified: number;
+    /**
+     * Number of batch get calls for token checks.
+     */
+    batchGetCalls: number;
+    /**
+     * Total number of keys checked via batch get calls.
+     */
+    batchGetKeys: number;
+    /**
+     * DynamoDB query calls issued (if applicable).
+     */
+    ddbQueryCalls: number;
+    /**
+     * DynamoDB batch get calls issued (if applicable).
+     */
+    ddbBatchGetCalls: number;
+    /**
+     * DynamoDB item read calls issued (if applicable).
+     */
+    ddbItemReadCalls: number;
+};
+/**
+ * Initialize a search trace with counters set to zero.
+ * @returns New search trace instance.
+ * */
+export declare function createSearchTrace(): SearchTrace;

package/api/Indexing/Types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Document identifier type used in indexes and cursors.
+ */
+export type DocId = string | number;
+/**
+ * Generic document record stored in the index.
+ */
+export type DocumentRecord = Record<string, unknown>;
+/**
+ * Reader interface for lossy postings lists.
+ */
+export type LossyReader = {
+    /**
+     * Load lossy postings for a token.
+     * @param token Token to load postings for.
+     * @param indexField Field name the token was indexed under.
+     * @returns Array of document ids containing the token.
+     */
+    loadLossyPostings(token: string, indexField: string): Promise<DocId[]>;
+};
+/**
+ * Page of lossy postings for paging-capable backends.
+ */
+export type LossyPostingsPage = {
+    /**
+     * Document ids in the page.
+     */
+    docIds: DocId[];
+    /**
+     * Doc id used to resume paging, if more results exist.
+     */
+    lastEvaluatedDocId?: DocId;
+};
+/**
+ * Options for paging through lossy postings.
+ */
+export type LossyPostingsPageOptions = {
+    /**
+     * Exclusive starting doc id for paging.
+     */
+    exclusiveStartDocId?: DocId;
+    /**
+     * Maximum number of doc ids to return.
+     */
+    limit?: number;
+};
+/**
+ * Reader interface that supports paging through lossy postings.
+ */
+export type LossyPagingReader = {
+    /**
+     * Query a page of lossy postings for a token.
+     * @param token Token to query postings for.
+     * @param indexField Field name the token was indexed under.
+     * @param options Paging options for the query.
+     * @returns Postings page for the token.
+     */
+    queryLossyPostingsPage(token: string, indexField: string, options?: LossyPostingsPageOptions): Promise<LossyPostingsPage>;
+};
+/**
+ * Key used to address a token within a document and field.
+ */
+export type DocTokenKey = {
+    /**
+     * Document id containing the token.
+     */
+    docId: DocId;
+    /**
+     * Field name the token was indexed under.
+     */
+    indexField: string;
+    /**
+     * Token value.
+     */
+    token: string;
+};
+/**
+ * Reader interface for checking token existence in documents.
+ */
+export type DocTokenReader = {
+    /**
+     * Check if a document has a specific 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 token exists for the document.
+     */
+    hasDocToken(docId: DocId, indexField: string, token: string): Promise<boolean>;
+};
+/**
+ * Batch reader interface for checking token existence.
+ */
+export type DocTokenBatchReader = {
+    /**
+     * Batch check document token existence.
+     * @param keys Token keys to check.
+     * @returns Array of booleans aligned with the input keys.
+     */
+    batchHasDocTokens(keys: DocTokenKey[]): Promise<boolean[]>;
+};
+/**
+ * Reader interface for exact token positions.
+ */
+export type ExactReader = {
+    /**
+     * Load exact positions for a token in a document.
+     * @param token Token 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 if not present.
+     */
+    loadExactPositions(token: string, indexField: string, docId: DocId): Promise<number[] | undefined>;
+};
+/**
+ * Batch reader interface for exact token positions.
+ */
+export type ExactBatchReader = {
+    /**
+     * 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)[]>;
+};
+/**
+ * Token statistics stored with the index.
+ */
+export type TokenStats = {
+    /**
+     * Document frequency for the token.
+     */
+    df?: number;
+    /**
+     * Optional stats version for planner compatibility.
+     */
+    version?: number;
+};
+/**
+ * Reader interface for token statistics.
+ */
+export type TokenStatsReader = {
+    /**
+     * Load token statistics for a token.
+     * @param token Token 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>;
+};
+/**
+ * Combined reader interface for lossy, exact, and stats operations.
+ */
+export type IndexReader = LossyReader & ExactReader & TokenStatsReader & Partial<ExactBatchReader>;
+/**
+ * Writer interface for lossy postings.
+ */
+export type LossyWriter = {
+    /**
+     * Add a lossy posting for a token.
+     * @param token Token to add.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id to associate.
+     * @returns Promise resolved when the posting is written.
+     */
+    addLossyPosting(token: string, indexField: string, docId: DocId): Promise<void>;
+    /**
+     * Remove a lossy posting for a token.
+     * @param token Token to remove.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id to disassociate.
+     * @returns Promise resolved when the posting is removed.
+     */
+    removeLossyPosting(token: string, indexField: string, docId: DocId): Promise<void>;
+};
+/**
+ * Writer interface for exact token positions.
+ */
+export type ExactWriter = {
+    /**
+     * Add exact token positions for a document.
+     * @param token Token to add.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id to associate.
+     * @param positions Token positions within the document.
+     * @returns Promise resolved when positions are written.
+     */
+    addExactPositions(token: string, indexField: string, docId: DocId, positions: number[]): Promise<void>;
+    /**
+     * Remove exact token positions for a document.
+     * @param token Token to remove.
+     * @param indexField Field name the token was indexed under.
+     * @param docId Document id to disassociate.
+     * @returns Promise resolved when positions are removed.
+     */
+    removeExactPositions(token: string, indexField: string, docId: DocId): Promise<void>;
+};
+/**
+ * Combined writer interface for lossy and exact indexing.
+ */
+export type IndexWriter = LossyWriter & ExactWriter;
+/**
+ * Full index backend interface for reading and writing.
+ */
+export type IndexBackend = IndexReader & IndexWriter;

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

@@ -0,0 +1,8 @@
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { DynamoBatchWriter, DynamoQueryClient, WriteRequest } from "./Types";
+export type BatchWriteWithRetryOptions = {
+    maxRetries?: number;
+    onRetry?: (attempt: number, pending: Record<string, WriteRequest[]>) => void;
+};
+export declare const createAwsSdkV3DynamoClient: (client: DynamoDBClient) => DynamoQueryClient;
+export declare const batchWriteWithRetry: (client: DynamoBatchWriter, requestItems: Record<string, WriteRequest[]>, options?: BatchWriteWithRetryOptions) => Promise<void>;