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

package/api/Indexing/rel/RelationalDdb.d.ts

@@ -0,0 +1,169 @@
+import type { DynamoQueryClient } from "../ddb/Types";
+import type { Direction, Edge, EdgeKey, EdgePage, RelationalQueryOptions } from "./Types";
+type EdgeMetadata = Record<string, unknown>;
+/**
+ * DynamoDB key shape for relation edges.
+ */
+export type RelationEdgesDdbKey = {
+    /**
+     * Partition key encoding entity/relation/direction.
+     */
+    edgeKey: string;
+    /**
+     * Sort key identifying the opposite entity id.
+     */
+    otherId: string;
+};
+/**
+ * DynamoDB item shape for relation edges.
+ */
+export type RelationEdgesDdbItem<TMetadata extends EdgeMetadata = EdgeMetadata> = RelationEdgesDdbKey & {
+    /**
+     * Optional metadata stored with the edge.
+     */
+    metadata?: TMetadata;
+};
+/**
+ * Schema metadata for relational edges stored in DynamoDB.
+ */
+export declare const relationEdgesSchema: {
+    readonly partitionKey: "edgeKey";
+    readonly sortKey: "otherId";
+    readonly metadataAttribute: "metadata";
+};
+/**
+ * Deployment-specific DynamoDB table names required for relational edges.
+ */
+export type RelationsTableNames = {
+    relationEdges: string;
+};
+/**
+ * Configuration for relational DynamoDB backends.
+ *
+ * Table names are required and should be injected per deployment.
+ */
+export type RelationsDdbConfig = {
+    client: DynamoQueryClient;
+    tables: RelationsTableNames;
+    batchSize?: number;
+};
+export declare const createRelationEdgesDdbDependencies: <TMetadata extends EdgeMetadata = EdgeMetadata>(config: RelationsDdbConfig) => RelationEdgesDdbDependencies<TMetadata>;
+/**
+ * Encode the partition key for relation edges.
+ * @param entityId Source/target entity id.
+ * @param relation Relation name.
+ * @param direction Traversal direction.
+ * @returns Encoded partition key for the relation edge.
+ */
+export declare function encodeRelationEdgePartitionKey(entityId: string, relation: string, direction: Direction): string;
+/**
+ * Build a DynamoDB key for a relation edge.
+ * @param entityId Source/target entity id.
+ * @param relation Relation name.
+ * @param direction Traversal direction.
+ * @param otherId Opposite entity id for the edge.
+ * @returns Relation edge key for DynamoDB.
+ */
+export declare function buildRelationEdgeDdbKey(entityId: string, relation: string, direction: Direction, otherId: string): RelationEdgesDdbKey;
+/**
+ * Build a DynamoDB item for a relation edge.
+ * @param entityId Source/target entity id.
+ * @param relation Relation name.
+ * @param direction Traversal direction.
+ * @param otherId Opposite entity id for the edge.
+ * @param metadata Optional metadata for the edge.
+ * @returns Relation edge item for DynamoDB.
+ */
+export declare function buildRelationEdgeDdbItem<TMetadata extends EdgeMetadata>(entityId: string, relation: string, direction: Direction, otherId: string, metadata?: TMetadata): RelationEdgesDdbItem<TMetadata>;
+/**
+ * Query request for relation edges.
+ */
+export type RelationEdgesQueryRequest = {
+    /**
+     * Partition key for the relation edge query.
+     */
+    edgeKey: string;
+    /**
+     * Optional maximum number of items to return.
+     */
+    limit?: number;
+    /**
+     * Optional exclusive start key for pagination.
+     */
+    exclusiveStartKey?: RelationEdgesDdbKey;
+};
+/**
+ * Query results for relation edges.
+ */
+export type RelationEdgesQueryResult<TMetadata extends EdgeMetadata = EdgeMetadata> = {
+    /**
+     * Returned items for the query.
+     */
+    items: RelationEdgesDdbItem<TMetadata>[];
+    /**
+     * Last evaluated key for pagination.
+     */
+    lastEvaluatedKey?: RelationEdgesDdbKey;
+};
+/**
+ * DynamoDB dependencies required for relation edge storage.
+ */
+export type RelationEdgesDdbDependencies<TMetadata extends EdgeMetadata = EdgeMetadata> = {
+    /**
+     * Batch put relation edge items.
+     * @param items Edge items to store.
+     * @returns Promise resolved once stored.
+     */
+    putEdges(items: RelationEdgesDdbItem<TMetadata>[]): Promise<void>;
+    /**
+     * Batch delete relation edge keys.
+     * @param keys Edge keys to delete.
+     * @returns Promise resolved once deleted.
+     */
+    deleteEdges(keys: RelationEdgesDdbKey[]): Promise<void>;
+    /**
+     * Query relation edges by key.
+     * @param request Query request parameters.
+     * @returns Query results and pagination key.
+     */
+    queryEdges(request: RelationEdgesQueryRequest): Promise<RelationEdgesQueryResult<TMetadata>>;
+};
+/**
+ * DynamoDB-backed relational edge store with directional queries.
+ */
+export declare class RelationalDdbBackend<TMetadata extends EdgeMetadata = EdgeMetadata> {
+    private readonly dependencies;
+    /**
+     * @param dependencies DynamoDB query/write dependencies.
+     */
+    constructor(dependencies: RelationEdgesDdbDependencies<TMetadata>);
+    /**
+     * Insert or update an edge.
+     * @param edge Edge to store.
+     * @returns Promise resolved once stored.
+     */
+    putEdge(edge: Edge<TMetadata>): Promise<void>;
+    /**
+     * Remove an edge by key.
+     * @param key Edge key to remove.
+     * @returns Promise resolved once removed.
+     */
+    removeEdge(key: EdgeKey): Promise<void>;
+    /**
+     * Query outgoing edges for an entity and relation.
+     * @param fromId Source entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of outgoing edges.
+     */
+    getOutgoing(fromId: string, relation: string, options?: RelationalQueryOptions): Promise<EdgePage<TMetadata>>;
+    /**
+     * Query incoming edges for an entity and relation.
+     * @param toId Target entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of incoming edges.
+     */
+    getIncoming(toId: string, relation: string, options?: RelationalQueryOptions): Promise<EdgePage<TMetadata>>;
+}
+export {};

