enigma-memory 0.1.17 → 0.1.22

package/packages/private-economy/src/x402.js

@@ -0,0 +1,346 @@
+export const X402_VERSION = 2;
+export const X402_HEADERS = Object.freeze({
+  paymentRequired: 'PAYMENT-REQUIRED',
+  paymentSignature: 'PAYMENT-SIGNATURE',
+  paymentResponse: 'PAYMENT-RESPONSE',
+});
+
+function requiredString(value, name, maximum = 16_384) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${name} exceeds ${maximum} characters`);
+  return normalized;
+}
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!plainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+function sameJson(left, right) {
+  return JSON.stringify(canonicalize(left)) === JSON.stringify(canonicalize(right));
+}
+
+function secureUrl(value, name) {
+  const url = new URL(requiredString(value, name, 4096));
+  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(url.hostname);
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) throw new TypeError(`${name} must use HTTPS outside localhost`);
+  if (url.username || url.password || url.hash) throw new TypeError(`${name} must not contain credentials or a fragment`);
+  return url;
+}
+
+function base64Json(value) {
+  return Buffer.from(JSON.stringify(value), 'utf8').toString('base64');
+}
+
+function parseBase64Json(value, name, maximumBytes = 256 * 1024) {
+  const encoded = requiredString(value, name, Math.ceil(maximumBytes * 4 / 3) + 16);
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(encoded) || encoded.length % 4 !== 0) throw new TypeError(`${name} is not canonical base64`);
+  const bytes = Buffer.from(encoded, 'base64');
+  if (bytes.length > maximumBytes || bytes.toString('base64') !== encoded) throw new TypeError(`${name} is invalid or too large`);
+  try {
+    const parsed = JSON.parse(bytes.toString('utf8'));
+    if (!plainObject(parsed)) throw new Error();
+    return parsed;
+  } catch {
+    throw new TypeError(`${name} does not contain a JSON object`);
+  }
+}
+
+function validateResource(resource, name = 'resource') {
+  if (!plainObject(resource)) throw new TypeError(`${name} must be an object`);
+  const url = secureUrl(resource.url, `${name}.url`).toString();
+  if (resource.description !== undefined) requiredString(resource.description, `${name}.description`, 1024);
+  if (resource.mimeType !== undefined) requiredString(resource.mimeType, `${name}.mimeType`, 256);
+  return { ...resource, url };
+}
+
+function validateRequirement(value, name = 'payment requirement') {
+  if (!plainObject(value)) throw new TypeError(`${name} must be an object`);
+  const requirement = {
+    scheme: requiredString(value.scheme, `${name}.scheme`, 64),
+    network: requiredString(value.network, `${name}.network`, 160),
+    amount: requiredString(value.amount, `${name}.amount`, 100),
+    asset: requiredString(value.asset, `${name}.asset`, 256),
+    payTo: requiredString(value.payTo, `${name}.payTo`, 256),
+    maxTimeoutSeconds: value.maxTimeoutSeconds,
+    ...(value.extra === undefined ? {} : { extra: value.extra }),
+  };
+  if (!/^\d+$/.test(requirement.amount)) throw new TypeError(`${name}.amount must be atomic units as a decimal string`);
+  if (!Number.isInteger(requirement.maxTimeoutSeconds) || requirement.maxTimeoutSeconds < 1 || requirement.maxTimeoutSeconds > 86_400) {
+    throw new TypeError(`${name}.maxTimeoutSeconds is invalid`);
+  }
+  if (requirement.extra !== undefined && !plainObject(requirement.extra)) throw new TypeError(`${name}.extra must be an object`);
+  return requirement;
+}
+
+export function parsePaymentRequiredHeader(value) {
+  const parsed = parseBase64Json(value, X402_HEADERS.paymentRequired);
+  if (parsed.x402Version !== X402_VERSION) throw new TypeError('unsupported x402 version');
+  const resource = validateResource(parsed.resource);
+  if (!Array.isArray(parsed.accepts) || !parsed.accepts.length || parsed.accepts.length > 32) throw new TypeError('x402 payment requirements must contain one through 32 accepts entries');
+  const accepts = parsed.accepts.map((entry, index) => validateRequirement(entry, `accepts[${index}]`));
+  if (parsed.extensions !== undefined && !plainObject(parsed.extensions)) throw new TypeError('x402 extensions must be an object');
+  return { x402Version: X402_VERSION, ...(parsed.error ? { error: String(parsed.error).slice(0, 1024) } : {}), resource, accepts, ...(parsed.extensions ? { extensions: parsed.extensions } : {}) };
+}
+
+export function parsePaymentPayloadHeader(value) {
+  const parsed = parseBase64Json(value, X402_HEADERS.paymentSignature);
+  if (parsed.x402Version !== X402_VERSION) throw new TypeError('unsupported x402 payment payload version');
+  if (!plainObject(parsed.payload)) throw new TypeError('x402 payment payload is missing scheme payload');
+  if (parsed.extensions !== undefined && !plainObject(parsed.extensions)) throw new TypeError('x402 payment payload extensions must be an object');
+  return {
+    x402Version: X402_VERSION,
+    ...(parsed.resource ? { resource: validateResource(parsed.resource, 'payment resource') } : {}),
+    accepted: validateRequirement(parsed.accepted, 'accepted'),
+    payload: parsed.payload,
+    ...(parsed.extensions ? { extensions: parsed.extensions } : {}),
+  };
+}
+
+export function parseSettlementResponseHeader(value) {
+  const parsed = parseBase64Json(value, X402_HEADERS.paymentResponse);
+  if (typeof parsed.success !== 'boolean') throw new TypeError('x402 settlement success must be boolean');
+  const transaction = typeof parsed.transaction === 'string' ? parsed.transaction : '';
+  const network = requiredString(parsed.network, 'x402 settlement network', 160);
+  if (parsed.success && !transaction) throw new TypeError('successful x402 settlement requires a transaction');
+  return {
+    success: parsed.success,
+    transaction,
+    network,
+    ...(parsed.errorReason ? { errorReason: String(parsed.errorReason).slice(0, 1024) } : {}),
+    ...(parsed.payer ? { payer: String(parsed.payer).slice(0, 256) } : {}),
+    ...(parsed.amount ? { amount: String(parsed.amount).slice(0, 100) } : {}),
+    ...(parsed.extensions && plainObject(parsed.extensions) ? { extensions: parsed.extensions } : {}),
+  };
+}
+
+function paymentFlow(requirement) {
+  return requirement.extra?.paymentFlow || 'authorization';
+}
+
+function validateExtensions(required, supplied) {
+  if (!required) return;
+  if (!supplied || !plainObject(supplied)) throw new TypeError('x402 payment payload omitted required extensions');
+  for (const [name, extension] of Object.entries(required)) {
+    if (!Object.hasOwn(supplied, name) || !plainObject(extension) || !plainObject(supplied[name])) throw new TypeError(`x402 extension ${name} is missing`);
+    if (!sameJson(extension.info, supplied[name].info)) throw new TypeError(`x402 extension ${name} changed server-provided info`);
+  }
+}
+
+function validatePayloadBinding(payload, required, requirement) {
+  if (!sameJson(payload.accepted, requirement)) throw new TypeError('x402 payment payload accepted terms do not exactly match the server offer');
+  if (payload.resource && payload.resource.url !== required.resource.url) throw new TypeError('x402 payment payload resource URL mismatch');
+  validateExtensions(required.extensions, payload.extensions);
+}
+
+export function createX402FacilitatorClient(options = {}) {
+  const baseUrl = secureUrl(options.baseUrl, 'x402 facilitator URL');
+  if (!baseUrl.pathname.endsWith('/')) baseUrl.pathname += '/';
+  const apiKey = options.apiKey ? requiredString(options.apiKey, 'x402 facilitator API key', 4096) : null;
+  const timeoutMs = Number.isInteger(options.timeoutMs) ? options.timeoutMs : 30_000;
+  if (timeoutMs < 1000 || timeoutMs > 120_000) throw new TypeError('x402 facilitator timeout is invalid');
+
+  async function request(path, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error('x402 facilitator timed out')), timeoutMs);
+    try {
+      const response = await fetch(new URL(path, baseUrl), {
+        method: body === undefined ? 'GET' : 'POST',
+        headers: { Accept: 'application/json', ...(body === undefined ? {} : { 'Content-Type': 'application/json' }), ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: 'error',
+        signal: controller.signal,
+      });
+      const payload = await response.json().catch(() => null);
+      if (!response.ok || !plainObject(payload)) throw new Error(`x402 facilitator failed with HTTP ${response.status}`);
+      return payload;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  return Object.freeze({
+    supported: () => request('supported'),
+    async verify(paymentPayload, paymentRequirements) {
+      const result = await request('verify', { x402Version: X402_VERSION, paymentPayload, paymentRequirements });
+      if (typeof result.isValid !== 'boolean') throw new Error('x402 facilitator returned an invalid verify response');
+      return result;
+    },
+    async settle(paymentPayload, paymentRequirements) {
+      const result = await request('settle', { x402Version: X402_VERSION, paymentPayload, paymentRequirements });
+      if (typeof result.success !== 'boolean' || typeof result.transaction !== 'string' || typeof result.network !== 'string') {
+        throw new Error('x402 facilitator returned an invalid settlement response');
+      }
+      if (result.success && !result.transaction) throw new Error('x402 facilitator reported success without a transaction');
+      return result;
+    },
+  });
+}
+
+function normalizeRoute(route) {
+  if (!route || typeof route !== 'object' || typeof route.execute !== 'function') throw new TypeError('x402 route requires execute()');
+  const method = requiredString(route.method || 'POST', 'x402 route method', 16).toUpperCase();
+  const path = requiredString(route.path, 'x402 route path', 2048);
+  if (!path.startsWith('/') || path.includes('?') || path.includes('#')) throw new TypeError('x402 route path must be absolute without query or fragment');
+  const resource = validateResource(route.resource);
+  const accepts = (route.accepts || []).map((entry, index) => validateRequirement(entry, `accepts[${index}]`));
+  if (!accepts.length) throw new TypeError('x402 route requires at least one payment requirement');
+  for (const requirement of accepts) {
+    const flow = paymentFlow(requirement);
+    if (flow !== 'upfront') throw new TypeError('x402 paid execution routes require explicit upfront settlement before resource execution');
+  }
+  return Object.freeze({ method, path, resource, accepts: Object.freeze(accepts), extensions: route.extensions || {}, execute: route.execute });
+}
+
+async function readRequestBody(request, maximum) {
+  const chunks = [];
+  let size = 0;
+  let tooLarge = false;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > maximum) tooLarge = true;
+    else chunks.push(chunk);
+  }
+  if (tooLarge) throw Object.assign(new Error('x402 request body is too large'), { statusCode: 413 });
+  return Buffer.concat(chunks, size);
+}
+
+function writeJson(response, status, payload, headers = {}) {
+  const body = JSON.stringify(payload);
+  response.statusCode = status;
+  response.setHeader('Cache-Control', 'no-store');
+  response.setHeader('Content-Type', 'application/json; charset=utf-8');
+  response.setHeader('Content-Length', Buffer.byteLength(body));
+  response.setHeader('X-Content-Type-Options', 'nosniff');
+  for (const [name, value] of Object.entries(headers)) response.setHeader(name, value);
+  response.end(body);
+}
+
+export function createX402ResourceHandler(options = {}) {
+  const facilitator = options.facilitator;
+  if (!facilitator || typeof facilitator.verify !== 'function' || typeof facilitator.settle !== 'function') throw new TypeError('x402 facilitator is required');
+  const routes = (options.routes || []).map(normalizeRoute);
+  const routeMap = new Map(routes.map((route) => [`${route.method} ${route.path}`, route]));
+  if (routeMap.size !== routes.length) throw new TypeError('duplicate x402 route');
+  const maxBodyBytes = Number.isInteger(options.maxBodyBytes) ? options.maxBodyBytes : 8 * 1024 * 1024;
+
+  return async function x402ResourceHandler(request, response, parsedUrl = null) {
+    const url = parsedUrl || new URL(request.url || '/', 'http://localhost');
+    const route = routeMap.get(`${request.method} ${url.pathname}`);
+    if (!route) return false;
+    const required = { x402Version: X402_VERSION, error: `${X402_HEADERS.paymentSignature} header is required`, resource: route.resource, accepts: route.accepts, extensions: route.extensions };
+    const paymentHeader = request.headers['payment-signature'];
+    if (!paymentHeader) {
+      writeJson(response, 402, { error: 'payment_required' }, { [X402_HEADERS.paymentRequired]: base64Json(required) });
+      return true;
+    }
+    let phase = 'payment';
+    let settlement = null;
+    let accepted = null;
+    try {
+      const payload = parsePaymentPayloadHeader(paymentHeader);
+      accepted = route.accepts.find((entry) => sameJson(entry, payload.accepted));
+      if (!accepted) throw new TypeError('x402 payment payload selected an unoffered requirement');
+      validatePayloadBinding(payload, required, accepted);
+      phase = 'request';
+      const rawBody = await readRequestBody(request, maxBodyBytes);
+      phase = 'payment';
+      const flow = paymentFlow(accepted);
+      if (flow !== 'upfront') throw new Error('x402 paid execution route is not prepaid');
+      settlement = await facilitator.settle(payload, accepted);
+      if (!settlement.success) throw new Error(settlement.errorReason || 'x402 upfront settlement failed');
+      if (settlement.network !== accepted.network) throw new Error('x402 facilitator settled on a different network');
+      phase = 'resource';
+      const result = await route.execute({ request, url, rawBody, payment: payload, requirement: accepted });
+      writeJson(response, result?.status || 200, result?.body ?? result ?? null, { [X402_HEADERS.paymentResponse]: base64Json(settlement) });
+      return true;
+    } catch (error) {
+      if (phase === 'resource') {
+        writeJson(response, 500, { error: 'resource_error', message: 'paid resource execution failed' }, settlement?.success ? { [X402_HEADERS.paymentResponse]: base64Json(settlement) } : {});
+        return true;
+      }
+      if (phase === 'request') {
+        writeJson(response, error.statusCode || 400, { error: 'invalid_request', message: error.message || 'invalid x402 request' });
+        return true;
+      }
+      const failed = { success: false, errorReason: error.message || 'payment_failed', transaction: '', network: accepted?.network || route.accepts[0].network };
+      writeJson(response, error instanceof TypeError ? 400 : 402, { error: 'payment_failed', message: failed.errorReason }, { [X402_HEADERS.paymentResponse]: base64Json(failed), [X402_HEADERS.paymentRequired]: base64Json(required) });
+      return true;
+    }
+  };
+}
+
+function replayableBody(value) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') return value;
+  if (Buffer.isBuffer(value)) return Buffer.from(value);
+  if (value instanceof Uint8Array) return Buffer.from(value);
+  if (value instanceof URLSearchParams) return value.toString();
+  throw new TypeError('x402 client request body must be replayable bytes, string, or URLSearchParams');
+}
+
+function requirementAllowed(requirement, policy) {
+  if (policy.schemes?.length && !policy.schemes.includes(requirement.scheme)) return false;
+  if (policy.networks?.length && !policy.networks.includes(requirement.network)) return false;
+  if (policy.assets?.length && !policy.assets.includes(requirement.asset)) return false;
+  if (policy.payTo?.length && !policy.payTo.includes(requirement.payTo)) return false;
+  if (policy.paymentFlows?.length && !policy.paymentFlows.includes(paymentFlow(requirement))) return false;
+  const maximum = policy.maxAmounts?.[`${requirement.network}/${requirement.asset}`] ?? policy.maxAmount;
+  if (maximum !== undefined && BigInt(requirement.amount) > BigInt(maximum)) return false;
+  return true;
+}
+
+export function createX402HttpClient(options = {}) {
+  if (typeof options.createPaymentPayload !== 'function') throw new TypeError('x402 client requires createPaymentPayload() from a real wallet signer');
+  if (!Array.isArray(options.networks) || !options.networks.length) throw new TypeError('x402 client requires an explicit network allowlist');
+  if (!Array.isArray(options.assets) || !options.assets.length) throw new TypeError('x402 client requires an explicit asset allowlist');
+  if (!Array.isArray(options.payTo) || !options.payTo.length) throw new TypeError('x402 client requires an explicit recipient allowlist');
+  if (options.maxAmount === undefined && !Object.keys(options.maxAmounts || {}).length) throw new TypeError('x402 client requires an explicit payment budget');
+  const policy = Object.freeze({
+    schemes: options.schemes || ['exact'],
+    networks: options.networks || [],
+    assets: options.assets || [],
+    payTo: options.payTo || [],
+    paymentFlows: options.paymentFlows || ['authorization'],
+    maxAmounts: options.maxAmounts || {},
+    maxAmount: options.maxAmount,
+  });
+
+  return async function x402Fetch(input, init = {}) {
+    const url = secureUrl(input, 'x402 resource URL');
+    const body = replayableBody(init.body);
+    const headers = new Headers(init.headers || {});
+    headers.delete(X402_HEADERS.paymentSignature);
+    headers.delete(X402_HEADERS.paymentRequired);
+    headers.delete(X402_HEADERS.paymentResponse);
+    const requestInit = { ...init, headers, body, redirect: 'manual' };
+    const first = await fetch(url, requestInit);
+    if (first.status !== 402) return { response: first, settlement: null, paymentRequired: null };
+    const paymentRequired = parsePaymentRequiredHeader(first.headers.get(X402_HEADERS.paymentRequired));
+    if (paymentRequired.resource.url !== url.toString()) throw new Error('x402 server requested payment for a different resource URL');
+    const acceptable = paymentRequired.accepts.filter((requirement) => requirementAllowed(requirement, policy));
+    if (!acceptable.length) throw new Error('x402 payment requirements exceed the configured wallet policy');
+    const selected = typeof options.selectPayment === 'function' ? await options.selectPayment(acceptable, paymentRequired) : acceptable[0];
+    if (!acceptable.some((entry) => sameJson(entry, selected))) throw new Error('x402 payment selector returned an unoffered requirement');
+    const payload = await options.createPaymentPayload({ requirement: selected, paymentRequired, resourceUrl: url.toString() });
+    const validated = parsePaymentPayloadHeader(base64Json(payload));
+    validatePayloadBinding(validated, paymentRequired, selected);
+    await first.body?.cancel?.();
+    const paidHeaders = new Headers(headers);
+    paidHeaders.set(X402_HEADERS.paymentSignature, base64Json(validated));
+    const paid = await fetch(url, { ...requestInit, headers: paidHeaders, body: replayableBody(body) });
+    if (paid.status >= 300 && paid.status < 400) throw new Error('x402 paid request redirect was blocked');
+    const responseHeader = paid.headers.get(X402_HEADERS.paymentResponse);
+    if (!responseHeader) throw new Error('x402 paid response omitted PAYMENT-RESPONSE');
+    const settlement = parseSettlementResponseHeader(responseHeader);
+    if (!settlement.success) throw new Error(settlement.errorReason || 'x402 payment failed');
+    if (settlement.network !== selected.network) throw new Error('x402 settlement network mismatch');
+    return { response: paid, settlement, paymentRequired };
+  };
+}

package/packages/proof-network/PACKAGE_CONTRACT.md

@@ -0,0 +1,21 @@
+# Proof Network Contract
+
+`enigma-memory/proof-network` defines canonical schema validation and normalization for sovereign proof network artifacts: anchor batches, capability grants, benchmark attestations, and registry batches.
+
+## Purpose
+
+The package normalizes and validates public-safe cryptographic proof objects:
+- `anchor_batch`: Merkle roots, sequence intervals, and ledger anchoring metadata
+- `capability_grant`: Signed scoped delegation grants
+- `capability_revocation`: Explicit capability invalidations
+- `benchmark_attestation`: Cryptographic benchmark performance records
+- `packet`: Transport envelopes for proof verification
+- `registry_entry` and `registry_batch`: Aggregated proof network registry records
+
+## Boundary & Privacy Guarantees
+
+The package enforces strict zero-leakage boundaries:
+- Zero raw memory or prompt plaintext in proof artifacts
+- Zero embedding vector content on-chain
+- Rejects ungrounded claims, secrets, private keys, tokens, and raw customer data
+- Operates purely offline with deterministic cryptographic validations

package/packages/rag/index.d.ts

@@ -0,0 +1,182 @@
+/// <reference types="node" />
+
+export interface LexicalHashDescriptor {
+  readonly provider: string;
+  readonly version: string;
+  readonly dimension: number;
+  readonly architecture: string;
+  readonly description: string;
+}
+export declare const LEXICAL_HASH_DESCRIPTOR: LexicalHashDescriptor;
+
+
+export interface LocalMiniLmArtifact {
+  readonly path: string;
+  readonly size: number;
+  readonly sha256: string;
+}
+
+export interface LocalMiniLmDescriptor {
+  readonly provider: 'huggingface_transformers_local';
+  readonly package: '@huggingface/transformers';
+  readonly packageVersion: '4.2.0';
+  readonly modelId: 'Xenova/all-MiniLM-L6-v2';
+  readonly immutableCommit: '751bff37182d3f1213fa05d7196b954e230abad9';
+  readonly dimension: 384;
+  readonly maxSequenceLength: 512;
+  readonly dtype: 'q8';
+  readonly device: 'cpu';
+  readonly pooling: 'mean';
+  readonly normalization: 'l2_unit_sphere';
+  readonly manifest: 'sha256-manifest.json';
+  readonly manifestSha256: string;
+  readonly artifacts: readonly LocalMiniLmArtifact[];
+}
+
+export declare const LOCAL_MINILM_DESCRIPTOR: LocalMiniLmDescriptor;
+export declare const ONNX_INTEGRATION_SPEC: LocalMiniLmDescriptor;
+export declare const EMBEDDING_DIM: number;
+export declare function verifyBundledModel(): Promise<void>;
+
+export interface TokenSubword {
+  token: string;
+  isSubword: boolean;
+  pos: number;
+}
+
+export declare function tokenizeSubwords(text: string): TokenSubword[];
+export declare function computeLexicalEmbedding(text: string, dim?: number): Float32Array;
+
+export interface EmbeddingProvider {
+  readonly providerType: 'local_minilm' | 'lexical_hash' | 'onnx_runtime_adapter' | string;
+  readonly descriptor: LocalMiniLmDescriptor | LexicalHashDescriptor;
+  dimension: number;
+  embed(text: string): Promise<Float32Array>;
+  embedSync(text: string): Float32Array;
+  embedBatch(texts: string[]): Promise<Float32Array[]>;
+  dispose(): Promise<void>;
+}
+
+export interface OnnxEmbeddingRunner {
+  run(texts: string[]): Promise<Float32Array[] | number[][]>;
+  dispose?(): void | Promise<void>;
+}
+
+export declare function createEmbeddingProvider(options?: {
+  dimension?: number;
+  modelType?: 'neural' | 'lexical' | 'onnx';
+  onnxRunner?: ((text: string) => Promise<Float32Array | number[]>) | OnnxEmbeddingRunner;
+}): EmbeddingProvider;
+
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare function quantizeVector(floatVec: Float32Array): Int8Array;
+export declare function dequantizeVector(int8Vec: Int8Array): Float32Array;
+
+export declare class BM25Index {
+  k1: number;
+  b: number;
+  docs: Map<string, unknown>;
+  invertedIndex: Map<string, Set<string>>;
+  totalDocLength: number;
+
+  constructor(options?: { k1?: number; b?: number });
+  tokenize(text: string): string[];
+  add(id: string, text: string, scope?: string): void;
+  remove(id: string): void;
+  clear(): void;
+  search(queryText: string, options?: { topK?: number; scope?: string }): Array<{ id: string; text: string; score: number; scope: string }>;
+}
+
+export declare function reciprocalRankFusion(
+  denseResults: Array<{ id: string; text: string; score: number; scope: string; metadata?: Record<string, unknown> }>,
+  bm25Results: Array<{ id: string; text: string; score: number; scope: string }>,
+  options?: { k?: number; denseWeight?: number; bm25Weight?: number; topK?: number }
+): Array<{ id: string; text: string; score: number; denseScore: number; bm25Score: number; scope: string; metadata?: Record<string, unknown> }>;
+
+export declare function semanticReranker(
+  queryText: string,
+  candidates: Array<{ id: string; text: string; score: number; scope: string; metadata?: Record<string, unknown>; importance?: number }>,
+  options?: { topK?: number; phraseBonus?: number; coverageWeight?: number }
+): Array<{ id: string; text: string; score: number; originalScore: number; scope: string; metadata?: Record<string, unknown> }>;
+
+export interface EncryptedVectorStoreOptions {
+  embeddingProvider?: EmbeddingProvider;
+  dimension?: number;
+  quantize?: boolean;
+}
+
+export interface VectorDocument {
+  id: string;
+  text: string;
+  scope: string;
+  importance: number;
+  createdAt: number;
+  metadata: Record<string, unknown>;
+}
+
+export interface SearchResultItem {
+  id: string;
+  text: string;
+  score: number;
+  cosine?: number;
+  scope: string;
+  importance?: number;
+  createdAt?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContextPackCompilation {
+  contextText: string;
+  items: SearchResultItem[];
+  totalChars: number;
+  estimatedTokens: number;
+}
+
+export interface EncryptedVectorBundle {
+  format: string;
+  ciphertext: string;
+  iv: string;
+  authTag: string;
+  count: number;
+}
+
+export declare class EncryptedVectorStore {
+  dimension: number;
+  quantize: boolean;
+  embedder: EmbeddingProvider;
+  documents: Map<string, VectorDocument>;
+  vectors: Map<string, Int8Array | Float32Array>;
+  bm25: BM25Index;
+
+  constructor(options?: EncryptedVectorStoreOptions);
+
+  add(
+    id: string,
+    text: string,
+    metadata?: Record<string, unknown>,
+    options?: { epoch?: number; signal?: AbortSignal }
+  ): Promise<{ id: string; scope: string; dimension: number; quantized: boolean } | null>;
+  addSync(id: string, text: string, metadata?: Record<string, unknown>): { id: string; scope: string; dimension: number; quantized: boolean };
+  addBatch(items: Array<{ id: string; text: string; metadata?: Record<string, unknown> }>): Promise<number>;
+  remove(id: string): boolean;
+  delete(id: string): boolean;
+  clear(): void;
+  get size(): number;
+  search(query: string | Float32Array, options?: { mode?: 'hybrid' | 'dense' | 'bm25'; topK?: number; threshold?: number; scope?: string; denseWeight?: number; bm25Weight?: number }): Promise<SearchResultItem[]>;
+  searchSync(query: string | Float32Array, options?: { mode?: 'hybrid' | 'dense' | 'bm25'; topK?: number; threshold?: number; scope?: string }): SearchResultItem[];
+  searchByVector(queryVec: Float32Array, options?: { topK?: number; threshold?: number; scope?: string }): SearchResultItem[];
+  compileContextPack(query: string, options?: { maxTokens?: number; topK?: number; scope?: string }): Promise<ContextPackCompilation>;
+
+  encryptForVault(vaultKey: Buffer | string): EncryptedVectorBundle;
+  static decryptFromVault(encryptedBundle: EncryptedVectorBundle, vaultKey: Buffer | string, options?: { embeddingProvider?: EmbeddingProvider }): EncryptedVectorStore;
+}
+
+export declare const RESEARCH_DISCLAIMER: {
+  readonly status: string;
+  readonly warning: string;
+};
+
+export declare function generateResearchOrthogonalBasis(seed: string, dim?: number): Float32Array[];
+export declare function applyResearchBasisTransform(vec: Float32Array, basis: Float32Array[]): Float32Array;
+export declare function createResearchBlindedQuery(queryVec: Float32Array, basis: Float32Array[], alpha?: number): { blindedVector: Float32Array; scalar: number };
+export declare function evaluateResearchBlindedRanking(blindedQuery: Float32Array, transformedDocs: Map<string, Float32Array>, topK?: number): Array<{ id: string; rawScore: number }>;