fhir-persistence 0.1.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,3114 @@
+/**
+ * `fhir-persistence` — Embedded FHIR R4 Persistence Layer
+ *
+ * Provides CRUD, search, indexing, schema migration, and terminology
+ * for FHIR R4 resources over SQLite (sql.js / better-sqlite3) and PostgreSQL.
+ *
+ * @packageDocumentation
+ */
+
+import type { Database } from 'better-sqlite3';
+
+export declare class BetterSqlite3Adapter implements StorageAdapter {
+    private db;
+    private closed;
+    constructor(options?: BetterSqlite3Options);
+    private ensureOpen;
+    execute(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+    }>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    queryStream<T = Record<string, unknown>>(sql: string, params?: unknown[]): AsyncIterable<T>;
+    prepare<T = Record<string, unknown>>(sql: string): PreparedStatement<T>;
+    transaction<R>(fn: (tx: TransactionContext) => R | Promise<R>): Promise<R>;
+    close(): Promise<void>;
+    /**
+     * Get the underlying better-sqlite3 Database instance.
+     * Use with caution — bypasses the adapter abstraction.
+     */
+    getRawDatabase(): Database;
+    /**
+     * Execute a PRAGMA and return the result.
+     */
+    pragma(statement: string): unknown;
+    /**
+     * Checkpoint WAL file to main database file.
+     * Useful before backup or when shutting down.
+     */
+    checkpoint(mode?: 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE'): void;
+}
+
+export declare interface BetterSqlite3Options {
+    /** Database file path, or ':memory:' for in-memory database. */
+    path?: string;
+    /** Enable WAL journal mode (default: true). */
+    wal?: boolean;
+    /** Enable foreign key constraints (default: true). */
+    foreignKeys?: boolean;
+    /** Busy timeout in milliseconds (default: 5000). */
+    busyTimeout?: number;
+    /** Additional PRAGMA statements to execute on init. */
+    pragmas?: Record<string, string | number | boolean>;
+}
+
+/**
+ * Build table schemas for ALL non-abstract resource types.
+ *
+ * @returns Array of `ResourceTableSet`, one per concrete resource type, sorted alphabetically.
+ */
+export declare function buildAllResourceTableSets(sdRegistry: StructureDefinitionRegistry, spRegistry: SearchParameterRegistry): ResourceTableSet[];
+
+/**
+ * v2: Build a COUNT query using ? placeholders.
+ */
+export declare function buildCountSQLv2(request: SearchRequest, registry: SearchParameterRegistry): CountSQL;
+
+/**
+ * v2: DELETE all reference rows for a resource (before re-inserting on update).
+ */
+export declare function buildDeleteReferencesSQLv2(tableName: string): string;
+
+/**
+ * Build a FHIR R4 history Bundle from HistoryEntry[].
+ *
+ * @param entries - History entries (newest first).
+ * @param options - Optional bundle metadata.
+ * @returns A FHIR R4 Bundle of type `history`.
+ */
+export declare function buildHistoryBundle(entries: HistoryEntry[], options?: BuildHistoryBundleOptions): HistoryBundle;
+
+/**
+ * Options for building a history bundle.
+ */
+export declare interface BuildHistoryBundleOptions {
+    /** Base URL for fullUrl construction (e.g., `"http://localhost:3000/fhir/R4"`). */
+    baseUrl?: string;
+    /** Total count of matching entries (may differ from entries.length if paginated). */
+    total?: number;
+    /** Self link URL. */
+    selfUrl?: string;
+    /** Next page link URL. */
+    nextUrl?: string;
+}
+
+/**
+ * v2: Build an INSERT statement for the history table.
+ * Uses `?` placeholders. Does NOT include versionSeq (AUTOINCREMENT).
+ */
+export declare function buildInsertHistorySQLv2(tableName: string, columns: Record<string, unknown>): {
+    sql: string;
+    values: unknown[];
+};
+
+/**
+ * v2: Build an INSERT statement for the main resource table.
+ * Uses `?` placeholders (SQLite-compatible).
+ */
+export declare function buildInsertMainSQLv2(tableName: string, columns: Record<string, unknown>): {
+    sql: string;
+    values: unknown[];
+};
+
+/**
+ * v2: Build a multi-row INSERT for the references table.
+ * Each row has 5 columns: resourceId, targetType, targetId, code, referenceRaw.
+ */
+export declare function buildInsertReferencesSQLv2(tableName: string, rowCount: number): string;
+
+/**
+ * v2: Instance history SELECT with optional _since, _count, cursor.
+ * Uses `?` placeholders and ORDER BY versionSeq DESC.
+ */
+export declare function buildInstanceHistorySQLv2(tableName: string, resourceId: string, options?: {
+    since?: string;
+    count?: number;
+    cursor?: string;
+}): {
+    sql: string;
+    values: unknown[];
+};
+
+/**
+ * Extract rows for global lookup tables from a FHIR resource.
+ *
+ * Scans the resource for HumanName, Address, ContactPoint, and Identifier
+ * values and decomposes them into individual rows matching Medplum's schema:
+ *
+ * - `HumanName` → { resourceId, name, given, family }
+ * - `Address`   → { resourceId, address, city, country, postalCode, state, use }
+ * - `ContactPoint` → { resourceId, system, value, use }
+ * - `Identifier` → { resourceId, system, value }
+ *
+ * @param resource - The FHIR resource (must have `id`).
+ * @param impls - SearchParameterImpl list for this resource type.
+ * @returns Array of LookupTableRow to insert into global tables.
+ */
+export declare function buildLookupTableRows(resource: FhirResource & {
+    id: string;
+}, impls: SearchParameterImpl[]): LookupTableRow[];
+
+/**
+ * Build the `next` link URL, or `undefined` if there is no next page.
+ *
+ * A next page exists when the current page returned exactly `count` results,
+ * indicating there may be more.
+ */
+export declare function buildNextLink(ctx: PaginationContext): string | undefined;
+
+/**
+ * Build a pagination context from search request parameters.
+ */
+export declare function buildPaginationContext(baseUrl: string, resourceType: string, queryParams: Record<string, string | string[]>, count: number | undefined, offset: number | undefined, resultCount: number): PaginationContext;
+
+/**
+ * Build ResourceTableSets for all platform resource types.
+ *
+ * Uses StructureDefinitionRegistry + SearchParameterRegistry
+ * populated with platform definitions to generate the table schemas.
+ */
+export declare function buildPlatformTableSets(): ResourceTableSet[];
+
+/**
+ * Build a main table row with search column values populated.
+ *
+ * Extends `buildResourceRow()` by extracting search parameter values
+ * from the resource JSON and merging them into the row.
+ *
+ * @param resource - The persisted resource.
+ * @param searchImpls - SearchParameterImpl list for this resource type.
+ * @returns A `ResourceRow` with both fixed and search columns.
+ */
+export declare function buildResourceRowWithSearch(resource: PersistedResource, searchImpls: SearchParameterImpl[], context?: OperationContext): ResourceRow;
+
+/**
+ * Build the complete 3-table schema for a single resource type.
+ *
+ * @param resourceType - The FHIR resource type (e.g., `'Patient'`).
+ * @param sdRegistry - StructureDefinitionRegistry (used to verify the type exists).
+ * @param spRegistry - SearchParameterRegistry (provides search column definitions).
+ * @returns The complete `ResourceTableSet` for the resource type.
+ * @throws Error if the resource type is not found or is abstract.
+ */
+export declare function buildResourceTableSet(resourceType: string, sdRegistry: StructureDefinitionRegistry, spRegistry: SearchParameterRegistry): ResourceTableSet;
+
+/**
+ * Build a complete `SchemaDefinition` for all resource types.
+ *
+ * @param sdRegistry - StructureDefinitionRegistry with indexed profiles.
+ * @param spRegistry - SearchParameterRegistry with indexed search params.
+ * @param version - Schema version string (default: `'fhir-r4-v4.0.1'`).
+ * @returns The complete `SchemaDefinition`.
+ */
+export declare function buildSchemaDefinition(sdRegistry: StructureDefinitionRegistry, spRegistry: SearchParameterRegistry, version?: string): SchemaDefinition;
+
+/**
+ * Build a FHIR R4 searchset Bundle from PersistedResource[].
+ *
+ * @param resources - Matched resources.
+ * @param options - Optional bundle metadata.
+ * @returns A FHIR R4 Bundle of type `searchset`.
+ */
+export declare function buildSearchBundle(resources: PersistedResource[], options?: BuildSearchBundleOptions): SearchBundle;
+
+/**
+ * Options for building a searchset Bundle.
+ */
+export declare interface BuildSearchBundleOptions {
+    /** Base URL for fullUrl construction (e.g., `"http://localhost:3000/fhir/R4"`). */
+    baseUrl?: string;
+    /** Total count of matching resources (only included when `_total=accurate`). */
+    total?: number;
+    /** Self link URL. */
+    selfUrl?: string;
+    /** Next page link URL. */
+    nextUrl?: string;
+    /** Included resources from _include/_revinclude. */
+    included?: PersistedResource[];
+}
+
+/**
+ * Build search column values for a FHIR resource.
+ *
+ * Given a resource and its applicable SearchParameterImpl list,
+ * extracts values from the resource JSON and returns a map of
+ * column name → value pairs ready for SQL insertion.
+ *
+ * @param resource - The FHIR resource to index.
+ * @param impls - SearchParameterImpl list for this resource type.
+ * @returns Column name → value map for search columns.
+ */
+export declare function buildSearchColumns(resource: FhirResource, impls: SearchParameterImpl[]): SearchColumnValues;
+
+/**
+ * v2: Build a complete search SQL query using ? placeholders.
+ * No projectId filter. deleted = 0 (INTEGER).
+ */
+export declare function buildSearchSQLv2(request: SearchRequest, registry: SearchParameterRegistry): SearchSQL;
+
+/**
+ * v2: SELECT by ID — no projectId, returns versionId + deleted.
+ */
+export declare function buildSelectByIdSQLv2(tableName: string): string;
+
+/**
+ * v2: SELECT a specific version from the history table.
+ */
+export declare function buildSelectVersionSQLv2(tableName: string): string;
+
+/**
+ * Build the `self` link URL for the current search page.
+ */
+export declare function buildSelfLink(ctx: PaginationContext): string;
+
+/**
+ * v2: Build two-phase search SQL for improved performance on large tables.
+ *
+ * ## Strategy
+ *
+ * **Phase 1** — Lightweight id-only query with all filters, sorting, and pagination.
+ * Only reads the indexed columns, avoiding expensive content deserialization.
+ *
+ * ```sql
+ * SELECT "id" FROM "Patient"
+ * WHERE "deleted" = 0 AND "birthdate" >= ?
+ * ORDER BY "lastUpdated" DESC
+ * LIMIT ?
+ * ```
+ *
+ * **Phase 2** — Fetch full content for matched ids (executed by caller).
+ *
+ * ```sql
+ * SELECT "id", "versionId", "content", "lastUpdated", "deleted"
+ * FROM "Patient"
+ * WHERE "id" IN (?, ?, ?)
+ * ```
+ *
+ * @param request - The parsed search request.
+ * @param registry - The SearchParameterRegistry.
+ * @returns TwoPhaseSearchSQL with phase1 query and phase2 template.
+ */
+export declare function buildTwoPhaseSearchSQLv2(request: SearchRequest, registry: SearchParameterRegistry): TwoPhaseSearchSQL;
+
+/**
+ * v2: Type-level history SELECT.
+ * Uses `?` placeholders and ORDER BY versionSeq DESC.
+ */
+export declare function buildTypeHistorySQLv2(tableName: string, options?: {
+    since?: string;
+    count?: number;
+    cursor?: string;
+}): {
+    sql: string;
+    values: unknown[];
+};
+
+/**
+ * v2: Build an UPDATE statement for the main resource table.
+ * Uses `?` placeholders. Updates all columns except `id`.
+ */
+export declare function buildUpdateMainSQLv2(tableName: string, columns: Record<string, unknown>): {
+    sql: string;
+    values: unknown[];
+};
+
+/**
+ * v2: Build a complete WHERE clause from parsed search params using ? placeholders.
+ */
+export declare function buildWhereClauseV2(params: ParsedSearchParam[], registry: SearchParameterRegistry, resourceType: string): WhereFragment | null;
+
+/**
+ * v2: Build a WHERE clause fragment using ? placeholders (SQLite).
+ *
+ * Dispatches to type-specific v2 builders. Key differences from v1:
+ * - Uses `?` instead of `$N`
+ * - Token search uses `json_each()` instead of `ARRAY[]::text[]`
+ * - Array columns use `json_each()` instead of PG array operators
+ */
+export declare function buildWhereFragmentV2(impl: SearchParameterImpl, param: ParsedSearchParam): WhereFragment | null;
+
+declare interface BundleLink {
+    relation: string;
+    url: string;
+}
+
+/**
+ * StructureDefinition Registry
+ *
+ * Indexes `CanonicalProfile[]` by resource type for fast lookup.
+ * MedXAI equivalent of Medplum's `indexStructureDefinitionBundle()` →
+ * `DATA_TYPES`, but as an injectable instance (no global state).
+ *
+ * Used by `TableSchemaBuilder` to determine which resource types
+ * need tables and to access element definitions for search column
+ * generation.
+ *
+ * @module fhir-persistence/registry
+ */
+/**
+ * Minimal CanonicalProfile shape (replaces @medxai/fhir-core dependency).
+ */
+export declare interface CanonicalProfile {
+    url: string;
+    name: string;
+    kind: 'resource' | 'complex-type' | 'primitive-type' | 'logical';
+    type: string;
+    abstract: boolean;
+    elements: Map<string, unknown>;
+}
+
+/**
+ * Target information for a chained search parameter.
+ *
+ * Example: `subject:Patient.name=Smith`
+ * - `targetType` = `"Patient"`
+ * - `targetParam` = `"name"`
+ */
+declare interface ChainedSearchTarget {
+    /** The target resource type (e.g., `"Patient"`). */
+    targetType: string;
+    /** The search parameter on the target resource (e.g., `"name"`). */
+    targetParam: string;
+}
+
+/**
+ * Minimal CodeSystem shape used by fhir-persistence.
+ */
+declare interface CodeSystemDef {
+    resourceType: 'CodeSystem';
+    url: string;
+    name?: string;
+    status?: string;
+    content?: string;
+    concept?: Array<{
+        code: string;
+        display?: string;
+        definition?: string;
+        concept?: unknown[];
+    }>;
+    [key: string]: unknown;
+}
+
+/**
+ * Definition of a single database column.
+ *
+ * v2: Dialect-neutral. DDLGenerator maps types to dialect-specific
+ * equivalents (e.g., BOOLEAN → INTEGER for SQLite).
+ */
+export declare interface ColumnSchema {
+    /** Column name (e.g., `id`, `content`, `birthdate`). */
+    name: string;
+    /** Logical SQL data type (mapped to dialect-specific type in DDL). */
+    type: SqlColumnType;
+    /** Whether the column has a NOT NULL constraint. */
+    notNull: boolean;
+    /** Whether this column is the primary key. */
+    primaryKey: boolean;
+    /** SQL default value expression (e.g., `'false'`, `'0'`). */
+    defaultValue?: string;
+    /** Source FHIRPath expression (documentation only). */
+    fhirPath?: string;
+    /** Source SearchParameter.code (documentation only). */
+    searchParamCode?: string;
+    /**
+     * v2: Search parameter storage strategy.
+     * Enables SchemaDiff to understand column purpose.
+     */
+    strategy?: 'column' | 'token-column' | 'lookup-table' | 'skip';
+}
+
+/**
+ * Compare two sets of ResourceTableSets and produce a list of deltas.
+ *
+ * @param oldSets - The previously installed schema (from PackageRegistry).
+ * @param newSets - The newly generated schema (from current IG).
+ * @returns Array of SchemaDelta describing all changes.
+ */
+export declare function compareSchemas(oldSets: ResourceTableSet[], newSets: ResourceTableSet[]): SchemaDelta[];
+
+/**
+ * Definition of a PostgreSQL table constraint.
+ */
+export declare interface ConstraintSchema {
+    /** Constraint name (e.g., `Patient_pk`). */
+    name: string;
+    /** Constraint type. */
+    type: 'primary_key' | 'unique' | 'check';
+    /** Columns involved (for primary_key and unique). */
+    columns?: string[];
+    /** SQL expression (for check constraints). */
+    expression?: string;
+}
+
+/**
+ * Result of a count query.
+ */
+export declare interface CountSQL {
+    /** The SQL COUNT query string. */
+    sql: string;
+    /** The parameter values for the query. */
+    values: unknown[];
+}
+
+/**
+ * Create a FhirRuntimeProvider from the fhir-runtime package.
+ *
+ * Usage:
+ * ```typescript
+ * import { extractSearchValues, extractAllSearchValues, extractReferences } from 'fhir-runtime';
+ *
+ * const provider = createFhirRuntimeProvider({
+ *   extractSearchValues,
+ *   extractAllSearchValues,
+ *   extractReferences,
+ * });
+ * ```
+ */
+export declare function createFhirRuntimeProvider(options: FhirRuntimeProviderOptions): FhirRuntimeProvider;
+
+/**
+ * Options for `createResource()`.
+ */
+export declare interface CreateResourceOptions {
+    /**
+     * Pre-assigned UUID for the resource.
+     * Used in batch/transaction operations where the ID is determined
+     * before the create call.
+     */
+    assignedId?: string;
+}
+
+declare interface CreateResourceOptions_2 {
+    /** Pre-assigned ID (used in batch/transaction). */
+    assignedId?: string;
+}
+
+declare interface CreateResourceOptions_3 {
+    /** Pre-assigned ID (used in batch/transaction). */
+    assignedId?: string;
+}
+
+declare type DDLDialect = 'sqlite' | 'postgres';
+
+/**
+ * Default page size for search results.
+ */
+export declare const DEFAULT_SEARCH_COUNT = 20;
+
+/**
+ * Bridge interface for fhir-definition registry.
+ *
+ * fhir-persistence depends only on this interface, never on
+ * fhir-definition internal types. Implementations may wrap
+ * `InMemoryDefinitionRegistry` or provide test-only mocks.
+ *
+ * ADR-01 §2.3 — structural typing, no `implements` required.
+ */
+declare interface DefinitionProvider {
+    /**
+     * Get a StructureDefinition by canonical URL.
+     */
+    getStructureDefinition(url: string): StructureDefinitionDef | undefined;
+    /**
+     * Get a ValueSet by canonical URL.
+     */
+    getValueSet(url: string): ValueSetDef | undefined;
+    /**
+     * Get a CodeSystem by canonical URL.
+     */
+    getCodeSystem(url: string): CodeSystemDef | undefined;
+    /**
+     * Get all SearchParameters for a specific resource type.
+     */
+    getSearchParameters(resourceType: string): SearchParameterDef[];
+    /**
+     * Enumerate all known resource types.
+     * Used by SchemaEngine and ReindexCLI to iterate over all tables.
+     */
+    getAllResourceTypes(): string[];
+    /**
+     * Get metadata about loaded packages (optional).
+     */
+    getLoadedPackages?(): LoadedPackageDef[];
+}
+
+/**
+ * Schema version for deleted resources.
+ */
+export declare const DELETED_SCHEMA_VERSION = -1;
+
+export declare type DeltaKind = 'ADD_TABLE' | 'DROP_TABLE' | 'ADD_COLUMN' | 'DROP_COLUMN' | 'ALTER_COLUMN' | 'ADD_INDEX' | 'DROP_INDEX' | 'REINDEX';
+
+/**
+ * Eviction policy for the cache.
+ *
+ * - `lru` — Least Recently Used: evict the entry that was accessed longest ago.
+ * - `fifo` — First In First Out: evict the entry that was inserted first.
+ * - `ttl-only` — No size-based eviction; entries only expire via TTL.
+ */
+declare type EvictionPolicy = 'lru' | 'fifo' | 'ttl-only';
+
+/**
+ * v2: Execute a FHIR search query using StorageAdapter.
+ *
+ * Key differences from v1:
+ * - Uses `StorageAdapter` instead of `DatabaseClient`
+ * - Uses `?` placeholders (SQLite)
+ * - `deleted` is number (0/1), not boolean
+ * - No `_include` / `_revinclude` in this MVP (can be added)
+ */
+export declare function executeSearch(adapter: StorageAdapter, request: SearchRequest, registry: SearchParameterRegistry, options?: SearchOptions_2): Promise<SearchResult_2>;
+
+/**
+ * A reference extracted from a FHIR resource.
+ */
+declare interface ExtractedReference {
+    /** The SearchParameter code (e.g., 'subject', 'performer'). */
+    code: string;
+    /** The full reference string (e.g., 'Patient/123'). */
+    reference: string;
+    /** The target resource type (e.g., 'Patient'). */
+    targetType: string;
+    /** The target resource ID (e.g., '123'). */
+    targetId: string;
+}
+
+/**
+ * Extract a search prefix from values if the parameter type supports it.
+ *
+ * Prefixes are two-letter codes at the start of the first value:
+ * - `"ge1990-01-01"` → prefix `"ge"`, value `"1990-01-01"`
+ * - `"male"` → no prefix, value `"male"`
+ *
+ * Only number, date, and quantity types support prefixes.
+ */
+export declare function extractPrefix(values: string[], paramType?: string): {
+    prefix?: SearchPrefix;
+    cleanValues: string[];
+};
+
+/**
+ * Extract the property path for a given resource type from a FHIRPath expression.
+ *
+ * Handles:
+ * - Simple: `"Patient.birthDate"` → `["birthDate"]`
+ * - Union: `"Patient.name | Practitioner.name"` → `["name"]` (for Patient)
+ * - .where(): `"Account.subject.where(resolve() is Patient)"` → `["subject"]`
+ * - Nested: `"Observation.value.as(Quantity)"` → `["valueQuantity"]` (special)
+ * - Deep: `"Patient.contact.name"` → `["contact", "name"]`
+ *
+ * @returns Array of path segments, or null if no matching path found.
+ */
+export declare function extractPropertyPath(expression: string, resourceType: string): string[] | null;
+
+/**
+ * v2: Extract all outgoing reference rows with targetType + referenceRaw.
+ */
+export declare function extractReferencesV2(resource: FhirResource, impls: SearchParameterImpl[]): ReferenceRowV2[];
+
+/**
+ * Bridges a fhir-definition DefinitionRegistry into our DefinitionProvider.
+ *
+ * Usage:
+ * ```typescript
+ * import { loadDefinitionPackages } from 'fhir-definition';
+ *
+ * const { registry } = await loadDefinitionPackages({ ... });
+ * const provider = new FhirDefinitionBridge(registry);
+ *
+ * // Use with FhirSystem
+ * const system = new FhirSystem(adapter);
+ * await system.initialize(provider);
+ * ```
+ */
+export declare class FhirDefinitionBridge implements DefinitionProvider {
+    private readonly registry;
+    private cachedResourceTypes;
+    constructor(registry: FhirDefinitionRegistry);
+    getStructureDefinition(url: string): StructureDefinitionDef | undefined;
+    getValueSet(url: string): ValueSetDef | undefined;
+    getCodeSystem(url: string): CodeSystemDef | undefined;
+    getSearchParameters(resourceType: string): SearchParameterDef[];
+    getAllResourceTypes(): string[];
+    getLoadedPackages(): LoadedPackageDef[];
+}
+
+/**
+ * Structural type matching fhir-definition's DefinitionRegistry.
+ * Uses `any` for return types to bridge between fhir-definition's
+ * concrete types and our minimal structural types.
+ */
+declare interface FhirDefinitionRegistry {
+    getStructureDefinition(url: string): any | undefined;
+    getValueSet(url: string): any | undefined;
+    getCodeSystem(url: string): any | undefined;
+    getSearchParameters(resourceType: string): any[];
+    listStructureDefinitions(): string[];
+    getLoadedPackages?(): any[];
+    getStatistics?(): any;
+}
+
+/**
+ * FHIR Meta element (subset used by the repository).
+ */
+export declare interface FhirMeta {
+    versionId?: string;
+    lastUpdated?: string;
+    source?: string;
+    profile?: string[];
+    [key: string]: unknown;
+}
+
+export declare class FhirPersistence {
+    private readonly adapter;
+    private readonly registry;
+    private readonly pipeline;
+    constructor(adapter: StorageAdapter, registry: SearchParameterRegistry, options?: FhirPersistenceOptions);
+    /** Get the underlying StorageAdapter. */
+    getAdapter(): StorageAdapter;
+    /** Get the SearchParameterRegistry. */
+    getRegistry(): SearchParameterRegistry;
+    /** Get the IndexingPipeline. */
+    getPipeline(): IndexingPipeline;
+    createResource<T extends FhirResource>(resourceType: string, resource: T, options?: CreateResourceOptions_3): Promise<T & PersistedResource>;
+    readResource(resourceType: string, id: string): Promise<PersistedResource>;
+    updateResource<T extends FhirResource>(resourceType: string, resource: T, options?: UpdateResourceOptions_3): Promise<T & PersistedResource>;
+    deleteResource(resourceType: string, id: string): Promise<void>;
+    readVersion(resourceType: string, id: string, versionId: string): Promise<PersistedResource>;
+    readHistory(resourceType: string, id: string, options?: HistoryOptions_3): Promise<HistoryEntry[]>;
+    /**
+     * Stream search results row-by-row for large result sets.
+     *
+     * Uses `StorageAdapter.queryStream` for true row-by-row iteration
+     * without loading all results into memory. Useful for:
+     * - Export operations ($export)
+     * - Reindex-all workflows
+     * - Large batch processing
+     *
+     * NOTE: Does NOT include _include/_revinclude resources.
+     * Use `searchResources` for full FHIR search with includes.
+     */
+    searchStream(resourceType: string, sql: string, params?: unknown[]): AsyncGenerator<PersistedResource>;
+    /**
+     * Re-index an existing resource (update search columns + references + lookup).
+     * Does NOT create a new version.
+     */
+    reindexResource(resourceType: string, id: string): Promise<void>;
+    private getImpls;
+}
+
+export declare interface FhirPersistenceOptions {
+    /** Indexing pipeline options. */
+    indexing?: IndexingPipelineOptions;
+}
+
+/**
+ * Minimal FHIR resource shape for persistence operations.
+ *
+ * This is intentionally loose — the repository does not validate
+ * resource structure (that's the validator's job). It only requires
+ * `resourceType` and optionally `id` / `meta`.
+ */
+export declare interface FhirResource {
+    resourceType: string;
+    id?: string;
+    meta?: FhirMeta;
+    [key: string]: unknown;
+}
+
+export declare class FhirRuntimeProvider implements RuntimeProvider {
+    private readonly opts;
+    constructor(options: FhirRuntimeProviderOptions);
+    extractSearchValues(resource: Record<string, unknown>, params: SearchParameterDef[]): Record<string, unknown[]>;
+    extractReferences(resource: Record<string, unknown>, params: SearchParameterDef[]): ExtractedReference[];
+    /**
+     * Convert our minimal SearchParameterDef to fhir-runtime's SearchParameter shape.
+     */
+    private toRuntimeSearchParameter;
+    /**
+     * Normalize fhir-runtime SearchIndexValue[] to persistence-friendly unknown[].
+     */
+    private normalizeSearchValues;
+    /**
+     * Normalize token values to "system|code" strings.
+     */
+    private normalizeTokenValues;
+}
+
+/**
+ * Options for creating a FhirRuntimeProvider.
+ *
+ * Uses `any` for function signatures to bridge between fhir-runtime's
+ * narrow union types (e.g., SearchParamType) and our structural types.
+ * The conversion is handled internally by FhirRuntimeProvider.
+ */
+export declare interface FhirRuntimeProviderOptions {
+    /**
+     * The `extractSearchValues` function from fhir-runtime.
+     * Signature: (resource: Resource, searchParam: SearchParameter) => SearchIndexEntry
+     */
+    extractSearchValues: (resource: any, searchParam: any) => any;
+    /**
+     * The `extractAllSearchValues` function from fhir-runtime.
+     * Signature: (resource: Resource, searchParams: SearchParameter[]) => SearchIndexEntry[]
+     */
+    extractAllSearchValues: (resource: any, searchParams: any[]) => any[];
+    /**
+     * The `extractReferences` function from fhir-runtime.
+     * Signature: (resource: Resource) => ReferenceInfo[]
+     */
+    extractReferences: (resource: any) => any[];
+}
+
+export declare class FhirStore {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    createResource<T extends FhirResource>(resourceType: string, resource: T, options?: CreateResourceOptions_2): Promise<T & PersistedResource>;
+    readResource(resourceType: string, id: string): Promise<PersistedResource>;
+    updateResource<T extends FhirResource>(resourceType: string, resource: T, options?: UpdateResourceOptions_2): Promise<T & PersistedResource>;
+    deleteResource(resourceType: string, id: string): Promise<void>;
+    readVersion(resourceType: string, id: string, versionId: string): Promise<PersistedResource>;
+    readHistory(resourceType: string, id: string, options?: HistoryOptions_2): Promise<HistoryEntry[]>;
+    writeReferences(resourceType: string, resourceId: string, refs: ReferenceRowV2[]): Promise<void>;
+}
+
+export declare class FhirSystem {
+    private readonly adapter;
+    private readonly dialect;
+    private readonly options;
+    constructor(adapter: StorageAdapter, options?: FhirSystemOptions);
+    /**
+     * Initialize the full FHIR persistence system.
+     *
+     * Flow (ADR-01 §4.1):
+     * ```
+     * DefinitionProvider
+     *   → populate SD/SP registries
+     *   → buildResourceTableSets
+     *   → IGPersistenceManager.initialize (DDL + migration)
+     *   → FhirPersistence(adapter, spRegistry, { runtimeProvider })
+     * ```
+     */
+    initialize(definitionProvider: DefinitionProvider): Promise<FhirSystemReady>;
+    /**
+     * Bridge DefinitionProvider → StructureDefinitionRegistry + SearchParameterRegistry.
+     *
+     * Converts DefinitionProvider's minimal types to the existing registry
+     * types expected by the schema builder and indexing pipeline.
+     */
+    private populateRegistries;
+    private buildTableSets;
+    /**
+     * Simple checksum from table set structure for change detection.
+     * Uses JSON serialization of table schemas (column names + types).
+     */
+    private computeChecksum;
+}
+
+export declare interface FhirSystemOptions {
+    /** SQL dialect (default: 'sqlite'). */
+    dialect?: DDLDialect;
+    /** Optional RuntimeProvider for FHIRPath-driven extraction. */
+    runtimeProvider?: RuntimeProvider;
+    /** Enable lookup tables in the indexing pipeline (default: true). */
+    enableLookupTables?: boolean;
+    /** Enable reference indexing (default: true). */
+    enableReferences?: boolean;
+    /** Package name for IG persistence tracking (default: 'fhir-persistence.default'). */
+    packageName?: string;
+    /** Package version (default: '1.0.0'). */
+    packageVersion?: string;
+}
+
+export declare interface FhirSystemReady {
+    /** The initialized FhirPersistence facade. */
+    persistence: FhirPersistence;
+    /** StructureDefinition registry (populated from DefinitionProvider). */
+    sdRegistry: StructureDefinitionRegistry;
+    /** SearchParameter registry (populated from DefinitionProvider). */
+    spRegistry: SearchParameterRegistry;
+    /** IG initialization result (new/upgrade/consistent). */
+    igResult: IGInitResult;
+    /** Resource types with tables. */
+    resourceTypes: string[];
+}
+
+/**
+ * Generate a `CREATE TABLE IF NOT EXISTS` statement for a history table.
+ *
+ * v2: Handles versionSeq AUTOINCREMENT for SQLite and GENERATED ALWAYS for PG.
+ */
+export declare function generateCreateHistoryTable(table: HistoryTableSchema, dialect?: DDLDialect): string;
+
+/**
+ * Generate a `CREATE INDEX IF NOT EXISTS` statement.
+ *
+ * Supports:
+ * - `opClass` — operator class appended to each column key (e.g., `gin_trgm_ops`)
+ * - `expression` — functional expression to index instead of plain columns
+ *   (e.g., `to_tsvector('simple'::regconfig, family)`)
+ */
+export declare function generateCreateIndex(index: IndexSchema, tableName: string, dialect?: DDLDialect): string | null;
+
+/**
+ * Generate a `CREATE TABLE IF NOT EXISTS` statement for a main table.
+ */
+export declare function generateCreateMainTable(table: MainTableSchema, dialect?: DDLDialect): string;
+
+/**
+ * Generate a `CREATE TABLE IF NOT EXISTS` statement for a references table.
+ */
+export declare function generateCreateReferencesTable(table: ReferencesTableSchema, dialect?: DDLDialect): string;
+
+export declare interface GeneratedMigration {
+    /** SQL statements to apply (up). */
+    up: string[];
+    /** SQL statements to revert (down). Best-effort; some are irreversible. */
+    down: string[];
+    /** Deltas that require reindex (no DDL, just scheduling). */
+    reindexDeltas: SchemaDelta[];
+    /** Human-readable description of changes. */
+    description: string;
+}
+
+/**
+ * Generate SQL DDL from a list of schema deltas.
+ *
+ * @param deltas - Schema changes to apply.
+ * @param dialect - Target SQL dialect.
+ * @returns Generated migration with up/down SQL and reindex info.
+ */
+export declare function generateMigration(deltas: SchemaDelta[], dialect: DDLDialect): GeneratedMigration;
+
+/**
+ * Generate all DDL statements for a single resource type (3 tables + indexes).
+ *
+ * Returns an array of SQL statements in order:
+ * 1. CREATE TABLE for main table
+ * 2. CREATE TABLE for history table
+ * 3. CREATE TABLE for references table
+ * 4. All CREATE INDEX statements
+ */
+export declare function generateResourceDDL(tableSet: ResourceTableSet, dialect?: DDLDialect): string[];
+
+/**
+ * Generate all DDL statements for a complete schema definition.
+ *
+ * Order:
+ * 1. Global lookup tables (HumanName, Address, ContactPoint, Identifier)
+ * 2. Resource tables (main, history, references)
+ * 3. All indexes (global lookup + resource tables)
+ *
+ * @param schema - The complete schema definition.
+ * @returns Array of SQL DDL statements.
+ */
+export declare function generateSchemaDDL(schema: SchemaDefinition, dialect?: DDLDialect): string[];
+
+/**
+ * Generate the complete DDL as a single string, with statements
+ * separated by double newlines.
+ *
+ * Includes a header comment with version and generation timestamp.
+ */
+export declare function generateSchemaDDLString(schema: SchemaDefinition, dialect?: DDLDialect): string;
+
+/**
+ * Navigate a resource object using a property path and return the value(s).
+ *
+ * Handles arrays at any level — if a path segment hits an array,
+ * the remaining path is applied to each element.
+ *
+ * @returns Array of extracted values (may be empty).
+ */
+export declare function getNestedValues(obj: unknown, pathSegments: string[]): unknown[];
+
+/**
+ * Schema for a global shared lookup table (e.g., `HumanName`, `Address`).
+ *
+ * Matches Medplum's production-verified design where a single table
+ * stores data from ALL resource types that use that complex type.
+ *
+ * - `HumanName` — stores name/given/family from Patient.name, Practitioner.name, etc.
+ * - `Address` — stores address/city/country/postalCode/state/use
+ * - `ContactPoint` — stores system/value/use from telecom fields
+ * - `Identifier` — stores system/value from identifier fields
+ */
+declare interface GlobalLookupTableSchema {
+    /** Table name (e.g., `'HumanName'`, `'Address'`). */
+    tableName: LookupTableType;
+    /** All columns. */
+    columns: ColumnSchema[];
+    /** All indexes. */
+    indexes: IndexSchema[];
+}
+
+/**
+ * Generate a deterministic UUID-like hash for a token value.
+ *
+ * Produces a v4-format UUID string from the SHA-256 hash of `system|code`.
+ * This matches Medplum's approach of using a deterministic hash for token
+ * search columns (UUID[] type).
+ */
+export declare function hashToken(system: string, code: string): string;
+
+/**
+ * Determine whether there is a next page of results.
+ *
+ * Returns `true` when the current page is full (resultCount === count),
+ * indicating there may be more results.
+ */
+export declare function hasNextPage(ctx: PaginationContext): boolean;
+
+/**
+ * A FHIR R4 Bundle (minimal shape for history).
+ */
+export declare interface HistoryBundle {
+    resourceType: 'Bundle';
+    id: string;
+    type: 'history';
+    total: number;
+    link?: BundleLink[];
+    entry?: HistoryBundleEntry[];
+}
+
+export declare interface HistoryBundleEntry {
+    fullUrl?: string;
+    resource?: Record<string, unknown>;
+    request: {
+        method: string;
+        url: string;
+    };
+    response: {
+        status: string;
+        etag?: string;
+        lastModified?: string;
+    };
+}
+
+/**
+ * A single entry in a history result, including delete markers.
+ */
+export declare interface HistoryEntry {
+    /** The resource (null for delete entries). */
+    resource: PersistedResource | null;
+    /** The versionId for this entry. */
+    versionId: string;
+    /** The timestamp of this version. */
+    lastUpdated: string;
+    /** Whether this entry represents a deletion. */
+    deleted: boolean;
+    /** The resource type (needed for delete entries where resource is null). */
+    resourceType: string;
+    /** The resource id. */
+    id: string;
+}
+
+/**
+ * Options for history queries.
+ */
+export declare interface HistoryOptions {
+    /**
+     * Only include versions updated after this instant.
+     * Corresponds to the `_since` parameter.
+     */
+    since?: string;
+    /**
+     * Maximum number of entries to return.
+     * Corresponds to the `_count` parameter.
+     */
+    count?: number;
+    /**
+     * Cursor for pagination — the `lastUpdated` value of the last
+     * entry from the previous page. Only entries with `lastUpdated`
+     * strictly before this value are returned.
+     */
+    cursor?: string;
+}
+
+declare interface HistoryOptions_2 {
+    since?: string;
+    count?: number;
+    cursor?: string;
+}
+
+declare interface HistoryOptions_3 {
+    since?: string;
+    count?: number;
+    cursor?: string;
+}
+
+/**
+ * Schema for a FHIR resource history table.
+ *
+ * Stores all historical versions of a resource.
+ * Fixed structure — no search columns.
+ */
+export declare interface HistoryTableSchema {
+    /** Table name (e.g., `'Patient_History'`). */
+    tableName: string;
+    /** FHIR resource type name. */
+    resourceType: string;
+    /** All columns (fixed). */
+    columns: ColumnSchema[];
+    /** All indexes (fixed). */
+    indexes: IndexSchema[];
+}
+
+declare type IGInitAction = 'new' | 'upgrade' | 'consistent';
+
+declare interface IGInitResult {
+    /** What action was taken. */
+    action: IGInitAction;
+    /** Package name. */
+    packageName: string;
+    /** Package version. */
+    packageVersion: string;
+    /** Number of DDL statements applied (0 for 'consistent'). */
+    ddlCount: number;
+    /** Number of reindex jobs scheduled. */
+    reindexCount: number;
+    /** Error message if any step failed. */
+    error?: string;
+}
+
+declare interface IGPackageInput {
+    /** Package name (e.g., "hl7.fhir.r4.core"). */
+    name: string;
+    /** Package version (e.g., "4.0.1"). */
+    version: string;
+    /** Content checksum for change detection. */
+    checksum: string;
+    /** The new schema table sets generated from this package. */
+    tableSets: ResourceTableSet[];
+}
+
+export declare class IGPersistenceManager {
+    private readonly dialect;
+    private readonly packageRepo;
+    private readonly migrationRunner;
+    private readonly reindexScheduler;
+    constructor(adapter: StorageAdapter, dialect?: DDLDialect);
+    /**
+     * Initialize an IG package — the main entry point.
+     *
+     * Three-way branch based on checksum comparison:
+     * - **new**: Fresh install → apply full schema DDL
+     * - **upgrade**: Checksum changed → diff + apply migration
+     * - **consistent**: Checksum matches → no-op
+     */
+    initialize(input: IGPackageInput): Promise<IGInitResult>;
+}
+
+/**
+ * A parsed `_include` or `_revinclude` target.
+ *
+ * Syntax: `{sourceType}:{searchParam}` or `{sourceType}:{searchParam}:{targetType}`
+ *
+ * Examples:
+ * - `_include=MedicationRequest:patient` → `{ resourceType: "MedicationRequest", searchParam: "patient" }`
+ * - `_include=Observation:subject:Patient` → `{ resourceType: "Observation", searchParam: "subject", targetType: "Patient" }`
+ */
+declare interface IncludeTarget {
+    /** Source resource type (e.g., "MedicationRequest"). */
+    resourceType: string;
+    /** Search parameter code (e.g., "patient", "subject"). */
+    searchParam: string;
+    /** Optional target type filter (e.g., "Patient"). */
+    targetType?: string;
+    /**
+     * If true, this is an `_include:iterate` — recursively include
+     * resources referenced by included resources (max depth 3, with cycle detection).
+     */
+    iterate?: boolean;
+    /**
+     * If true, this is a wildcard `_include=*` — include ALL referenced resources.
+     */
+    wildcard?: boolean;
+}
+
+export declare class IndexingPipeline {
+    private readonly adapter;
+    private readonly lookupWriter;
+    private readonly options;
+    private readonly runtimeProvider;
+    constructor(adapter: StorageAdapter, options?: IndexingPipelineOptions);
+    /**
+     * Index a resource: extract search columns, write references, write lookup rows.
+     *
+     * @param resourceType - The FHIR resource type (e.g., "Patient").
+     * @param resource - The FHIR resource (must have `id`).
+     * @param impls - SearchParameterImpl list for this resource type.
+     * @returns IndexResult with search columns and write counts.
+     */
+    indexResource(resourceType: string, resource: FhirResource, impls: SearchParameterImpl[]): Promise<IndexResult>;
+    /**
+     * Remove all index data for a deleted resource.
+     *
+     * @param resourceType - The FHIR resource type.
+     * @param resourceId - The resource ID.
+     */
+    deleteIndex(resourceType: string, resourceId: string): Promise<void>;
+    /**
+     * Extract search column values without writing references or lookup rows.
+     * Useful for re-indexing or testing.
+     */
+    extractSearchColumns(resource: FhirResource, impls: SearchParameterImpl[]): SearchColumnValues;
+    /**
+     * Extract reference rows without writing them.
+     * Useful for re-indexing or testing.
+     */
+    extractReferences(resource: FhirResource, impls: SearchParameterImpl[]): ReferenceRowV2[];
+    /**
+     * Extract lookup table rows without writing them.
+     * Useful for re-indexing or testing.
+     */
+    extractLookupRows(resource: FhirResource, impls: SearchParameterImpl[]): LookupTableRow[];
+    /**
+     * Get the underlying LookupTableWriter for direct access.
+     */
+    getLookupWriter(): LookupTableWriter;
+    private writeReferences;
+    private writeLookupRows;
+    /**
+     * Convert SearchParameterImpl[] to SearchParameterDef[] for RuntimeProvider.
+     */
+    private implsToDefs;
+    /**
+     * Extract search column values via RuntimeProvider.
+     */
+    private extractViaRuntime;
+    /**
+     * Extract references via RuntimeProvider → ReferenceRowV2[].
+     */
+    private extractRefsViaRuntime;
+}
+
+/**
+ * Options for the indexing pipeline.
+ */
+export declare interface IndexingPipelineOptions {
+    /** Enable lookup table writes (default: true). */
+    enableLookupTables?: boolean;
+    /** Enable reference indexing (default: true). */
+    enableReferences?: boolean;
+    /** Optional RuntimeProvider for FHIRPath-driven extraction (B3). */
+    runtimeProvider?: RuntimeProvider;
+}
+
+/**
+ * Result of indexing a single resource.
+ */
+export declare interface IndexResult {
+    /** Search column values to merge into the main table row. */
+    searchColumns: SearchColumnValues;
+    /** Reference rows written to {RT}_References table. */
+    referenceCount: number;
+    /** Lookup table rows written to global lookup tables. */
+    lookupRowCount: number;
+}
+
+/**
+ * Definition of a PostgreSQL index.
+ */
+export declare interface IndexSchema {
+    /** Index name (e.g., `Patient_lastUpdated_idx`). */
+    name: string;
+    /** Columns included in the index key. */
+    columns: string[];
+    /** Index type. */
+    indexType: 'btree' | 'gin' | 'gist';
+    /** Whether this is a unique index. */
+    unique: boolean;
+    /** Partial index WHERE clause (e.g., `'deleted = false'`). */
+    where?: string;
+    /** INCLUDE columns for covering indexes. */
+    include?: string[];
+    /**
+     * Operator class for the index (e.g., `'gin_trgm_ops'` for trigram GIN).
+     * Applied to all columns in the index.
+     */
+    opClass?: string;
+    /**
+     * Functional expression to index instead of a plain column.
+     * When set, `columns` is ignored and this SQL expression is used directly.
+     * Example: `"to_tsvector('simple'::regconfig, family)"`
+     */
+    expression?: string;
+}
+
+/**
+ * Initialize the platform IG — create or upgrade platform resource tables.
+ *
+ * This is the main entry point for bootstrapping platform tables on startup.
+ * Uses IGPersistenceManager for checksum-based change detection.
+ *
+ * @param adapter - StorageAdapter (SQLite or PostgreSQL).
+ * @returns IGInitResult with action taken (new/upgrade/consistent).
+ */
+export declare function initializePlatformIG(adapter: StorageAdapter): Promise<IGInitResult>;
+
+declare interface InstalledPackage {
+    /** Package name (e.g., "hl7.fhir.r4.core"). */
+    name: string;
+    /** Package version (e.g., "4.0.1"). */
+    version: string;
+    /** Content checksum for change detection. */
+    checksum: string;
+    /** Serialized ResourceTableSet[] JSON for SchemaDiff. */
+    schemaSnapshot: string | null;
+    /** When this package was installed/updated. */
+    installedAt: string;
+    /** Package status: active or superseded. */
+    status: PackageStatus;
+}
+
+/**
+ * Loaded package metadata.
+ */
+declare interface LoadedPackageDef {
+    name: string;
+    version: string;
+    loadedAt?: string;
+    resourceCount?: number;
+}
+
+/**
+ * A row to be inserted into one of the 4 global lookup tables.
+ */
+export declare interface LookupTableRow {
+    /** Which global table: HumanName, Address, ContactPoint, or Identifier. */
+    table: LookupTableType;
+    /** Column name → value map for the lookup table row. */
+    values: Record<string, unknown>;
+}
+
+/**
+ * @deprecated Use GlobalLookupTableSchema instead. Kept for backward compatibility.
+ */
+declare interface LookupTableSchema {
+    tableName: string;
+    resourceType: string;
+    searchParamCode: string;
+    columns: ColumnSchema[];
+    indexes: IndexSchema[];
+    compositePrimaryKey: string[];
+}
+
+/**
+ * The 4 global lookup table types, matching Medplum's production design.
+ *
+ * Each is a shared table across ALL resource types, storing decomposed
+ * complex FHIR types for precise search via JOINs.
+ */
+declare type LookupTableType = 'HumanName' | 'Address' | 'ContactPoint' | 'Identifier';
+
+export declare class LookupTableWriter {
+    private readonly adapter;
+    private initialized;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Create all 4 lookup tables + indexes if they don't exist.
+     */
+    ensureTables(): Promise<void>;
+    /**
+     * Write lookup table rows for a resource (replace strategy).
+     *
+     * 1. Deletes all existing rows for the resourceId across all 4 tables
+     * 2. Inserts new rows grouped by table type
+     *
+     * @param resourceId - The resource ID to index.
+     * @param rows - LookupTableRow[] from `buildLookupTableRows()`.
+     */
+    writeRows(resourceId: string, rows: LookupTableRow[]): Promise<void>;
+    /**
+     * Delete all lookup table rows for a given resourceId.
+     */
+    deleteRows(resourceId: string): Promise<void>;
+    /**
+     * Get all lookup rows for a given resourceId and table type.
+     */
+    getRows<T = Record<string, unknown>>(table: string, resourceId: string): Promise<T[]>;
+}
+
+/**
+ * Schema for a FHIR resource main table (current version).
+ *
+ * Contains fixed columns (id, content, lastUpdated, etc.) plus
+ * dynamic search columns derived from SearchParameters.
+ */
+export declare interface MainTableSchema {
+    /** Table name (e.g., `'Patient'`). */
+    tableName: string;
+    /** FHIR resource type name. */
+    resourceType: string;
+    /** All columns (fixed + search). */
+    columns: ColumnSchema[];
+    /** All indexes (fixed + search). */
+    indexes: IndexSchema[];
+    /** Table constraints (PK, unique, check). */
+    constraints: ConstraintSchema[];
+}
+
+/**
+ * v2: Map rows with deleted:number to PersistedResource[].
+ */
+export declare function mapRowsToResources(rows: SearchRowV2[]): PersistedResource[];
+
+/**
+ * Maximum allowed page size.
+ */
+export declare const MAX_SEARCH_COUNT = 1000;
+
+declare interface MigrationRecordV2 {
+    version: number;
+    description: string;
+    type: string;
+    applied_at: string;
+}
+
+export declare interface MigrationResultV2 {
+    action: 'up' | 'down' | 'none';
+    applied: number[];
+    currentVersion: number;
+    errors: Array<{
+        version: number;
+        error: string;
+    }>;
+}
+
+/**
+ * v2: Manages schema migrations using StorageAdapter (SQLite / PG).
+ *
+ * Key differences from v1:
+ * - Uses `StorageAdapter` instead of `DatabaseClient`
+ * - `?` placeholders instead of `$1`
+ * - Supports `type` field: 'ig' | 'file'
+ * - IG migrations are forward-only (no down/revert)
+ * - Tracking table uses `datetime('now')` for SQLite
+ */
+export declare class MigrationRunnerV2 {
+    private readonly adapter;
+    private readonly migrations;
+    constructor(adapter: StorageAdapter, migrations?: MigrationV2[]);
+    /**
+     * Ensure the tracking table exists.
+     */
+    ensureTrackingTable(): Promise<void>;
+    /**
+     * Apply all pending migrations (or up to a target version).
+     */
+    up(targetVersion?: number): Promise<MigrationResultV2>;
+    /**
+     * Revert migrations down to a target version.
+     * IG migrations (type='ig') cannot be reverted — they are skipped.
+     */
+    down(targetVersion?: number): Promise<MigrationResultV2>;
+    /**
+     * Get the current migration status.
+     */
+    status(): Promise<MigrationStatusV2>;
+    /**
+     * Get all applied migration records.
+     */
+    getRecords(): Promise<MigrationRecordV2[]>;
+    /**
+     * Apply an IG-generated migration directly.
+     *
+     * Assigns the next available version number automatically.
+     * This is the primary entry point for IGPersistenceManager.
+     */
+    applyIGMigration(generated: GeneratedMigration): Promise<MigrationResultV2>;
+    private getAppliedVersions;
+    private applyMigration;
+    private revertMigration;
+    private maxApplied;
+}
+
+declare interface MigrationStatusV2 {
+    currentVersion: number;
+    appliedVersions: number[];
+    availableVersions: number[];
+    pendingVersions: number[];
+}
+
+/**
+ * v2 migration types — adds `type` field for IG vs file distinction.
+ */
+export declare interface MigrationV2 {
+    /** Unique version number. Must be positive integer. */
+    version: number;
+    /** Human-readable description. */
+    description: string;
+    /** SQL statements to apply this migration. */
+    up: string[];
+    /** SQL statements to revert this migration. Empty for IG migrations (forward-only). */
+    down: string[];
+    /** Migration source type: 'ig' for IG-driven, 'file' for manual file-based. */
+    type: 'ig' | 'file';
+}
+
+/**
+ * Repository Types & Interfaces
+ *
+ * Defines the contract for FHIR resource persistence operations.
+ * All implementations must support transactional CRUD with versioning.
+ *
+ * Design decisions (from WF-E2E-001 Medplum analysis):
+ * - `id` and `versionId` are UUIDs, generated app-side
+ * - Every write produces a new history entry (new version snapshot)
+ * - Soft delete: `deleted=true`, `content=''`, `__version=-1`
+ * - Optimistic locking via `ifMatch` (versionId comparison)
+ *
+ * @module fhir-persistence/repo
+ */
+/**
+ * Operation context — flows through all CRUD/Search operations.
+ *
+ * S1 (Phase B): Only `project` is used — multi-tenant isolation.
+ * S5 (Phase C): Will extend to use `author`, `accessPolicy`, `superAdmin`.
+ */
+export declare interface OperationContext {
+    /** Current project ID for multi-tenant scoping. */
+    project?: string;
+    /** The actor performing the operation (User/Bot/ClientApplication reference). */
+    author?: string;
+    /** The AccessPolicy ID bound to this operation. */
+    accessPolicy?: string;
+    /** Whether this is a super-admin operation (bypasses project scoping). */
+    superAdmin?: boolean;
+}
+
+export declare class PackageRegistryRepo {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Ensure the packages tracking table exists.
+     */
+    ensureTable(): Promise<void>;
+    /**
+     * Get the active version of a package by name.
+     */
+    getPackage(name: string): Promise<InstalledPackage | undefined>;
+    /**
+     * Get all installed packages (all statuses).
+     */
+    getInstalledPackages(): Promise<InstalledPackage[]>;
+    /**
+     * Get only active packages.
+     */
+    getActivePackages(): Promise<InstalledPackage[]>;
+    /**
+     * Register a package version.
+     *
+     * When a new version is registered for the same package name:
+     * 1. Previous active versions are marked as 'superseded'
+     * 2. The new version is inserted as 'active'
+     * 3. A schema_version record is created with the package_list snapshot
+     */
+    registerPackage(pkg: Omit<InstalledPackage, 'installedAt' | 'status'>, description?: string): Promise<void>;
+    /**
+     * Insert or update a package record (backward-compatible).
+     *
+     * Uses INSERT OR REPLACE (SQLite UPSERT) to handle both new and upgraded packages.
+     */
+    upsertPackage(pkg: Omit<InstalledPackage, 'installedAt' | 'status'>): Promise<void>;
+    /**
+     * Remove all versions of a package.
+     */
+    removePackage(name: string): Promise<void>;
+    /**
+     * Check if a package needs update by comparing checksums.
+     *
+     * Returns:
+     * - 'new' if the package is not installed (no active version)
+     * - 'upgrade' if the checksum differs
+     * - 'consistent' if the checksum matches
+     */
+    checkStatus(name: string, checksum: string): Promise<'new' | 'upgrade' | 'consistent'>;
+    /**
+     * Ensure the schema version table exists.
+     */
+    ensureSchemaVersionTable(): Promise<void>;
+    /**
+     * Record a schema version with the current active package list.
+     */
+    recordSchemaVersion(description: string): Promise<void>;
+    /**
+     * Get all schema version records.
+     */
+    getSchemaVersions(): Promise<SchemaVersionRecord[]>;
+    /**
+     * Get the latest schema version record.
+     */
+    getLatestSchemaVersion(): Promise<SchemaVersionRecord | undefined>;
+}
+
+declare type PackageStatus = 'active' | 'superseded';
+
+/**
+ * Pagination Helpers
+ *
+ * Build pagination URLs for FHIR search Bundle links.
+ * Pure functions — no database dependency.
+ *
+ * FHIR R4 Pagination spec:
+ * - `Bundle.link` with `relation: "self"` — current page URL
+ * - `Bundle.link` with `relation: "next"` — next page URL (if more results)
+ * - Offset-based pagination using `_offset` and `_count`
+ *
+ * @module fhir-persistence/search
+ */
+/**
+ * Context for building pagination links.
+ */
+export declare interface PaginationContext {
+    /** Base URL of the FHIR server (e.g., `"http://localhost:3000/fhir/R4"`). */
+    baseUrl: string;
+    /** The FHIR resource type being searched. */
+    resourceType: string;
+    /** Original query parameters (excluding `_offset`). */
+    queryParams: Record<string, string | string[]>;
+    /** Page size (`_count`). */
+    count: number;
+    /** Current offset (`_offset`). */
+    offset: number;
+    /** Number of results returned on the current page. */
+    resultCount: number;
+}
+
+/**
+ * A single parsed search parameter from a FHIR search URL.
+ *
+ * Examples:
+ * - `?gender=male`           → `{ code: "gender", values: ["male"] }`
+ * - `?gender=male,female`    → `{ code: "gender", values: ["male", "female"] }`
+ * - `?birthdate=ge1990-01-01`→ `{ code: "birthdate", prefix: "ge", values: ["1990-01-01"] }`
+ * - `?name:exact=Smith`      → `{ code: "name", modifier: "exact", values: ["Smith"] }`
+ */
+export declare interface ParsedSearchParam {
+    /** The search parameter code (e.g., `"gender"`, `"birthdate"`). */
+    code: string;
+    /** Optional modifier (e.g., `"exact"`, `"contains"`, `"missing"`). */
+    modifier?: SearchModifier;
+    /** Optional prefix for number/date/quantity (e.g., `"ge"`, `"lt"`). */
+    prefix?: SearchPrefix;
+    /**
+     * The search values (OR semantics within a single parameter).
+     * Comma-separated values in the URL are split into this array.
+     */
+    values: string[];
+    /**
+     * Chained search info (single-level).
+     *
+     * Present when the param uses chained syntax:
+     * `subject:Patient.name=Smith` →
+     *   code = "subject", chain = { targetType: "Patient", targetParam: "name" }
+     */
+    chain?: ChainedSearchTarget;
+}
+
+/**
+ * Parse a query parameter key into code, optional modifier, and optional chain.
+ *
+ * Examples:
+ * - `"gender"` → `{ code: "gender" }`
+ * - `"name:exact"` → `{ code: "name", modifier: "exact" }`
+ * - `"code:not"` → `{ code: "code", modifier: "not" }`
+ * - `"subject:Patient.name"` → `{ code: "subject", chain: { targetType: "Patient", targetParam: "name" } }`
+ */
+export declare function parseParamKey(key: string): {
+    code: string;
+    modifier?: SearchModifier;
+    chain?: ChainedSearchTarget;
+};
+
+/**
+ * Parse a FHIR search URL query string into a `SearchRequest`.
+ *
+ * @param resourceType - The FHIR resource type being searched.
+ * @param queryParams - The URL query parameters as a key-value record.
+ *   For repeated keys, values should be joined with `&` or passed as arrays.
+ * @param registry - Optional SearchParameterRegistry for parameter validation.
+ *   If provided, unknown parameter codes will be rejected.
+ * @returns A fully parsed SearchRequest.
+ * @throws Error if a parameter code is unknown and registry is provided.
+ */
+export declare function parseSearchRequest(resourceType: string, queryParams: Record<string, string | string[] | undefined>, registry?: SearchParameterRegistry): SearchRequest;
+
+/**
+ * Parse the `_sort` parameter value into `SortRule[]`.
+ *
+ * Examples:
+ * - `"birthdate"` → `[{ code: "birthdate", descending: false }]`
+ * - `"-birthdate"` → `[{ code: "birthdate", descending: true }]`
+ * - `"family,-birthdate"` → two rules
+ */
+export declare function parseSortParam(value: string): SortRule[];
+
+/**
+ * A FHIR resource that has been persisted (id and meta are guaranteed).
+ */
+export declare interface PersistedResource extends FhirResource {
+    id: string;
+    meta: FhirMeta & {
+        versionId: string;
+        lastUpdated: string;
+    };
+}
+
+/**
+ * Plan and optimize a search request.
+ *
+ * @param request - The parsed search request.
+ * @param registry - The SearchParameterRegistry for resolving implementations.
+ * @param options - Optional planner configuration.
+ * @returns A SearchPlan with the optimized request and metadata.
+ */
+export declare function planSearch(request: SearchRequest, registry: SearchParameterRegistry, options?: SearchPlannerOptions): SearchPlan;
+
+export declare const PLATFORM_PACKAGE_NAME = "medxai.core";
+
+export declare const PLATFORM_PACKAGE_VERSION = "1.0.0";
+
+/**
+ * Platform resource types that require special handling.
+ *
+ * These are MedXAI-defined resources (not part of FHIR R4 base spec).
+ * They participate in multi-tenant isolation via `projectId`.
+ */
+export declare const PLATFORM_RESOURCE_TYPES: ReadonlySet<string>;
+
+export declare const PLATFORM_SEARCH_PARAMETERS: SearchParameterResource[];
+
+/**
+ * FHIR search parameter types that support prefixes.
+ */
+export declare const PREFIX_TYPES: ReadonlySet<string>;
+
+/**
+ * Map a FHIR search prefix to a SQL comparison operator.
+ */
+export declare function prefixToOperator(prefix?: SearchPrefix): string;
+
+/**
+ * StorageAdapter — Database Abstraction Interface
+ *
+ * Provides a unified interface for database operations across
+ * SQLite and PostgreSQL. All business logic interacts with
+ * the database exclusively through this interface.
+ *
+ * v2 upgrade: Replaces direct `pg.Pool` usage in v1's `DatabaseClient`.
+ * The existing `DatabaseClient` is preserved for backward compatibility.
+ *
+ * @module fhir-persistence/db
+ */
+/**
+ * A prepared (precompiled) SQL statement for high-frequency operations.
+ *
+ * Prepared statements avoid repeated SQL parsing overhead.
+ * The caller is responsible for calling `finalize()` when done.
+ */
+declare interface PreparedStatement<T = Record<string, unknown>> {
+    /** Execute as a read query, returning all matching rows. */
+    query(params?: unknown[]): T[];
+    /** Execute as a write operation, returning change count. */
+    execute(params?: unknown[]): {
+        changes: number;
+        lastInsertRowid?: number | bigint;
+    };
+    /** Release the prepared statement resources. */
+    finalize(): void;
+}
+
+/**
+ * Resource types that can be managed by project admins (not just super-admins).
+ *
+ * Phase B: informational only — enforcement deferred to Phase C (Auth).
+ */
+export declare const PROJECT_ADMIN_RESOURCE_TYPES: ReadonlySet<string>;
+
+/**
+ * Protected resource types that can only be managed by super-admins or
+ * the system itself. Normal project-scoped operations cannot create/update/delete these.
+ *
+ * Phase B: informational only — enforcement deferred to Phase C (Auth).
+ */
+export declare const PROTECTED_RESOURCE_TYPES: ReadonlySet<string>;
+
+/**
+ * v2: A row for the `{ResourceType}_References` table.
+ * Adds targetType and referenceRaw for more precise reference queries.
+ */
+export declare interface ReferenceRowV2 {
+    /** The source resource ID. */
+    resourceId: string;
+    /** The target resource type (e.g., "Patient"). */
+    targetType: string;
+    /** The target resource ID. */
+    targetId: string;
+    /** The search parameter code (e.g., "subject"). */
+    code: string;
+    /** The original reference string, or null. */
+    referenceRaw: string | null;
+}
+
+/**
+ * Schema for a FHIR resource references table.
+ *
+ * Stores outgoing reference relationships for `_revinclude` support.
+ * Uses a composite primary key.
+ */
+export declare interface ReferencesTableSchema {
+    /** Table name (e.g., `'Patient_References'`). */
+    tableName: string;
+    /** FHIR resource type name. */
+    resourceType: string;
+    /** All columns (fixed). */
+    columns: ColumnSchema[];
+    /** All indexes. */
+    indexes: IndexSchema[];
+    /** Composite primary key column names. */
+    compositePrimaryKey: string[];
+}
+
+/**
+ * Re-index all resource types using StorageAdapter.
+ *
+ * @param adapter - StorageAdapter.
+ * @param resourceTypes - List of resource types to re-index.
+ * @param onProgress - Optional progress callback.
+ * @returns Complete re-index result.
+ */
+export declare function reindexAllV2(adapter: StorageAdapter, resourceTypes: string[], onProgress?: ReindexProgressCallbackV2): Promise<ReindexResultV2>;
+
+declare interface ReindexJob {
+    /** Auto-assigned job ID. */
+    id: number;
+    /** Resource type to reindex (e.g., "Patient"). */
+    resourceType: string;
+    /** Search parameter code that changed (e.g., "birthdate"). */
+    searchParamCode: string;
+    /** New FHIRPath expression. */
+    expression: string;
+    /** Current job status. */
+    status: ReindexJobStatus;
+    /** Cursor for keyset pagination (lastUpdated of last processed resource). */
+    cursor: string | null;
+    /** Number of resources processed so far. */
+    processedCount: number;
+    /** When the job was created. */
+    createdAt: string;
+    /** When the job was last updated. */
+    updatedAt: string;
+}
+
+declare type ReindexJobStatus = 'pending' | 'running' | 'completed' | 'failed';
+
+declare type ReindexProgressCallbackV2 = (info: {
+    resourceType: string;
+    processed: number;
+    total: number;
+}) => void;
+
+/**
+ * Re-index all resources of a given type using StorageAdapter.
+ *
+ * Reads all non-deleted resources in batches via keyset pagination,
+ * parses content JSON, and can be extended with custom row-update logic.
+ *
+ * @param adapter - StorageAdapter (SQLite or PostgreSQL).
+ * @param resourceType - The FHIR resource type to re-index.
+ * @param onProgress - Optional progress callback.
+ * @returns Per-type reindex result.
+ */
+export declare function reindexResourceTypeV2(adapter: StorageAdapter, resourceType: string, onProgress?: ReindexProgressCallbackV2): Promise<{
+    processed: number;
+    updated: number;
+    errors: number;
+}>;
+
+declare interface ReindexResultV2 {
+    totalProcessed: number;
+    totalUpdated: number;
+    totalErrors: number;
+    byType: Record<string, {
+        processed: number;
+        updated: number;
+        errors: number;
+    }>;
+}
+
+export declare class ReindexScheduler {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Ensure the reindex jobs table exists.
+     */
+    ensureTable(): Promise<void>;
+    /**
+     * Schedule reindex jobs from REINDEX deltas.
+     *
+     * @param deltas - REINDEX deltas from SchemaDiff (filtered by caller).
+     * @returns Number of jobs scheduled.
+     */
+    schedule(deltas: SchemaDelta[]): Promise<number>;
+    /**
+     * Get all pending reindex jobs.
+     */
+    getPendingJobs(): Promise<ReindexJob[]>;
+    /**
+     * Get a specific job by ID.
+     */
+    getJob(id: number): Promise<ReindexJob | undefined>;
+    /**
+     * Get all jobs (any status).
+     */
+    getAllJobs(): Promise<ReindexJob[]>;
+    /**
+     * Update job status and cursor.
+     */
+    updateJob(id: number, update: {
+        status?: ReindexJobStatus;
+        cursor?: string;
+        processedCount?: number;
+    }): Promise<void>;
+    /**
+     * Get status summary of all jobs.
+     */
+    getStatus(): Promise<{
+        pending: number;
+        running: number;
+        completed: number;
+        failed: number;
+    }>;
+}
+
+/**
+ * Repository Error Hierarchy
+ *
+ * Maps to standard FHIR/HTTP error semantics:
+ * - 404 Not Found → ResourceNotFoundError
+ * - 410 Gone → ResourceGoneError
+ * - 412 Precondition Failed → ResourceVersionConflictError
+ *
+ * @module fhir-persistence/repo
+ */
+/**
+ * Base class for all repository errors.
+ */
+export declare class RepositoryError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+
+/**
+ * v2 Resource Cache with configurable eviction policy.
+ *
+ * Upgrades v1 with:
+ * - Eviction policy: lru / fifo / ttl-only
+ * - stats.reset() to zero counters
+ * - sweep() to proactively remove expired entries
+ */
+export declare class ResourceCacheV2 {
+    private readonly cache;
+    private readonly maxSize;
+    private readonly ttlMs;
+    private readonly enabled;
+    private readonly evictionPolicy;
+    private _hits;
+    private _misses;
+    private _evictions;
+    constructor(config?: ResourceCacheV2Config);
+    private key;
+    get(resourceType: string, id: string): PersistedResource | undefined;
+    set(resourceType: string, id: string, resource: PersistedResource): void;
+    invalidate(resourceType: string, id: string): void;
+    clear(): void;
+    /**
+     * Proactively remove all expired entries.
+     * @returns Number of entries swept.
+     */
+    sweep(): number;
+    get size(): number;
+    get stats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        hitRate: number;
+        evictions: number;
+    };
+    /**
+     * Reset stats counters without clearing cache entries.
+     */
+    resetStats(): void;
+    get isEnabled(): boolean;
+    get policy(): EvictionPolicy;
+}
+
+/**
+ * v2 configuration for the resource cache.
+ */
+declare interface ResourceCacheV2Config {
+    /** Maximum number of entries. Default: 1000. Ignored for ttl-only policy. */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. Default: 60000 (60s). */
+    ttlMs?: number;
+    /** Whether the cache is enabled. Default: false. */
+    enabled?: boolean;
+    /** Eviction policy. Default: 'lru'. */
+    evictionPolicy?: EvictionPolicy;
+}
+
+/**
+ * Resource has been deleted (HTTP 410 Gone).
+ */
+export declare class ResourceGoneError extends RepositoryError {
+    readonly name = "ResourceGoneError";
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, id: string);
+}
+
+/**
+ * Resource not found (HTTP 404).
+ */
+export declare class ResourceNotFoundError extends RepositoryError {
+    readonly name = "ResourceNotFoundError";
+    readonly resourceType: string;
+    readonly resourceId: string;
+    constructor(resourceType: string, id: string);
+}
+
+/**
+ * FHIR Resource Repository — persistence contract.
+ *
+ * All write operations are transactional (ACID).
+ * All write operations produce a history entry.
+ */
+export declare interface ResourceRepository {
+    /**
+     * Create a new FHIR resource.
+     *
+     * - Generates `id` (UUID) if not provided via `options.assignedId`
+     * - Generates `meta.versionId` (UUID)
+     * - Sets `meta.lastUpdated` to current time
+     * - Writes to main table + history table in a transaction
+     * - If `context.project` is set, injects projectId into the row
+     *
+     * @returns The persisted resource with populated `id` and `meta`.
+     */
+    createResource<T extends FhirResource>(resource: T, options?: CreateResourceOptions, context?: OperationContext): Promise<T & PersistedResource>;
+    /**
+     * Read a resource by type and ID.
+     *
+     * When `context.project` is set, verifies the resource belongs to that project.
+     *
+     * @throws ResourceNotFoundError if the resource does not exist.
+     * @throws ResourceGoneError if the resource has been deleted.
+     */
+    readResource(resourceType: string, id: string, context?: OperationContext): Promise<PersistedResource>;
+    /**
+     * Update an existing resource.
+     *
+     * - The resource must have `id` set.
+     * - Generates new `meta.versionId` (UUID)
+     * - Sets `meta.lastUpdated` to current time
+     * - Writes to main table (UPSERT) + history table in a transaction
+     * - If `options.ifMatch` is set, performs optimistic locking check
+     * - If `context.project` is set, injects projectId into the row
+     *
+     * @throws ResourceNotFoundError if the resource does not exist.
+     * @throws ResourceGoneError if the resource has been deleted.
+     * @throws ResourceVersionConflictError if `ifMatch` does not match.
+     */
+    updateResource<T extends FhirResource>(resource: T, options?: UpdateResourceOptions, context?: OperationContext): Promise<T & PersistedResource>;
+    /**
+     * Soft-delete a resource.
+     *
+     * - Sets `deleted=true`, `content=''`, `__version=-1`
+     * - Writes a delete history entry
+     *
+     * @throws ResourceNotFoundError if the resource does not exist.
+     * @throws ResourceGoneError if already deleted.
+     */
+    deleteResource(resourceType: string, id: string, context?: OperationContext): Promise<void>;
+    /**
+     * Read the version history of a resource (newest first).
+     */
+    readHistory(resourceType: string, id: string, options?: HistoryOptions): Promise<HistoryEntry[]>;
+    /**
+     * Read type-level history (all changes to a resource type, newest first).
+     */
+    readTypeHistory(resourceType: string, options?: HistoryOptions): Promise<HistoryEntry[]>;
+    /**
+     * Read a specific version of a resource.
+     *
+     * @throws ResourceNotFoundError if the version does not exist.
+     */
+    readVersion(resourceType: string, id: string, versionId: string): Promise<PersistedResource>;
+    /**
+     * Search for resources matching the given search request.
+     *
+     * - Executes parameterized SQL built from the search request
+     * - Optionally returns total count when `options.total === 'accurate'`
+     * - If `context.project` is set, adds projectId filter to the query
+     *
+     * @param request - Parsed FHIR search request.
+     * @param options - Search options (e.g., total mode).
+     * @param context - Operation context for project scoping.
+     * @returns Search result with matched resources and optional total.
+     */
+    searchResources(request: SearchRequest, options?: SearchOptions, context?: OperationContext): Promise<SearchResult>;
+}
+
+/**
+ * v1 ResourceRow — preserved for backward compatibility with FhirRepository (PG).
+ * @deprecated Use ResourceRowV2 for new code.
+ */
+declare interface ResourceRow {
+    [key: string]: unknown;
+    id: string;
+    content: string;
+    lastUpdated: string;
+    deleted: boolean;
+    projectId: string;
+    __version: number;
+    _source?: string;
+    _profile?: string[];
+    compartments?: string[];
+}
+
+/**
+ * Complete table set for a single FHIR resource type.
+ *
+ * Contains 3 core tables (main, history, references).
+ * Lookup tables are now global (shared across all resource types)
+ * and stored at the SchemaDefinition level.
+ */
+export declare interface ResourceTableSet {
+    /** FHIR resource type (e.g., `'Patient'`). */
+    resourceType: string;
+    /** Main table (current version + search columns). */
+    main: MainTableSchema;
+    /** History table (all versions). */
+    history: HistoryTableSchema;
+    /** References table (outgoing references). */
+    references: ReferencesTableSchema;
+    /**
+     * v2: Raw SP metadata for SchemaDiff to compare old vs new search params.
+     */
+    searchParams?: SearchParamMeta[];
+    /**
+     * @deprecated Per-resource lookup tables removed. Use SchemaDefinition.globalLookupTables.
+     */
+    lookupTables?: LookupTableSchema[];
+}
+
+/**
+ * Optimistic locking conflict (HTTP 412 Precondition Failed).
+ *
+ * Thrown when `ifMatch` (expected versionId) does not match
+ * the current versionId of the resource.
+ */
+export declare class ResourceVersionConflictError extends RepositoryError {
+    readonly name = "ResourceVersionConflictError";
+    readonly resourceType: string;
+    readonly resourceId: string;
+    readonly expectedVersion: string;
+    readonly actualVersion: string;
+    constructor(resourceType: string, id: string, expectedVersion: string, actualVersion: string);
+}
+
+/**
+ * Bridge interface for fhir-runtime.
+ *
+ * fhir-persistence depends only on this interface, never on
+ * fhir-runtime internal types. Implementations may wrap
+ * a real `FhirRuntimeInstance` or provide test-only approximations.
+ *
+ * ADR-01 §4.1b — structural typing, no `implements` required.
+ */
+declare interface RuntimeProvider {
+    /**
+     * Extract search parameter values from a resource.
+     *
+     * Real implementation uses FHIRPath evaluation via fhir-runtime.
+     * Test implementation uses extractPropertyPath approximation.
+     *
+     * @param resource - The FHIR resource to extract values from.
+     * @param params - SearchParameter definitions to extract.
+     * @returns Map of param code → extracted values.
+     */
+    extractSearchValues(resource: Record<string, unknown>, params: SearchParameterDef[]): Record<string, unknown[]>;
+    /**
+     * Extract all outgoing references from a resource.
+     *
+     * Real implementation uses fhir-runtime's reference extractor
+     * based on StructureDefinition knowledge.
+     * Test implementation scans JSON for `.reference` fields.
+     *
+     * @param resource - The FHIR resource to scan.
+     * @param params - Reference-type SearchParameters (used for code mapping).
+     * @returns Array of extracted references with targetType/targetId.
+     */
+    extractReferences(resource: Record<string, unknown>, params: SearchParameterDef[]): ExtractedReference[];
+    /**
+     * Validate a resource against a profile (optional capability).
+     *
+     * Not all implementations support validation. Check existence before calling.
+     */
+    validate?(resource: Record<string, unknown>, profileUrl?: string): Promise<ValidationResult>;
+}
+
+/**
+ * Schema version constant.
+ *
+ * Tracks the schema migration version (not the resource version).
+ * Incremented when the schema structure changes.
+ * Set to -1 for deleted resources.
+ */
+export declare const SCHEMA_VERSION = 1;
+
+/**
+ * Complete schema definition for all resource types.
+ *
+ * This is the top-level output of the schema generation pipeline.
+ */
+export declare interface SchemaDefinition {
+    /** Schema version identifier (e.g., `'fhir-r4-v4.0.1'`). */
+    version: string;
+    /** ISO timestamp of when the schema was generated. */
+    generatedAt: string;
+    /** Table sets for all resource types. */
+    tableSets: ResourceTableSet[];
+    /**
+     * Global lookup tables shared across all resource types.
+     * Matches Medplum's production design: HumanName, Address, ContactPoint, Identifier.
+     */
+    globalLookupTables: GlobalLookupTableSchema[];
+}
+
+export declare interface SchemaDelta {
+    /** The type of schema change. */
+    kind: DeltaKind;
+    /** The resource type affected (e.g., "Patient"). */
+    resourceType: string;
+    /** The table name affected (e.g., "Patient", "Patient_History"). */
+    tableName: string;
+    /** Column details (for ADD_COLUMN, DROP_COLUMN, ALTER_COLUMN). */
+    column?: ColumnSchema;
+    /** Previous column details (for ALTER_COLUMN). */
+    oldColumn?: ColumnSchema;
+    /** Index details (for ADD_INDEX, DROP_INDEX). */
+    index?: IndexSchema;
+    /** Search parameter details (for REINDEX). */
+    searchParam?: SearchParamMeta;
+    /** The full ResourceTableSet (for ADD_TABLE). */
+    tableSet?: ResourceTableSet;
+}
+
+declare interface SchemaVersionRecord {
+    /** Auto-incrementing version number. */
+    version: number;
+    /** JSON snapshot of active package names+versions at this schema version. */
+    packageList: string;
+    /** Description of the schema change. */
+    description: string;
+    /** When this schema version was applied. */
+    appliedAt: string;
+}
+
+/**
+ * All valid search prefixes.
+ */
+export declare const SEARCH_PREFIXES: ReadonlySet<string>;
+
+/**
+ * A FHIR R4 Bundle of type `searchset`.
+ */
+export declare interface SearchBundle {
+    resourceType: 'Bundle';
+    id: string;
+    type: 'searchset';
+    total?: number;
+    link?: BundleLink[];
+    entry?: SearchBundleEntry[];
+}
+
+/**
+ * A single entry in a searchset Bundle.
+ */
+export declare interface SearchBundleEntry {
+    fullUrl?: string;
+    resource: Record<string, unknown>;
+    search: {
+        mode: 'match' | 'include' | 'outcome';
+    };
+}
+
+/**
+ * Column type for search parameter columns.
+ */
+export declare type SearchColumnType = SqlColumnType;
+
+/**
+ * Search column values to merge into the main table row.
+ */
+export declare interface SearchColumnValues {
+    [columnName: string]: unknown;
+}
+
+/**
+ * Search Logger — Execution Time Observability
+ *
+ * Wraps search operations with timing and result counting.
+ * Provides slow query detection, recent log buffer, and stats.
+ *
+ * @module fhir-persistence/observability
+ */
+declare interface SearchLogEntry {
+    /** Resource type being searched. */
+    resourceType: string;
+    /** Number of search parameters used. */
+    paramCount: number;
+    /** Number of results returned. */
+    resultCount: number;
+    /** Execution duration in milliseconds. */
+    durationMs: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Whether this was flagged as slow. */
+    slow: boolean;
+}
+
+export declare class SearchLogger {
+    private readonly entries;
+    private readonly enabled;
+    private readonly slowThresholdMs;
+    private readonly maxEntries;
+    private readonly onLog?;
+    constructor(config?: SearchLoggerConfig);
+    /**
+     * Log a completed search operation.
+     */
+    log(resourceType: string, paramCount: number, resultCount: number, durationMs: number): void;
+    /**
+     * Get the most recent N log entries.
+     */
+    getRecentLogs(count?: number): SearchLogEntry[];
+    /**
+     * Get entries flagged as slow queries.
+     */
+    getSlowQueries(): SearchLogEntry[];
+    /**
+     * Get aggregate statistics.
+     */
+    getStats(): SearchStats;
+    /**
+     * Clear all log entries.
+     */
+    clearLogs(): void;
+    get isEnabled(): boolean;
+}
+
+declare interface SearchLoggerConfig {
+    /** Whether logging is enabled. Default: true. */
+    enabled?: boolean;
+    /** Slow query threshold in milliseconds. Default: 1000. */
+    slowThresholdMs?: number;
+    /** Maximum number of log entries to retain. Default: 100. */
+    maxEntries?: number;
+    /** Custom log handler. Called for every search log entry. */
+    onLog?: (entry: SearchLogEntry) => void;
+}
+
+/**
+ * FHIR search modifier.
+ *
+ * See: https://hl7.org/fhir/R4/search.html#modifiers
+ */
+export declare type SearchModifier = 'exact' | 'contains' | 'missing' | 'not' | 'text' | 'above' | 'below' | 'in' | 'not-in' | 'of-type';
+
+/**
+ * Options for search execution.
+ */
+export declare interface SearchOptions {
+    /** Whether to include total count. */
+    total?: 'none' | 'estimate' | 'accurate';
+}
+
+/**
+ * Options for search execution.
+ */
+declare interface SearchOptions_2 {
+    /** Whether to include total count. */
+    total?: 'none' | 'estimate' | 'accurate';
+}
+
+/**
+ * Shape of a FHIR Bundle containing SearchParameter entries.
+ */
+export declare interface SearchParameterBundle {
+    resourceType: 'Bundle';
+    entry?: Array<{
+        resource?: SearchParameterResource;
+    }>;
+}
+
+/**
+ * Minimal SearchParameter shape used by fhir-persistence.
+ */
+declare interface SearchParameterDef {
+    resourceType: 'SearchParameter';
+    url?: string;
+    name?: string;
+    code: string;
+    type: 'number' | 'date' | 'string' | 'token' | 'reference' | 'composite' | 'quantity' | 'uri' | 'special';
+    base: string[];
+    expression?: string;
+    target?: string[];
+    [key: string]: unknown;
+}
+
+/**
+ * Resolved implementation details for a single search parameter
+ * on a specific resource type.
+ */
+export declare interface SearchParameterImpl {
+    /** SearchParameter.code (e.g., `'birthdate'`). */
+    code: string;
+    /** FHIR search parameter type. */
+    type: SearchParamType;
+    /** Resource types this parameter applies to. */
+    resourceTypes: string[];
+    /** FHIRPath expression for value extraction. */
+    expression: string;
+    /** Physical storage strategy. */
+    strategy: SearchStrategy;
+    /** Column name in the main table (for `column` strategy). */
+    columnName: string;
+    /** PostgreSQL column type (for `column` strategy). */
+    columnType: SearchColumnType;
+    /** Whether the column stores an array of values. */
+    array: boolean;
+}
+
+/**
+ * Indexes SearchParameter definitions by resource type.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const registry = new SearchParameterRegistry();
+ * const bundle = JSON.parse(fs.readFileSync('search-parameters.json', 'utf8'));
+ * registry.indexBundle(bundle);
+ *
+ * const patientParams = registry.getForResource('Patient');
+ * ```
+ */
+export declare class SearchParameterRegistry {
+    /**
+     * Map from resource type → Map from param code → SearchParameterImpl.
+     */
+    private readonly byResource;
+    /**
+     * Total number of indexed implementations (across all resource types).
+     */
+    private _totalCount;
+    /**
+     * Number of skipped parameters (composite, special, ignored).
+     */
+    private _skippedCount;
+    /**
+     * Index all SearchParameter entries from a FHIR Bundle.
+     *
+     * Skips entries that are:
+     * - Not a SearchParameter resource
+     * - Of type `composite` or `special`
+     * - In the ignored list (`_id`, `_lastUpdated`, etc.)
+     *
+     * @returns Stats about the indexing operation.
+     */
+    indexBundle(bundle: SearchParameterBundle): {
+        indexed: number;
+        skipped: number;
+    };
+    /**
+     * Index a single SearchParameterImpl directly.
+     *
+     * Useful for adding platform-specific or custom search parameters.
+     */
+    indexImpl(resourceType: string, impl: SearchParameterImpl): void;
+    /**
+     * Get all search parameter implementations for a resource type.
+     *
+     * @returns Array of SearchParameterImpl, sorted by code for deterministic output.
+     */
+    getForResource(resourceType: string): SearchParameterImpl[];
+    /**
+     * Get a specific search parameter implementation for a resource type.
+     */
+    getImpl(resourceType: string, code: string): SearchParameterImpl | undefined;
+    /**
+     * Check if a resource type has any indexed search parameters.
+     */
+    hasResource(resourceType: string): boolean;
+    /**
+     * Get all resource types that have indexed search parameters.
+     */
+    getResourceTypes(): string[];
+    /**
+     * Get the total number of indexed implementations.
+     */
+    get totalCount(): number;
+    /**
+     * Get the number of skipped parameters.
+     */
+    get skippedCount(): number;
+    /**
+     * Get the number of resource types with indexed parameters.
+     */
+    get resourceTypeCount(): number;
+    /**
+     * Remove all indexed parameters.
+     */
+    clear(): void;
+    /**
+     * Build a SearchParameterImpl from a raw SearchParameter resource.
+     */
+    private buildImpl;
+}
+
+/**
+ * Raw FHIR SearchParameter shape (subset of fields we need).
+ */
+export declare interface SearchParameterResource {
+    resourceType: 'SearchParameter';
+    code: string;
+    type: SearchParamType;
+    base: string[];
+    expression?: string;
+    url?: string;
+    name?: string;
+    target?: string[];
+}
+
+/**
+ * Metadata for a search parameter, preserved for SchemaDiff.
+ */
+declare interface SearchParamMeta {
+    code: string;
+    type: string;
+    expression: string;
+}
+
+/**
+ * FHIR SearchParameter type codes.
+ */
+export declare type SearchParamType = 'number' | 'date' | 'string' | 'token' | 'reference' | 'composite' | 'quantity' | 'uri' | 'special';
+
+/**
+ * Search plan produced by the planner.
+ */
+export declare interface SearchPlan {
+    /** The optimized search request (params reordered). */
+    request: SearchRequest;
+    /** Whether two-phase SQL is recommended for this query. */
+    useTwoPhase: boolean;
+    /** Whether any chained search params are present. */
+    hasChainedSearch: boolean;
+    /** Estimated selectivity: 'high' (few results), 'medium', 'low' (many results). */
+    estimatedSelectivity: 'high' | 'medium' | 'low';
+    /** Warnings produced during planning (e.g., deep chain rejected). */
+    warnings: string[];
+}
+
+/**
+ * Options for the search planner.
+ */
+export declare interface SearchPlannerOptions {
+    /** Maximum allowed chain depth (default: 1, i.e., single-level chain). */
+    maxChainDepth?: number;
+    /** Row count threshold above which two-phase SQL is recommended. Default: 10000. */
+    twoPhaseThreshold?: number;
+    /** Estimated table row count (from stats or hint). Default: 0 (unknown). */
+    estimatedRowCount?: number;
+}
+
+/**
+ * Search Types
+ *
+ * Defines the data structures for FHIR search request parsing
+ * and SQL WHERE clause generation.
+ *
+ * ## FHIR Search Semantics
+ *
+ * - Multiple values for the same parameter → OR (comma-separated)
+ * - Multiple different parameters → AND (separate query params)
+ * - Prefixes (eq, ne, lt, gt, le, ge) → comparison operators
+ * - Modifiers (:exact, :contains, :missing, :not) → behavior modifiers
+ *
+ * Reference: https://hl7.org/fhir/R4/search.html
+ *
+ * @module fhir-persistence/search
+ */
+/**
+ * FHIR search prefix for number, date, and quantity parameters.
+ *
+ * See: https://hl7.org/fhir/R4/search.html#prefix
+ */
+export declare type SearchPrefix = 'eq' | 'ne' | 'lt' | 'gt' | 'le' | 'ge' | 'sa' | 'eb' | 'ap';
+
+/**
+ * A fully parsed FHIR search request.
+ *
+ * Produced by `parseSearchRequest()` from a URL query string.
+ * Consumed by `buildSearchSQL()` to generate a SQL query.
+ */
+export declare interface SearchRequest {
+    /** The FHIR resource type to search. */
+    resourceType: string;
+    /** Parsed search parameters (AND semantics between parameters). */
+    params: ParsedSearchParam[];
+    /**
+     * Maximum number of results to return.
+     * Corresponds to `_count`. Default: 20.
+     */
+    count?: number;
+    /**
+     * Offset for pagination.
+     * Corresponds to `_offset`.
+     */
+    offset?: number;
+    /**
+     * Sort rules.
+     * Corresponds to `_sort`.
+     */
+    sort?: SortRule[];
+    /**
+     * Total count mode.
+     * Corresponds to `_total`.
+     */
+    total?: 'none' | 'estimate' | 'accurate';
+    /**
+     * Resources to include (forward references).
+     * Corresponds to `_include`.
+     */
+    include?: IncludeTarget[];
+    /**
+     * Resources to reverse-include (reverse references).
+     * Corresponds to `_revinclude`.
+     */
+    revinclude?: IncludeTarget[];
+    /**
+     * Compartment filter for compartment search.
+     * Set when the URL is `/:compartmentType/:compartmentId/:resourceType`.
+     *
+     * Example: `GET /Patient/123/Observation` →
+     *   `{ resourceType: "Patient", id: "123" }`
+     */
+    compartment?: {
+        resourceType: string;
+        id: string;
+    };
+    /**
+     * Project ID for multi-tenant scoping.
+     * When set, search results are restricted to resources with matching `projectId`.
+     *
+     * Injected by the server layer from OperationContext.project.
+     */
+    project?: string;
+}
+
+/**
+ * Result of a search execution.
+ */
+export declare interface SearchResult {
+    /** Matched resources. */
+    resources: PersistedResource[];
+    /** Included resources from _include/_revinclude (search.mode = 'include'). */
+    included?: PersistedResource[];
+    /** Total count (only when `total=accurate`). */
+    total?: number;
+}
+
+/**
+ * Result of a search execution.
+ */
+declare interface SearchResult_2 {
+    /** Matched resources. */
+    resources: PersistedResource[];
+    /** Included resources from _include/_revinclude (search.mode = 'include'). */
+    included?: PersistedResource[];
+    /** Total count (only when `total=accurate`). */
+    total?: number;
+}
+
+/**
+ * v2: Raw row shape returned by search SQL.
+ * Uses deleted: number (0/1) instead of boolean.
+ */
+declare interface SearchRowV2 {
+    id: string;
+    versionId: string;
+    content: string;
+    deleted: number;
+    lastUpdated: string;
+    [key: string]: unknown;
+}
+
+/**
+ * A complete search SQL query with parameterized values.
+ *
+ * Produced by `buildSearchSQL()`.
+ */
+export declare interface SearchSQL {
+    /** The full SQL query string. */
+    sql: string;
+    /** The parameter values for the query. */
+    values: unknown[];
+}
+
+declare interface SearchStats {
+    /** Total number of logged searches. */
+    totalSearches: number;
+    /** Average duration in ms. */
+    avgDurationMs: number;
+    /** Maximum duration in ms. */
+    maxDurationMs: number;
+    /** Minimum duration in ms. */
+    minDurationMs: number;
+    /** Number of slow queries. */
+    slowCount: number;
+}
+
+/**
+ * Physical storage strategy for a search parameter.
+ *
+ * - `column` — single column in the main table
+ * - `token-column` — three columns (UUID[], TEXT[], TEXT) for token search
+ * - `lookup-table` — separate lookup table; only a sort column in main table
+ */
+export declare type SearchStrategy = 'column' | 'token-column' | 'lookup-table';
+
+/**
+ * A single sort rule from the `_sort` parameter.
+ *
+ * Examples:
+ * - `_sort=birthdate`  → `{ code: "birthdate", descending: false }`
+ * - `_sort=-birthdate` → `{ code: "birthdate", descending: true }`
+ */
+export declare interface SortRule {
+    /** The search parameter code to sort by. */
+    code: string;
+    /** Whether to sort in descending order. */
+    descending: boolean;
+}
+
+/**
+ * Split a search value string on commas (OR semantics).
+ *
+ * Escaped commas (`\,`) are preserved as literal commas.
+ *
+ * Examples:
+ * - `"male"` → `["male"]`
+ * - `"male,female"` → `["male", "female"]`
+ * - `"a\\,b"` → `["a,b"]`
+ */
+export declare function splitSearchValues(value: string): string[];
+
+/**
+ * Table Schema — Type Definitions
+ *
+ * Intermediate data model representing PostgreSQL table structure.
+ * These types are the output of `TableSchemaBuilder` and the input
+ * to `DDLGenerator`. They are pure data — no behavior, no DB dependency.
+ *
+ * ## Design
+ *
+ * Each FHIR resource type maps to a `ResourceTableSet` containing
+ * exactly 3 tables:
+ * - **Main table** (`Patient`) — current version + search columns
+ * - **History table** (`Patient_History`) — all versions
+ * - **References table** (`Patient_References`) — outgoing references
+ *
+ * This mirrors Medplum's 3-table-per-resource strategy (WF-MIG-002).
+ *
+ * @module fhir-persistence/schema
+ */
+/**
+ * SQL column types used in FHIR resource tables.
+ *
+ * v2: Removed UUID / UUID[]. Token columns now use TEXT / TEXT[].
+ * PostgreSQL-specific types (TIMESTAMPTZ, TEXT[]) are still here
+ * for PG DDL generation. SQLite adapter maps them to TEXT.
+ */
+export declare type SqlColumnType = 'TEXT' | 'TEXT[]' | 'BOOLEAN' | 'INTEGER' | 'BIGINT' | 'TIMESTAMPTZ' | 'TIMESTAMPTZ[]' | 'DATE' | 'DATE[]' | 'NUMERIC' | 'DOUBLE PRECISION' | 'DOUBLE PRECISION[]' | 'REAL';
+
+export declare class SQLiteAdapter implements StorageAdapter {
+    private readonly data?;
+    private db;
+    private initPromise;
+    /**
+     * @param path - Database file path, or ':memory:' for in-memory database.
+     * @param data - Optional Uint8Array of an existing database file to load.
+     */
+    constructor(_path?: string, data?: Uint8Array | undefined);
+    private initialize;
+    private getDb;
+    execute(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+    }>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    queryStream<T = Record<string, unknown>>(sql: string, params?: unknown[]): AsyncIterable<T>;
+    prepare<T = Record<string, unknown>>(sql: string): PreparedStatement<T>;
+    transaction<R>(fn: (tx: TransactionContext) => R | Promise<R>): Promise<R>;
+    close(): Promise<void>;
+    /**
+     * Export the database as a Uint8Array (for file persistence).
+     */
+    export(): Promise<Uint8Array>;
+}
+
+/**
+ * Unified database access interface for SQLite and PostgreSQL.
+ *
+ * All methods are async to support both synchronous (SQLite via sql.js)
+ * and asynchronous (PostgreSQL via pg) database drivers.
+ *
+ * ## Transaction Semantics
+ * - SQLite: `BEGIN IMMEDIATE ... COMMIT / ROLLBACK`
+ * - PostgreSQL: `BEGIN ... COMMIT / ROLLBACK` with `SELECT FOR UPDATE`
+ */
+export declare interface StorageAdapter {
+    /** Execute a write operation (INSERT / UPDATE / DELETE / DDL). */
+    execute(sql: string, params?: unknown[]): Promise<{
+        changes: number;
+    }>;
+    /** Execute a read query, returning all matching rows. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Execute a read query, returning the first row or undefined. */
+    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T | undefined>;
+    /** Stream rows for large result sets (avoids full memory load). */
+    queryStream<T = Record<string, unknown>>(sql: string, params?: unknown[]): AsyncIterable<T>;
+    /** Prepare a SQL statement for repeated execution. */
+    prepare<T = Record<string, unknown>>(sql: string): PreparedStatement<T>;
+    /**
+     * Execute a function within a single database transaction.
+     *
+     * - On success (fn returns normally): COMMIT
+     * - On failure (fn throws): ROLLBACK and re-throw
+     */
+    transaction<R>(fn: (tx: TransactionContext) => R | Promise<R>): Promise<R>;
+    /** Close the database connection and release resources. */
+    close(): Promise<void>;
+}
+
+declare interface StoredValueSet {
+    /** ValueSet canonical URL (e.g., "http://hl7.org/fhir/ValueSet/observation-codes"). */
+    url: string;
+    /** ValueSet version (e.g., "4.0.1"). */
+    version: string;
+    /** ValueSet name (human-readable). */
+    name: string | null;
+    /** Full ValueSet content as JSON string. */
+    content: string;
+    /** When this record was stored. */
+    storedAt: string;
+}
+
+/**
+ * DefinitionProvider — Bridge Interface for fhir-definition
+ *
+ * Abstracts the `fhir-definition` registry so that `fhir-persistence`
+ * never imports `fhir-definition` types directly. This enables:
+ *
+ * - Testing with in-memory mocks (no IG package loading)
+ * - Swapping fhir-definition versions without touching persistence code
+ * - Structural typing compatibility (duck typing)
+ *
+ * ADR-01 §2.3: DefinitionProvider interface contract.
+ *
+ * @module fhir-persistence/providers
+ */
+/**
+ * Minimal StructureDefinition shape used by fhir-persistence.
+ * Only the fields that fhir-persistence reads are declared.
+ */
+declare interface StructureDefinitionDef {
+    resourceType: 'StructureDefinition';
+    url: string;
+    name?: string;
+    type?: string;
+    kind?: string;
+    snapshot?: {
+        element?: Array<{
+            path?: string;
+            type?: Array<{
+                code?: string;
+            }>;
+            [key: string]: unknown;
+        }>;
+    };
+    [key: string]: unknown;
+}
+
+/**
+ * Indexes CanonicalProfile instances by their `type` field for O(1) lookup.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const registry = new StructureDefinitionRegistry();
+ * const profiles = loadBundleFromFile('profiles-resources.json').profiles;
+ * registry.indexAll(profiles);
+ *
+ * const patient = registry.get('Patient');
+ * const tableTypes = registry.getTableResourceTypes(); // ~140+ types
+ * ```
+ */
+export declare class StructureDefinitionRegistry {
+    private readonly profiles;
+    /**
+     * Index a single CanonicalProfile by its `type` field.
+     *
+     * If a profile with the same type already exists, it is overwritten
+     * (later definitions override earlier ones, matching BundleLoader
+     * merge semantics).
+     */
+    index(profile: CanonicalProfile): void;
+    /**
+     * Index multiple CanonicalProfiles.
+     *
+     * Profiles are indexed in order; later entries override earlier
+     * ones with the same type.
+     */
+    indexAll(profiles: readonly CanonicalProfile[]): void;
+    /**
+     * Get a profile by resource type name.
+     *
+     * @param resourceType - The FHIR resource type (e.g., `'Patient'`).
+     * @returns The CanonicalProfile, or `undefined` if not indexed.
+     */
+    get(resourceType: string): CanonicalProfile | undefined;
+    /**
+     * Check if a resource type is indexed.
+     */
+    has(resourceType: string): boolean;
+    /**
+     * Get all resource types that should have database tables.
+     *
+     * Returns types where `kind === 'resource'` AND `abstract === false`.
+     * This excludes:
+     * - Abstract types (Resource, DomainResource)
+     * - Complex types (HumanName, Address)
+     * - Primitive types (string, boolean)
+     * - Logical models
+     *
+     * Results are sorted alphabetically for deterministic output.
+     */
+    getTableResourceTypes(): string[];
+    /**
+     * Get all indexed type names (regardless of kind or abstract).
+     */
+    getAllTypes(): string[];
+    /**
+     * Get the number of indexed profiles.
+     */
+    get size(): number;
+    /**
+     * Remove all indexed profiles.
+     */
+    clear(): void;
+}
+
+declare interface TerminologyCode {
+    /** Code system URI (e.g., "http://loinc.org"). */
+    system: string;
+    /** Code value (e.g., "8480-6"). */
+    code: string;
+    /** Human-readable display text. */
+    display: string;
+}
+
+export declare class TerminologyCodeRepo {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Ensure the terminology_codes table and indexes exist.
+     */
+    ensureTable(): Promise<void>;
+    /**
+     * Batch insert codes. Duplicates are silently ignored (INSERT OR IGNORE).
+     *
+     * @param codes - Array of codes to insert.
+     * @returns Number of codes actually inserted (excluding duplicates).
+     */
+    batchInsert(codes: TerminologyCode[]): Promise<number>;
+    /**
+     * Lookup display text for a specific (system, code) pair.
+     *
+     * @returns Display text, or undefined if not found.
+     */
+    lookup(system: string, code: string): Promise<string | undefined>;
+    /**
+     * Lookup all codes matching a code value (any system).
+     * Useful for code-only search without specifying system.
+     *
+     * @returns Array of matching TerminologyCode entries.
+     */
+    lookupByCode(code: string): Promise<TerminologyCode[]>;
+    /**
+     * Get the total number of codes in the table.
+     */
+    getCodeCount(): Promise<number>;
+    /**
+     * Remove all codes from the table.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * A restricted adapter interface available inside a transaction callback.
+ *
+ * All operations within a transaction use this context to ensure
+ * they execute on the same database connection/transaction.
+ */
+export declare interface TransactionContext {
+    /** Execute a write operation within the transaction. */
+    execute(sql: string, params?: unknown[]): {
+        changes: number;
+    };
+    /** Execute a read query within the transaction. */
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+    /** Execute a read query returning the first row or undefined. */
+    queryOne<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | undefined;
+}
+
+/**
+ * Result of a two-phase search SQL build.
+ */
+export declare interface TwoPhaseSearchSQL {
+    /** Phase 1: SELECT id with full WHERE + ORDER BY + LIMIT/OFFSET. */
+    phase1: SearchSQL;
+    /** Phase 2: SELECT content WHERE id IN (?,...). Values are id strings from Phase 1 results. */
+    phase2Template: string;
+}
+
+/**
+ * Options for `updateResource()`.
+ */
+export declare interface UpdateResourceOptions {
+    /**
+     * Expected versionId for optimistic locking.
+     * If provided and does not match the current versionId,
+     * the update is rejected with `ResourceVersionConflictError`.
+     *
+     * Corresponds to the HTTP `If-Match` header.
+     */
+    ifMatch?: string;
+}
+
+declare interface UpdateResourceOptions_2 {
+    /** Expected versionId for optimistic locking (If-Match header). */
+    ifMatch?: string;
+}
+
+declare interface UpdateResourceOptions_3 {
+    /** Expected versionId for optimistic locking (If-Match header). */
+    ifMatch?: string;
+}
+
+/**
+ * A single validation issue.
+ */
+declare interface ValidationIssue {
+    severity: 'error' | 'warning' | 'information';
+    message: string;
+    path?: string;
+}
+
+/**
+ * Result of resource validation.
+ */
+declare interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+}
+
+/**
+ * Minimal ValueSet shape used by fhir-persistence.
+ */
+declare interface ValueSetDef {
+    resourceType: 'ValueSet';
+    url: string;
+    name?: string;
+    status?: string;
+    compose?: unknown;
+    expansion?: unknown;
+    [key: string]: unknown;
+}
+
+declare interface ValueSetInput {
+    url: string;
+    version: string;
+    name?: string;
+    content: string;
+}
+
+export declare class ValueSetRepo {
+    private readonly adapter;
+    constructor(adapter: StorageAdapter);
+    /**
+     * Ensure the terminology_valuesets table exists.
+     */
+    ensureTable(): Promise<void>;
+    /**
+     * Insert or update a ValueSet.
+     * If a ValueSet with the same (url, version) exists, it is replaced.
+     */
+    upsert(input: ValueSetInput): Promise<void>;
+    /**
+     * Get a specific ValueSet by url and version.
+     *
+     * @returns The stored ValueSet, or undefined if not found.
+     */
+    getValueSet(url: string, version: string): Promise<StoredValueSet | undefined>;
+    /**
+     * Get all versions of a ValueSet by URL.
+     *
+     * @returns Array of stored ValueSets, ordered by version.
+     */
+    getByUrl(url: string): Promise<StoredValueSet[]>;
+    /**
+     * Get all stored ValueSets.
+     */
+    getAll(): Promise<StoredValueSet[]>;
+    /**
+     * Remove a specific ValueSet by url and version.
+     */
+    remove(url: string, version: string): Promise<void>;
+    /**
+     * Get the total number of stored ValueSets.
+     */
+    getValueSetCount(): Promise<number>;
+    /**
+     * Remove all stored ValueSets.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * A SQL WHERE clause fragment with parameterized values.
+ *
+ * Used by `buildWhereFragment()` to produce composable SQL pieces.
+ */
+export declare interface WhereFragment {
+    /** The SQL expression (e.g., `'"gender" = $1'`). */
+    sql: string;
+    /** The parameter values (e.g., `['male']`). */
+    values: unknown[];
+}
+
+export { }