package/api/Indexing/rel/RelationalInMemoryBackend.d.ts

@@ -0,0 +1,38 @@
+import type { Edge, EdgeKey, EdgePage, RelationalQueryOptions } from "./Types";
+type EdgeMetadata = Record<string, unknown>;
+/**
+ * In-memory relational backend for tests and local runs.
+ */
+export declare class RelationalInMemoryBackend<TMetadata extends EdgeMetadata = EdgeMetadata> {
+    private forward;
+    private reverse;
+    /**
+     * Insert or update an edge.
+     * @param edge Edge to store.
+     * @returns Nothing.
+     */
+    putEdge(edge: Edge<TMetadata>): void;
+    /**
+     * Remove an edge by key.
+     * @param key Edge key to remove.
+     * @returns Nothing.
+     */
+    removeEdge(key: EdgeKey): void;
+    /**
+     * Query outgoing edges for an entity and relation.
+     * @param fromId Source entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of outgoing edges.
+     */
+    getOutgoing(fromId: string, relation: string, options?: RelationalQueryOptions): EdgePage<TMetadata>;
+    /**
+     * Query incoming edges for an entity and relation.
+     * @param toId Target entity id.
+     * @param relation Relation name.
+     * @param options Optional paging options.
+     * @returns Page of incoming edges.
+     */
+    getIncoming(toId: string, relation: string, options?: RelationalQueryOptions): EdgePage<TMetadata>;
+}
+export {};

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

@@ -0,0 +1,69 @@
+/**
+ * @packageDocumentation
+ *
+ * Shared types for relational indexing and handler interfaces.
+ */
+/**
+ * Edge traversal direction.
+ */
+export type Direction = "out" | "in";
+/**
+ * Key identifying a relation between two entities.
+ */
+export type EdgeKey = {
+    /**
+     * Source entity id.
+     */
+    from: string;
+    /**
+     * Target entity id.
+     */
+    to: string;
+    /**
+     * Relation name.
+     */
+    relation: string;
+    /**
+     * Optional direction override for the edge.
+     */
+    direction?: Direction;
+};
+/**
+ * Edge connecting two entities with optional metadata.
+ */
+export type Edge<TMetadata = Record<string, unknown>> = {
+    /**
+     * Edge key describing the relation.
+     */
+    key: EdgeKey;
+    /**
+     * Optional metadata stored with the edge.
+     */
+    metadata?: TMetadata;
+};
+/**
+ * Page of edges returned from a query.
+ */
+export type EdgePage<TMetadata = Record<string, unknown>> = {
+    /**
+     * Returned edges for the page.
+     */
+    edges: Array<Edge<TMetadata>>;
+    /**
+     * Cursor string for the next page, if more results exist.
+     */
+    nextCursor?: string;
+};
+/**
+ * Paging options for relational queries.
+ */
+export type RelationalQueryOptions = {
+    /**
+     * Optional maximum number of edges to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+};

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

@@ -0,0 +1,26 @@
+import type { DocId } from "../Types";
+/**
+ * Cursor state for structured indexing paging.
+ */
+export type StructuredCursorState = {
+    /**
+     * Last document id processed in the previous page.
+     */
+    lastDocId?: DocId;
+    /**
+     * Backend continuation token for paging.
+     */
+    backendToken?: string;
+};
+/**
+ * Encode structured cursor state into a URL-safe string.
+ * @param state Cursor state to encode.
+ * @returns URL-safe cursor string, or undefined when there is no state to encode.
+ */
+export declare function encodeStructuredCursor(state?: StructuredCursorState): string | undefined;
+/**
+ * Decode a structured cursor string back into state.
+ * @param cursor Cursor string to decode.
+ * @returns Parsed cursor state, or undefined when cursor is missing.
+ */
+export declare function decodeStructuredCursor(cursor?: string): StructuredCursorState | undefined;

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

@@ -0,0 +1,128 @@
+import type { DocId } from "../Types";
+import type { StructuredSearchDependencies } from "./SearchStructured";
+import type { StructuredDocFieldsRecord } from "./StructuredDdb";
+import type { Where } from "./Types";
+/**
+ * Document payload for structured indexing.
+ */
+export type StructuredDocumentRecord = {
+    /**
+     * Document id for the structured record.
+     */
+    id: DocId | number;
+    /**
+     * Structured fields to index. Field keys should be type-qualified when
+     * multiple types share fields.
+     */
+    fields: StructuredDocFieldsRecord;
+};
+/**
+ * Event payload for structured document indexing.
+ */
+export type StructuredIndexDocumentEvent = {
+    /**
+     * Action discriminator for indexing.
+     */
+    action: "indexDocument";
+    /**
+     * Document payload to index.
+     */
+    document: StructuredDocumentRecord;
+};
+/**
+ * Event payload for structured searches.
+ */
+export type StructuredSearchEvent = {
+    /**
+     * Action discriminator for structured search.
+     */
+    action: "SearchStructured";
+    /**
+     * Structured query clause. Field values should be type-qualified when
+     * multiple types share fields.
+     */
+    where: Where;
+    /**
+     * Optional maximum number of results to return.
+     */
+    limit?: number;
+    /**
+     * Optional cursor string for pagination.
+     */
+    cursor?: string;
+};
+/**
+ * Union of structured handler events.
+ */
+export type StructuredHandlerEvent = StructuredIndexDocumentEvent | StructuredSearchEvent;
+/**
+ * Writer interface for structured indexing.
+ */
+export type StructuredWriter = {
+    /**
+     * Write structured fields for a document.
+     * @param docId Document id to write.
+     * @param fields Structured fields to store.
+     * @returns Promise resolved once stored.
+     */
+    write(docId: DocId, fields: StructuredDocFieldsRecord): Promise<void>;
+};
+/**
+ * Reader interface for structured searching.
+ */
+export type StructuredReader = StructuredSearchDependencies;
+/**
+ * Reader/writer dependencies for the structured handler.
+ */
+export type StructuredHandlerDependencies = {
+    /**
+     * Reader dependencies used for search.
+     */
+    reader: StructuredReader;
+    /**
+     * Writer dependency used for indexing.
+     */
+    writer: StructuredWriter;
+};
+/**
+ * Lambda-style response payload.
+ */
+export type LambdaResponse = {
+    /**
+     * HTTP status code for the response.
+     */
+    statusCode: number;
+    /**
+     * Serialized response body.
+     */
+    body: string;
+};
+/**
+ * Configure the structured handler with concrete implementations.
+ *
+ * Example index event:
+ * {
+ *   "action": "indexDocument",
+ *   "document": { "id": "doc-42", "fields": { "category": "news", "tags": ["a", "b"] } }
+ * }
+ *
+ * Example search event:
+ * {
+ *   "action": "SearchStructured",
+ *   "where": { "and": [{ "type": "term", "field": "category", "mode": "eq", "value": "news" }] },
+ *   "limit": 10,
+ *   "cursor": "eyJ2IjoxLCJsYXN0RG9jSWQiOiJkb2MtNDIifQ"
+ * }
+ * @returns Nothing.
+ */
+export declare function setStructuredHandlerDependencies(
+/**
+ * Reader/writer dependencies used by the handler.
+ */
+value: StructuredHandlerDependencies): void;
+/**
+ * Handle structured indexing and search events.
+ * @param event Handler event describing the operation to execute.
+ * @returns Lambda response with status and body payload.
+ */
+export declare function structuredHandler(event: StructuredHandlerEvent): Promise<LambdaResponse>;

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

@@ -0,0 +1,44 @@
+import type { DocId } from "../Types";
+import type { CandidatePage, StructuredQueryOptions, StructuredTermWhere, Where, WhereValue } from "./Types";
+type StructuredTermIndex = {
+    query(field: string, mode: StructuredTermWhere["mode"], value: WhereValue, options?: StructuredQueryOptions): Promise<{
+        candidateIds: DocId[];
+        lastEvaluatedKey?: string;
+    }>;
+};
+type StructuredRangeIndex = {
+    between(field: string, lower: WhereValue, upper: WhereValue, options?: StructuredQueryOptions): Promise<{
+        candidateIds: DocId[];
+        lastEvaluatedKey?: string;
+    }>;
+    gte(field: string, lower: WhereValue, options?: StructuredQueryOptions): Promise<{
+        candidateIds: DocId[];
+        lastEvaluatedKey?: string;
+    }>;
+    lte(field: string, upper: WhereValue, options?: StructuredQueryOptions): Promise<{
+        candidateIds: DocId[];
+        lastEvaluatedKey?: string;
+    }>;
+};
+/**
+ * Dependencies required to run structured searches.
+ */
+export type StructuredSearchDependencies = {
+    /**
+     * Term query dependency for equality/contains lookups.
+     */
+    terms: StructuredTermIndex;
+    /**
+     * Range query dependency for between/gte/lte lookups.
+     */
+    ranges: StructuredRangeIndex;
+};
+/**
+ * Execute a structured query using the provided term/range dependencies.
+ * @param dependencies Query dependencies for term and range lookups.
+ * @param where Structured query expression to evaluate.
+ * @param options Optional paging options.
+ * @returns Candidate page with optional cursor.
+ */
+export declare function searchStructured(dependencies: StructuredSearchDependencies, where: Where, options?: StructuredQueryOptions): Promise<CandidatePage>;
+export {};

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

@@ -0,0 +1,166 @@
+/**
+ * @packageDocumentation
+ *
+ * DynamoDB schema helpers for structured indexing (term, range, and doc fields).
+ */
+import type { DocId } from "../Types";
+import type { WhereValue } from "./Types";
+/**
+ * Document fields stored for structured indexing. Keys should be type-qualified
+ * when multiple types share fields.
+ */
+export type StructuredDocFieldsRecord = Record<string, WhereValue | WhereValue[]>;
+/**
+ * Term query mode for structured indexing.
+ */
+export type StructuredTermMode = "eq" | "contains";
+/**
+ * DynamoDB key shape for term index entries.
+ */
+export type StructuredTermIndexKey = {
+    /**
+     * Partition key for term index entries.
+     */
+    termKey: string;
+    /**
+     * Document id containing the term.
+     */
+    docId: DocId;
+};
+/**
+ * DynamoDB item shape for term index entries.
+ */
+export type StructuredTermIndexItem = StructuredTermIndexKey & {
+    /**
+     * Field name being indexed. Use a type-qualified field name when multiple
+     * types share fields.
+     */
+    field: string;
+    /**
+     * Stored field value.
+     */
+    value: WhereValue;
+    /**
+     * Term match mode for the entry.
+     */
+    mode: StructuredTermMode;
+};
+/**
+ * DynamoDB key shape for range index entries.
+ */
+export type StructuredRangeIndexKey = {
+    /**
+     * Field name being indexed. Use a type-qualified field name when multiple
+     * types share fields.
+     */
+    field: string;
+    /**
+     * Range key used for ordering.
+     */
+    rangeKey: string;
+};
+/**
+ * DynamoDB item shape for range index entries.
+ */
+export type StructuredRangeIndexItem = StructuredRangeIndexKey & {
+    /**
+     * Stored field value.
+     */
+    value: WhereValue;
+    /**
+     * Document id containing the value.
+     */
+    docId: DocId;
+};
+/**
+ * DynamoDB key shape for structured doc fields entries.
+ */
+export type StructuredDocFieldsKey = {
+    /**
+     * Document id for the record.
+     */
+    docId: DocId;
+};
+/**
+ * DynamoDB item shape for structured doc fields entries.
+ */
+export type StructuredDocFieldsItem = StructuredDocFieldsKey & {
+    /**
+     * Structured fields stored for the document.
+     */
+    fields: StructuredDocFieldsRecord;
+};
+/**
+ * Schema metadata for the structured term index table.
+ */
+export declare const structuredTermIndexSchema: {
+    readonly partitionKey: "termKey";
+    readonly sortKey: "docId";
+    readonly fieldAttribute: "field";
+    readonly valueAttribute: "value";
+    readonly modeAttribute: "mode";
+};
+/**
+ * Schema metadata for the structured range index table.
+ */
+export declare const structuredRangeIndexSchema: {
+    readonly partitionKey: "field";
+    readonly sortKey: "rangeKey";
+    readonly valueAttribute: "value";
+    readonly docIdAttribute: "docId";
+};
+/**
+ * Schema metadata for the structured document fields table.
+ */
+export declare const structuredDocFieldsSchema: {
+    readonly partitionKey: "docId";
+    readonly fieldsAttribute: "fields";
+};
+/**
+ * Serialize a structured value for DynamoDB key usage.
+ * @param value Structured value to serialize.
+ * @returns Serialized string representation.
+ */
+export declare function serializeStructuredValue(value: WhereValue): string;
+/**
+ * Build the term index partition key for a field/value/mode.
+ * @param field Field name being indexed. Use a type-qualified field name when
+ * multiple types share fields.
+ * @param value Field value.
+ * @param mode Term mode for the entry.
+ * @returns Term key for the structured term index.
+ */
+export declare function buildStructuredTermKey(field: string, value: WhereValue, mode: StructuredTermMode): string;
+/**
+ * Build the range key for a value/doc id pair.
+ * @param value Field value.
+ * @param docId Document id containing the value.
+ * @returns Range key for the structured range index.
+ */
+export declare function buildStructuredRangeKey(value: WhereValue, docId: DocId): string;
+/**
+ * Build a structured term index item.
+ * @param field Field name being indexed. Use a type-qualified field name when
+ * multiple types share fields.
+ * @param value Field value.
+ * @param mode Term mode for the entry.
+ * @param docId Document id containing the value.
+ * @returns Structured term index item.
+ */
+export declare function buildStructuredTermItem(field: string, value: WhereValue, mode: StructuredTermMode, docId: DocId): StructuredTermIndexItem;
+/**
+ * Build a structured range index item.
+ * @param field Field name being indexed. Use a type-qualified field name when
+ * multiple types share fields.
+ * @param value Field value.
+ * @param docId Document id containing the value.
+ * @returns Structured range index item.
+ */
+export declare function buildStructuredRangeItem(field: string, value: WhereValue, docId: DocId): StructuredRangeIndexItem;
+/**
+ * Build a structured document fields item.
+ * @param docId Document id for the record.
+ * @param fields Structured fields to store.
+ * @returns Structured doc fields item.
+ */
+export declare function buildStructuredDocFieldsItem(docId: DocId, fields: StructuredDocFieldsRecord): StructuredDocFieldsItem;