@fortemi/core 2026.6.4 → 2026.6.6

package/dist/index.d.ts

@@ -131,7 +131,136 @@ declare class TypedEventBus {
  */
 
 type PersistenceMode = 'opfs' | 'idb' | 'memory';
-declare function createPGliteInstance(persistence: PersistenceMode, archiveName?: string): Promise<PGlite>;
+interface CreatePGliteOptions {
+    /**
+     * Restore the instance from a physical data-dir snapshot (issue #187) — schema
+     * + rows + INDEXES in one binary load, with no migration / import / reindex.
+     * The blob comes from PGlite's `dumpDataDir`; see `dumpDbSnapshot`/`restoreDbSnapshot`.
+     * When set, callers MUST NOT run migrations — the restored dir already carries them.
+     */
+    loadDataDir?: Blob | File;
+}
+declare function createPGliteInstance(persistence: PersistenceMode, archiveName?: string, options?: CreatePGliteOptions): Promise<PGlite>;
+
+/**
+ * Physical data-dir snapshot (issue #187).
+ *
+ * A *snapshot* is a binary dump of a populated PGlite data directory — schema +
+ * rows + INDEXES (including the HNSW vector index from migration 0004) — that
+ * restores in a single binary load with NO migration, NO shard import, and NO
+ * client-side HNSW build. It is the fast, pre-indexed, single-version restore
+ * option, complementary to logical Knowledge Shards (which are portable + mergeable
+ * but pay the import + reindex cost on every load).
+ *
+ * Named "snapshot" to stay distinct from:
+ *  - `ArchiveManager` / `archiveName` — a *named persistence store* (idb/opfs namespace).
+ *  - Knowledge Shards — logical, portable, mergeable interchange (`importShard`).
+ *
+ * Safety (the one real risk of the physical format): a Postgres data dir is coupled
+ * to the PGlite/pgvector version and the schema-migration head it was built with.
+ * Every snapshot carries a version stamp (a JSON sidecar); `restoreDbSnapshot`
+ * verifies compatibility BEFORE loading and fails fast (`DbSnapshotVersionError`) on
+ * mismatch, so a host can fall back to a shard import.
+ */
+
+/** Snapshot meta envelope schema. */
+declare const DB_SNAPSHOT_SCHEMA_VERSION: "fortemi.db-snapshot.v1";
+/**
+ * PGlite version this build of @fortemi/core bundles and can safely restore a
+ * snapshot from. Kept in sync with the `@electric-sql/pglite` dependency; a unit
+ * test asserts it matches package.json so it can't silently drift.
+ */
+declare const SUPPORTED_PGLITE_VERSION = "0.4.1";
+/** Schema-migration head this build expects a restored snapshot to carry. */
+declare const CURRENT_MIGRATION_HEAD: number;
+type DbSnapshotCompression = 'none' | 'gzip' | 'auto';
+interface DbSnapshotMeta {
+    schema_version: typeof DB_SNAPSHOT_SCHEMA_VERSION;
+    /** PGlite version the data dir was dumped from (data-dir format coupling). */
+    pglite_version: string;
+    /** pgvector extension version at dump time (advisory). */
+    pgvector_version: string | null;
+    /** Max applied migration version at dump time (schema coupling). */
+    migration_head: number;
+    /** ISO-8601 dump time. */
+    created_at: string;
+    /** @fortemi/core version that produced the snapshot (diagnostic only). */
+    fortemi_version?: string;
+}
+interface DbSnapshot {
+    /** The PGlite data-dir dump (gzip by default). Serve as a static asset. */
+    data: Blob | File;
+    /** Version stamp — serve alongside `data` as a `<name>.meta.json` sidecar. */
+    meta: DbSnapshotMeta;
+}
+/** Minimal shape `dumpDbSnapshot` needs — PGlite satisfies it structurally. */
+interface DumpableDb {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    dumpDataDir(compression?: DbSnapshotCompression): Promise<Blob | File>;
+}
+interface DumpDbSnapshotOptions {
+    /** Defaults to 'gzip'. */
+    compression?: DbSnapshotCompression;
+    /** Recorded in meta for diagnostics. */
+    fortemiVersion?: string;
+    /** Override the timestamp (tests / reproducible builds). */
+    createdAt?: string;
+}
+/**
+ * Dump a populated PGlite into a versioned snapshot. Build-time (Node), after the
+ * corpus is loaded and the HNSW index has been built once.
+ *
+ * Returns `{ data, meta }`: write `data` to e.g. `corpus.pgdata` and `meta` to
+ * `corpus.pgdata.meta.json` (the sidecar `restoreDbSnapshot(url)` looks for).
+ */
+declare function dumpDbSnapshot(db: DumpableDb, options?: DumpDbSnapshotOptions): Promise<DbSnapshot>;
+interface DbSnapshotExpectations {
+    migrationHead?: number;
+    pgliteVersion?: string;
+    /** When provided, a differing snapshot pgvector version is a warning, not a failure. */
+    pgvectorVersion?: string | null;
+}
+interface DbSnapshotCompat {
+    compatible: boolean;
+    /** Hard incompatibilities — restore must refuse. */
+    reasons: string[];
+    /** Advisory differences — restore proceeds. */
+    warnings: string[];
+}
+/**
+ * Verify a snapshot's version stamp against what this build supports. Pure —
+ * unit-testable with no PGlite. Hard gates: snapshot schema, migration head
+ * (exact), PGlite major.minor (data-dir format). pgvector is advisory.
+ */
+declare function verifyDbSnapshotMeta(meta: DbSnapshotMeta, expected?: DbSnapshotExpectations): DbSnapshotCompat;
+/** Thrown by `restoreDbSnapshot` when the snapshot is incompatible with this build. */
+declare class DbSnapshotVersionError extends Error {
+    readonly reasons: string[];
+    readonly meta: DbSnapshotMeta;
+    constructor(reasons: string[], meta: DbSnapshotMeta);
+}
+type DbSnapshotSource = DbSnapshot | string | {
+    dataUrl: string;
+    metaUrl?: string;
+};
+interface RestoreDbSnapshotOptions {
+    /** Persistence for the restored instance. Defaults to 'memory' (read-only demos). */
+    persistence?: PersistenceMode;
+    archiveName?: string;
+    /** Verification expectations (defaults to this build's supported values). */
+    expectations?: DbSnapshotExpectations;
+    /** Injectable fetch (tests / non-browser). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Restore a PGlite from a physical snapshot — verify the version stamp first,
+ * then load the data dir with **no migration / import / HNSW build**. Throws
+ * `DbSnapshotVersionError` on incompatibility (catch it to fall back to a shard
+ * import). The returned instance is ready to query; do NOT run migrations on it.
+ */
+declare function restoreDbSnapshot(source: DbSnapshotSource, options?: RestoreDbSnapshotOptions): Promise<PGlite>;
 
 /**
  * Type-safe client for the PGlite Worker.
@@ -248,187 +377,937 @@ declare class PGliteWorkerStorageBackendFactory implements StorageBackendFactory
 }
 
 /**
- * Capability module system (ADR-002).
- * Tracks opt-in WASM module states. No WASM loaded by default (CAP-001).
+ * Shard format types — matches the fortemi server matric-shard specification.
  *
- * State machine (valid transitions):
- *   unloaded  -> loading  (via enable)
- *   loading   -> ready    (via markReady or successful loader)
- *   loading   -> error    (via markError or failed loader)
- *   ready     -> disabled (via disable)
- *   disabled  -> loading  (via enable, re-enable)
- *   error     -> loading  (via enable, retry)
+ * A shard is a gzip-compressed tar archive (.shard) containing serialized
+ * knowledge data with a manifest for integrity verification.
  */
-
-type CapabilityState = 'unloaded' | 'loading' | 'ready' | 'error' | 'disabled';
-type CapabilityName = 'semantic' | 'llm' | 'audio' | 'vision' | 'pdf';
-declare class CapabilityManager {
-    private events;
-    private capabilities;
-    private loaders;
-    private progressMessages;
-    constructor(events: TypedEventBus);
-    /**
-     * Register an async loader for a capability.
-     * Called by enable(); if no loader is registered the capability transitions
-     * directly to ready (useful for capabilities that require no async init).
-     */
-    registerLoader(name: CapabilityName, loader: () => Promise<void>): void;
-    getState(name: CapabilityName): CapabilityState;
-    isReady(name: CapabilityName): boolean;
-    /**
-     * Enable a capability.
-     * Valid from: unloaded, disabled, error (retry).
-     * Runs the registered loader if present; transitions to ready on success,
-     * error on failure.
-     */
-    enable(name: CapabilityName): Promise<void>;
-    /**
-     * Disable a ready capability.
-     * Valid from: ready only.
-     */
-    disable(name: CapabilityName): void;
-    /**
-     * Mark a loading capability as ready (external use, e.g. bridge protocol).
-     * Valid from: loading only.
-     */
-    markReady(name: CapabilityName): void;
-    /**
-     * Mark a loading capability as errored (external use, e.g. bridge protocol).
-     * Valid from: loading only.
-     */
-    markError(name: CapabilityName, error: string): void;
-    /**
-     * Report loading progress (0-100).
-     * Emits capability.loading with progress if the capability is currently loading.
-     * No-op if the capability is not in loading state.
-     */
-    reportProgress(name: CapabilityName, progress: number): void;
-    /** Set a human-readable progress message for a loading capability */
-    setProgress(name: CapabilityName, message: string): void;
-    /** Get the current progress message for a capability */
-    getProgress(name: CapabilityName): string | undefined;
-    getError(name: CapabilityName): string | undefined;
-    listAll(): Array<{
-        name: CapabilityName;
-        state: CapabilityState;
-    }>;
-}
-
+declare const CURRENT_SHARD_VERSION = "1.0.0";
+declare const SHARD_FORMAT = "matric-shard";
+/** Components that can appear in a shard archive. */
+type ShardComponent = 'notes' | 'collections' | 'tags' | 'links' | 'embedding_sets' | 'embedding_set_members' | 'embedding_configs' | 'embeddings' | 'skos_schemes' | 'skos_concepts' | 'skos_relations' | 'note_skos_tags' | 'provenance_edges' | 'community_assignments' | 'communities' | 'graph_edges' | 'graph_sources';
 /**
- * Sequential SQL migration runner for DatabaseClient.
- * Tracks applied migrations in a schema_version table.
- * Each migration runs in a transaction; version updated atomically.
+ * Reference to one cluster file of a component split across addressable files
+ * (`notes/000.jsonl`, `notes/001.jsonl`, …). `offset`/`count` are the record
+ * range within the component, so an in-place reader fetches only the clusters a
+ * query needs — the shard analog of the AIWG chunk-manifest scan parts.
  */
-
-interface Migration {
-    version: number;
-    name: string;
-    sql: string;
-}
-declare class MigrationRunner {
-    private db;
-    private events?;
-    constructor(db: DatabaseClient, events?: TypedEventBus | undefined);
-    ensureSchemaTable(): Promise<void>;
-    getCurrentVersion(): Promise<number>;
-    apply(migrations: Migration[]): Promise<number>;
-    getAppliedMigrations(): Promise<Array<{
-        version: number;
-        name: string;
-    }>>;
+interface ShardClusterRef {
+    href: string;
+    offset: number;
+    count: number;
 }
-
-declare const allMigrations: Migration[];
-
 /**
- * Multi-archive manager for Fortemi.
- * Each archive is a separate PGlite instance with its own persistence path.
- * Migrations are applied automatically on open.
+ * Optional clustered layout (additive — absent on monolithic shards). When a
+ * component is present here, its records live in the listed cluster files instead
+ * of (or in addition to) the single `<component>.jsonl`. Both `importShard` and
+ * the in-place reader consume it; a monolithic shard omits `layout` entirely.
  */
-
-interface ArchiveInfo {
-    name: string;
-    createdAt: string;
+interface ShardLayout {
+    clusters?: Partial<Record<ShardComponent, ShardClusterRef[]>>;
 }
-declare class ArchiveManager {
-    private events?;
-    private currentArchive;
-    private db;
-    private archives;
-    private persistence;
-    private backendFactory;
-    constructor(persistenceOrFactory: PersistenceMode | StorageBackendFactory, events?: TypedEventBus | undefined, persistenceOverride?: PersistenceMode);
-    getCurrentArchiveName(): string;
-    getDb(): StorageBackend | null;
-    open(archiveName?: string): Promise<StorageBackend>;
-    create(archiveName: string): Promise<StorageBackend>;
-    switchTo(archiveName: string): Promise<StorageBackend>;
-    delete(archiveName: string): Promise<void>;
-    listArchives(): ArchiveInfo[];
-    close(): Promise<void>;
+/** Manifest included in every shard as manifest.json. */
+interface ShardManifest {
+    version: string;
+    matric_version: string;
+    format: typeof SHARD_FORMAT;
+    created_at: string;
+    components: ShardComponent[];
+    counts: Partial<Record<ShardComponent | 'community_sets', number>>;
+    checksums: Record<string, string>;
+    min_reader_version: string;
+    /** Clustered component layout for partial fetch (issue #189). Absent → monolithic. */
+    layout?: ShardLayout;
 }
-
-/**
- * Factory function for creating a FortemiCore instance.
- * All deployment modes use this entry point.
- */
-
-interface FortemiConfig {
-    persistence: 'opfs' | 'idb' | 'memory';
-    archiveName?: string;
+/** Options for shard export. */
+interface ExportOptions {
+    includeEmbeddings?: boolean;
+    /** Filter to specific collection (export only notes in this collection). */
+    collectionId?: string;
+    /** Filter to notes with this tag (e.g. 'app:research' for app-scoped export). */
+    tag?: string;
+    /** Export only these embedding sets and their member/vector rows. */
+    embeddingSetIds?: string[];
+    /** Preserve virtual selector materialization metadata and virtual member rows. */
+    includeMaterializedSelectors?: boolean;
+    /**
+     * When set to a positive integer, emit notes as clustered files
+     * (`notes/000.jsonl`, …) of this many records each, and record the layout in
+     * the manifest, so an in-place reader can fetch only the clusters it needs
+     * (issue #189). Absent → a single monolithic `notes.jsonl` (unchanged).
+     */
+    clusterNotesSize?: number;
 }
-interface FortemiCore {
-    events: TypedEventBus;
-    config: FortemiConfig;
-    destroy(): void;
+/** Conflict resolution strategy for shard import. */
+type ConflictStrategy = 'skip' | 'replace' | 'error';
+/** Options for shard import. */
+interface ImportOptions {
+    conflictStrategy?: ConflictStrategy;
+    /** Rows processed between cooperative yields. Defaults to 250. */
+    batchSize?: number;
+    /** Progress callback for long-running import phases. */
+    onProgress?: (progress: ImportProgress) => void;
 }
-declare function createFortemi(config: FortemiConfig): FortemiCore;
-
-/**
- * Compute a SHA-256 content hash for the given byte array.
- *
- * Returns a string in `algorithm:hex` format to match the server-side
- * convention, e.g. `sha256:a3b4c5...` (64 hex characters after the prefix).
- *
- * @param data - Raw bytes to hash
- * @returns `'sha256:<64-char lowercase hex>'`
- */
-declare function computeHash(data: Uint8Array): string;
-
-interface SWRegistrationResult {
-    registered: boolean;
-    registration?: ServiceWorkerRegistration;
-    error?: string;
+type ImportProgressPhase = 'unpack' | 'validate' | 'collections' | 'notes' | 'skos' | 'links' | 'provenance' | 'embedding_sets' | 'embeddings' | 'embedding_set_members' | 'graph' | 'communities' | 'index';
+interface ImportProgress {
+    phase: ImportProgressPhase;
+    done: number;
+    total: number;
 }
-declare function registerServiceWorker(swUrl?: string): Promise<SWRegistrationResult>;
-
-/**
- * REST route definitions for Service Worker.
- * These are pure functions that transform HTTP Request → tool input and tool output → Response.
- * The actual DB connection is injected at registration time.
- *
- * All routes currently return 503 Not Implemented — the DB wiring happens in a later issue.
- * The URL structure and request/response shapes are the valuable contract defined here.
- */
-interface RouteHandler {
-    method: string;
-    pattern: RegExp;
-    handler: (request: Request, match: RegExpMatchArray, params: URLSearchParams) => Promise<Response>;
+/** Per-entity import counts. */
+interface ImportCounts {
+    notes: number;
+    collections: number;
+    tags: number;
+    links: number;
+    embedding_sets: number;
+    embedding_set_members: number;
+    embeddings: number;
+    skos_schemes: number;
+    skos_concepts: number;
+    skos_relations: number;
+    note_skos_tags: number;
+    provenance_edges: number;
+    graph_sources: number;
+    graph_edges: number;
+    community_sets: number;
+    communities: number;
+    community_assignments: number;
 }
+/** Result of a shard import operation. */
+interface ImportResult {
+    success: boolean;
+    counts: ImportCounts;
+    skipped: Partial<ImportCounts>;
+    warnings: string[];
+    errors: string[];
+    duration_ms: number;
+}
+/** Note as serialized in the shard JSONL. */
+interface ShardNote {
+    id: string;
+    title: string | null;
+    original_content: string;
+    revised_content: string | null;
+    format: string;
+    source: string;
+    starred: boolean;
+    archived: boolean;
+    tags: string[];
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+/** Collection as serialized in the shard JSON array. */
+interface ShardCollection {
+    id: string;
+    name: string;
+    description: string | null;
+    parent_id: string | null;
+    created_at: string;
+    note_count?: number;
+}
+/** Tag as serialized in the shard JSON array. */
+interface ShardTag {
+    name: string;
+    created_at: string;
+}
+/** Link as serialized in the shard JSONL. */
+interface ShardLink {
+    id: string;
+    from_note_id: string;
+    to_note_id: string;
+    kind: string;
+    score: number | null;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+/** Embedding set as serialized in the shard JSON array. */
+interface ShardEmbeddingSet {
+    id: string;
+    name?: string;
+    purpose?: string | null;
+    model: string;
+    dimension: number;
+    kind?: 'physical' | 'filter' | 'virtual';
+    mode?: 'auto' | 'manual' | 'mixed' | null;
+    truncate_dimension?: number | null;
+    criteria?: Record<string, unknown> | null;
+    source?: Record<string, unknown> | null;
+    compatibility?: Record<string, unknown> | null;
+    materialization?: Record<string, unknown> | null;
+    freshness?: ShardArtifactFreshness | null;
+    created_at: string;
+    updated_at?: string;
+}
+/** Embedding set member as serialized in the shard JSONL. */
+interface ShardEmbeddingSetMember {
+    embedding_set_id: string;
+    note_id: string;
+    embedding_id: string;
+}
+/** Embedding as serialized in the shard JSONL. */
+interface ShardEmbedding {
+    id: string;
+    note_id: string;
+    embedding_set_id: string;
+    vector: number[];
+    created_at: string;
+}
+/** SKOS scheme as serialized in the shard JSON array. */
+interface ShardSkosScheme {
+    id: string;
+    title: string;
+    description: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** SKOS concept as serialized in the shard JSON array. */
+interface ShardSkosConcept {
+    id: string;
+    scheme_id: string;
+    pref_label: string;
+    alt_labels: string[];
+    definition: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** SKOS concept relation as serialized in the shard JSONL. */
+interface ShardSkosRelation {
+    id: string;
+    source_concept_id: string;
+    target_concept_id: string;
+    relation_type: 'broader' | 'narrower' | 'related';
+    created_at: string;
+}
+/** Note-to-SKOS-concept assignment as serialized in the shard JSONL. */
+interface ShardNoteSkosTag {
+    id: string;
+    note_id: string;
+    concept_id: string;
+    created_at: string;
+}
+/** Provenance edge as serialized in the shard JSONL. */
+interface ShardProvenanceEdge {
+    id: string;
+    entity_type: string;
+    entity_id: string;
+    activity: string;
+    agent: string;
+    started_at: string;
+    ended_at: string | null;
+    attributes: Record<string, unknown> | null;
+}
+interface ShardArtifactFreshness {
+    status: 'fresh' | 'stale' | 'unknown';
+    checked_at?: string;
+    stale_reason?: string;
+    source_hashes?: {
+        notes?: string;
+        links?: string;
+        embeddings?: string;
+        embedding_set_members?: string;
+        virtual_set_definition?: string;
+        parameters?: string;
+    };
+}
+
+/**
+ * LinksRepository — bidirectional note link management.
+ *
+ * Responsibilities:
+ * - Create typed links between notes with duplicate prevention
+ * - Soft-delete links
+ * - Query outbound, inbound, and backlinks for a note
+ */
+
+interface LinkRow {
+    id: string;
+    source_note_id: string;
+    target_note_id: string;
+    link_type: string;
+    confidence: number | null;
+    created_at: Date;
+    updated_at: Date | null;
+    deleted_at: Date | null;
+}
+declare class LinksRepository {
+    private db;
+    constructor(db: DatabaseClient);
+    create(sourceNoteId: string, targetNoteId: string, linkType?: string): Promise<LinkRow>;
+    get(id: string): Promise<LinkRow>;
+    listForNote(noteId: string): Promise<{
+        outbound: LinkRow[];
+        inbound: LinkRow[];
+    }>;
+    getBacklinks(noteId: string): Promise<string[]>;
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * CollectionsRepository — folder/category management for notes.
+ *
+ * Responsibilities:
+ * - Create, read, update, and soft-delete collections
+ * - Prevent circular parent references
+ * - Assign and unassign notes from collections
+ * - Return flat list and shallow tree views
+ */
+
+interface CollectionRow {
+    id: string;
+    name: string;
+    description: string | null;
+    parent_id: string | null;
+    position: number;
+    created_at: Date;
+    updated_at: Date;
+    deleted_at: Date | null;
+}
+interface CollectionCreateInput {
+    name: string;
+    description?: string;
+    parent_id?: string;
+}
+declare class CollectionsRepository {
+    private db;
+    constructor(db: DatabaseClient);
+    create(input: CollectionCreateInput): Promise<CollectionRow>;
+    get(id: string): Promise<CollectionRow>;
+    list(): Promise<CollectionRow[]>;
+    listTree(): Promise<Array<CollectionRow & {
+        children: CollectionRow[];
+    }>>;
+    update(id: string, fields: Partial<Pick<CollectionRow, 'name' | 'description' | 'parent_id' | 'position'>>): Promise<CollectionRow>;
+    delete(id: string): Promise<void>;
+    assignNote(collectionId: string, noteId: string): Promise<void>;
+    unassignNote(collectionId: string, noteId: string): Promise<void>;
+    getNotesInCollection(collectionId: string): Promise<string[]>;
+}
+
+/**
+ * Field mapper — converts between browser schema and shard (server) schema.
+ *
+ * The browser uses different field names than the server shard format.
+ * This module handles all rename transforms bidirectionally.
+ */
+
+/** Browser-format note row from the export query (denormalized). */
+interface BrowserNoteExport {
+    id: string;
+    title: string | null;
+    format: string;
+    source: string;
+    is_starred: boolean;
+    is_archived: boolean;
+    created_at: Date | string;
+    updated_at: Date | string;
+    deleted_at: Date | string | null;
+    original_content: string;
+    revised_content: string | null;
+    tags: string[];
+}
+/** Convert a browser note to shard format. */
+declare function noteToShard(note: BrowserNoteExport): ShardNote;
+/** Convert a shard note back to browser-insertable format. */
+declare function noteFromShard(shard: ShardNote): BrowserNoteExport;
+/** Convert a browser link to shard format. */
+declare function linkToShard(link: LinkRow): ShardLink;
+/** Convert a shard link back to browser-insertable format. */
+declare function linkFromShard(shard: ShardLink): {
+    id: string;
+    source_note_id: string;
+    target_note_id: string;
+    link_type: string;
+    confidence: number | null;
+    created_at: string;
+};
+/** Convert a browser collection to shard format. */
+declare function collectionToShard(collection: CollectionRow, noteCount?: number): ShardCollection;
+/** Convert a shard collection back to browser-insertable format. */
+declare function collectionFromShard(shard: ShardCollection): {
+    id: string;
+    name: string;
+    description: string | null;
+    parent_id: string | null;
+    created_at: string;
+};
+/**
+ * Convert SKOS concepts + note_tag associations into shard flat tag format.
+ * Shard tags are simple string arrays — deduplicated across all notes.
+ */
+declare function tagsToShard(allTags: Array<{
+    name: string;
+    created_at: Date | string;
+}>): ShardTag[];
+/**
+ * Convert shard flat tags to browser format for insertion.
+ * Returns unique tag names ready for note_tag association.
+ */
+declare function tagsFromShard(shardTags: ShardTag[]): string[];
+/** Convert a browser embedding_set to shard format. */
+declare function embeddingSetToShard(set: {
+    id: string;
+    name?: string;
+    purpose?: string | null;
+    model_name: string;
+    dimensions: number;
+    kind?: 'physical' | 'filter' | 'virtual';
+    mode?: 'auto' | 'manual' | 'mixed' | null;
+    truncate_dimension?: number | null;
+    criteria_json?: unknown | null;
+    source_json?: unknown | null;
+    compatibility_json?: unknown | null;
+    materialization_json?: unknown | null;
+    freshness_json?: unknown | null;
+    created_at: Date | string;
+    updated_at?: Date | string;
+}): ShardEmbeddingSet;
+/** Convert a shard embedding set back to browser format. */
+declare function embeddingSetFromShard(shard: ShardEmbeddingSet): {
+    id: string;
+    name: string;
+    purpose: string | null;
+    model_name: string;
+    dimensions: number;
+    kind: 'physical' | 'filter' | 'virtual';
+    mode: 'auto' | 'manual' | 'mixed' | null;
+    truncate_dimension: number | null;
+    criteria_json: string | null;
+    source_json: string | null;
+    compatibility_json: string | null;
+    materialization_json: string | null;
+    freshness_json: string | null;
+    created_at: string;
+    updated_at: string | null;
+};
+/** Convert a browser embedding_set_member to shard format. */
+declare function embeddingSetMemberToShard(member: {
+    embedding_set_id: string;
+    note_id: string;
+    embedding_id: string;
+}): ShardEmbeddingSetMember;
+/** Convert a browser embedding to shard format. */
+declare function embeddingToShard(emb: {
+    id: string;
+    note_id: string;
+    embedding_set_id: string;
+    vector: string | number[];
+    created_at: Date | string;
+}): ShardEmbedding;
+/** Convert a shard embedding back to browser format. */
+declare function embeddingFromShard(shard: ShardEmbedding): {
+    id: string;
+    note_id: string;
+    embedding_set_id: string;
+    vector: string;
+    created_at: string;
+};
+declare function skosSchemeToShard(scheme: {
+    id: string;
+    title: string;
+    description: string | null;
+    created_at: Date | string;
+    updated_at: Date | string;
+}): ShardSkosScheme;
+declare function skosConceptToShard(concept: {
+    id: string;
+    scheme_id: string;
+    pref_label: string;
+    alt_labels: string[] | string | null;
+    definition: string | null;
+    created_at: Date | string;
+    updated_at: Date | string;
+}): ShardSkosConcept;
+declare function skosRelationToShard(relation: {
+    id: string;
+    source_concept_id: string;
+    target_concept_id: string;
+    relation_type: 'broader' | 'narrower' | 'related';
+    created_at: Date | string;
+}): ShardSkosRelation;
+declare function noteSkosTagToShard(tag: {
+    id: string;
+    note_id: string;
+    concept_id: string;
+    created_at: Date | string;
+}): ShardNoteSkosTag;
+declare function provenanceEdgeToShard(edge: {
+    id: string;
+    entity_type: string;
+    entity_id: string;
+    activity: string;
+    agent: string;
+    started_at: Date | string;
+    ended_at: Date | string | null;
+    attributes: Record<string, unknown> | string | null;
+}): ShardProvenanceEdge;
+
+/**
+ * In-place Knowledge Shard reader (issue #189) — the static-file backend.
+ *
+ * A shard is already a self-describing bundle of formatted component files
+ * (`notes.jsonl`, `links.jsonl`, `note_skos_tags.jsonl`, `skos_concepts.json`, …)
+ * plus a `manifest.json`. `importShard` loads all of it into PGlite; this reader
+ * is the *second* access mode of the SAME format: open the manifest and query the
+ * component (or clustered) files directly, with NO PGlite — read-only, lightest.
+ *
+ * Capabilities (read-only): browse + get note, full-text + facet search, lazy
+ * links/tags/concepts + full record. Semantic is opt-in via a pluggable provider
+ * (none / brute-force cosine / prebuilt ANN snapshot) — see `StaticSemanticProvider`.
+ */
+
+/** The public note shape — the same browser-insertable record `importShard` produces. */
+type ShardReaderNote = BrowserNoteExport;
+interface ShardSearchWeights {
+    title: number;
+    content: number;
+    tag: number;
+}
+interface ShardListOptions {
+    offset?: number;
+    limit?: number;
+    /** Include archived notes (default true). */
+    includeArchived?: boolean;
+    /** Include soft-deleted notes (default false). */
+    includeDeleted?: boolean;
+}
+interface ShardSearchOptions extends ShardListOptions {
+    /** AND-filter: note must carry every listed tag. */
+    tags?: string[];
+    /** OR-filter on note source. */
+    source?: string[];
+    rank?: boolean;
+    snippets?: boolean;
+    snippetLength?: number;
+    weights?: Partial<ShardSearchWeights>;
+}
+interface ShardSearchRankedNote {
+    note: ShardReaderNote;
+    rank: number;
+    snippet?: string;
+}
+interface ShardSearchResult {
+    items: ShardReaderNote[];
+    total: number;
+    facets: {
+        tags: Record<string, number>;
+        source: Record<string, number>;
+    };
+    rankedItems?: ShardSearchRankedNote[];
+    /** Cluster files fetched to serve this query (0 when served from cache). */
+    fetchedClusters: number;
+}
+interface ShardNoteFull {
+    note: ShardReaderNote;
+    links: ShardLink[];
+    concepts: ShardSkosConcept[];
+}
+/**
+ * Opt-in semantic search over static files. The reader stays text/facets-only
+ * unless a provider is supplied. Implementations span the tradeoff points:
+ * brute-force cosine over a small static vector set, or a prebuilt ANN snapshot
+ * for the full corpus. `prepare()` may lazily load whatever static asset it needs.
+ */
+interface StaticSemanticProvider {
+    prepare?(store: ShardComponentStore): Promise<void>;
+    search(query: string, k: number): Promise<Array<{
+        id: string;
+        score: number;
+    }>>;
+}
+interface OpenShardOptions {
+    /** Static base URL when `source` is unpacked component files. */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** Optional semantic provider; absent → `semantic()` returns []. */
+    semantic?: StaticSemanticProvider;
+    /** Bounds the cross-page search match cache (total cached note records). Default 5000. */
+    maxCachedMatches?: number;
+}
+/** Reads shard component/cluster files from a packed map or a static base URL. */
+interface ShardComponentStore {
+    readonly manifest: ShardManifest;
+    read(filename: string): Promise<Uint8Array | undefined>;
+}
+type ShardReaderSource = Uint8Array | Blob | {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+};
+interface ShardReader {
+    readonly manifest: ShardManifest;
+    listNotes(options?: ShardListOptions): Promise<{
+        items: ShardReaderNote[];
+        total: number;
+    }>;
+    getNote(id: string): Promise<ShardReaderNote | null>;
+    search(query: string, options?: ShardSearchOptions): Promise<ShardSearchResult>;
+    linksOf(id: string): Promise<ShardLink[]>;
+    conceptsOf(id: string): Promise<ShardSkosConcept[]>;
+    getNoteFull(id: string): Promise<ShardNoteFull | null>;
+    semantic(query: string, k?: number): Promise<Array<{
+        note: ShardReaderNote;
+        score: number;
+    }>>;
+    close(): void;
+}
+/**
+ * Open a Knowledge Shard for in-place, read-only query — NO PGlite. `source` is a
+ * packed tar.gz (`Uint8Array`/`Blob`) or a static base URL serving the unpacked
+ * component/cluster files. Honors `min_reader_version`: a shard that needs a newer
+ * reader than this build throws (the host should fall back to `importShard`).
+ */
+declare function openShard(source: ShardReaderSource, options?: OpenShardOptions): Promise<ShardReader>;
+
+/**
+ * Backend seam (#191) — a uniform tool-intent operation interface that lets the
+ * PGlite database backend (#187) and the static-file shard backend (#189) be
+ * selected and dispatched against the same way, plus a capability-negotiation
+ * API so a caller asks for the operations it needs and gets the lightest backend
+ * that provides them.
+ *
+ * The seam sits one level above SQL: every adapter exposes the same read
+ * operations (and optional write / semantic / full-content ops) regardless of
+ * whether the data lives in a queryable PGlite instance or a set of static shard
+ * files fetched over HTTP. A remote-server backend is a future adapter against
+ * this same interface — deliberately deferred. See
+ * `.aiwg/architecture/adr-backend-seam.md`.
+ */
+
+/**
+ * Semantic-search tier a backend offers, in increasing capability:
+ * - `none`     — no vector search (text / facets only)
+ * - `cosine-small` — brute-force cosine over a small static vector set (#189)
+ * - `ann-full` — prebuilt/queryable approximate-nearest-neighbour over the full
+ *   corpus (PGlite + pgvector, or a prebuilt ANN snapshot)
+ * - `server`   — delegated to a remote service (future remote backend)
+ */
+type BackendSemanticTier = 'none' | 'cosine-small' | 'ann-full' | 'server';
+/** Relative startup cost of bringing a backend online. */
+type BackendStartupCost = 'instant' | 'index-build' | 'network';
+/** What a backend can do — the unit of capability negotiation. */
+interface BackendCapabilities {
+    /** Can answer list / get / search read operations. */
+    read: boolean;
+    /** Can mutate notes (manageNote). */
+    write: boolean;
+    /** Can merge external shards into its store. */
+    merge: boolean;
+    /** Coordinates concurrent multi-user writes. */
+    multiUser: boolean;
+    /** Highest semantic-search tier available. */
+    semantic: BackendSemanticTier;
+    /** Relative cost to bring the backend online. */
+    startupCost: BackendStartupCost;
+}
+/**
+ * Backend-neutral note record. `source`/`starred`/`archived` are optional
+ * because lean read paths (PGlite full-text search) do not return them; list,
+ * get, and every shard path populate all fields.
+ */
+interface BackendNote {
+    id: string;
+    title: string | null;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+    source?: string;
+    starred?: boolean;
+    archived?: boolean;
+}
+/** A note plus its current rendered content. */
+interface BackendNoteFull extends BackendNote {
+    content: string;
+}
+/** One search hit — note plus optional rank/snippet when the backend ranks. */
+interface BackendSearchHit {
+    note: BackendNote;
+    rank?: number;
+    snippet?: string;
+}
+/** Search response with optional facet counts. */
+interface BackendSearchResult {
+    hits: BackendSearchHit[];
+    total: number;
+    facets?: {
+        tags: Record<string, number>;
+        source?: Record<string, number>;
+    };
+}
+interface BackendListOptions {
+    offset?: number;
+    limit?: number;
+}
+interface BackendSearchQueryOptions extends BackendListOptions {
+    /** AND-filter: note must carry every listed tag. */
+    tags?: string[];
+    /** OR-filter on note source. */
+    source?: string[];
+}
+/**
+ * Uniform tool-intent operation interface. Every backend implements the read
+ * core; `getNoteFull`, `semantic`, and `manageNote` are optional and present
+ * only on backends whose capabilities advertise them.
+ */
+interface DataBackend {
+    readonly id: string;
+    readonly capabilities: BackendCapabilities;
+    listNotes(options?: BackendListOptions): Promise<{
+        items: BackendNote[];
+        total: number;
+    }>;
+    getNote(id: string): Promise<BackendNote | null>;
+    search(query: string, options?: BackendSearchQueryOptions): Promise<BackendSearchResult>;
+    /** Lazy full content (present when capabilities.read). */
+    getNoteFull?(id: string): Promise<BackendNoteFull | null>;
+    /** Vector search (present when capabilities.semantic !== 'none'). */
+    semantic?(query: string, k?: number): Promise<BackendSearchHit[]>;
+    /** Write op (present when capabilities.write). */
+    manageNote?(input: unknown): Promise<unknown>;
+}
+/** What a caller needs. Booleans require `true`; `semantic` is a minimum tier. */
+interface BackendRequest {
+    read?: boolean;
+    write?: boolean;
+    merge?: boolean;
+    multiUser?: boolean;
+    /** Minimum acceptable semantic tier (a higher tier satisfies a lower request). */
+    semantic?: BackendSemanticTier;
+}
+interface BackendCandidate {
+    backend: DataBackend;
+    /** Requested capabilities this backend cannot satisfy ([] = fully satisfies). */
+    missing: string[];
+}
+interface BackendSelection {
+    /** Chosen backend — fully-satisfying-and-lightest, else fewest-missing. Null only when no backends are available. */
+    backend: DataBackend | null;
+    capabilities: BackendCapabilities | null;
+    /** Requested capabilities the chosen backend cannot satisfy. */
+    missing: string[];
+    /** Every candidate with its own missing set, ordered as evaluated. */
+    candidates: BackendCandidate[];
+}
+/**
+ * Pick the backend that best satisfies `request` from `available`. Prefers a
+ * fully-satisfying backend with the lightest startup cost; if none fully
+ * satisfy, returns the one missing the fewest capabilities (lightest on ties) so
+ * the caller can degrade with eyes open via `selection.missing`.
+ */
+declare function selectBackend(request: BackendRequest, available: DataBackend[]): BackendSelection;
+interface PGliteBackendOptions {
+    id?: string;
+    /** Whether embeddings exist so search can use the semantic path. */
+    semanticAvailable?: boolean;
+}
+/**
+ * Wrap a PGlite-backed `DatabaseClient` as a `DataBackend`. Read ops delegate to
+ * the repositories; writes go through the `manageNote` tool. Advertises full
+ * read+write+merge with `ann-full` semantic when embeddings are present.
+ */
+declare function createPGliteBackend(db: DatabaseClient, options?: PGliteBackendOptions): DataBackend;
+interface ShardBackendOptions {
+    id?: string;
+    /** Declared semantic tier this shard provides (default `none`). Set to `cosine-small` when the reader has a vector provider. */
+    semantic?: BackendSemanticTier;
+}
+/**
+ * Wrap a `ShardReader` (#189) as a read-only `DataBackend`. Startup is instant
+ * (no index build) and the semantic tier is whatever the reader's provider
+ * offers — `none` for text/facets-only shards, `cosine-small` when a vector
+ * provider is attached.
+ */
+declare function createShardBackend(reader: ShardReader, options?: ShardBackendOptions): DataBackend;
+
+/**
+ * Capability module system (ADR-002).
+ * Tracks opt-in WASM module states. No WASM loaded by default (CAP-001).
+ *
+ * State machine (valid transitions):
+ *   unloaded  -> loading  (via enable)
+ *   loading   -> ready    (via markReady or successful loader)
+ *   loading   -> error    (via markError or failed loader)
+ *   ready     -> disabled (via disable)
+ *   disabled  -> loading  (via enable, re-enable)
+ *   error     -> loading  (via enable, retry)
+ */
+
+type CapabilityState = 'unloaded' | 'loading' | 'ready' | 'error' | 'disabled';
+type CapabilityName = 'semantic' | 'llm' | 'audio' | 'vision' | 'pdf';
+declare class CapabilityManager {
+    private events;
+    private capabilities;
+    private loaders;
+    private progressMessages;
+    constructor(events: TypedEventBus);
+    /**
+     * Register an async loader for a capability.
+     * Called by enable(); if no loader is registered the capability transitions
+     * directly to ready (useful for capabilities that require no async init).
+     */
+    registerLoader(name: CapabilityName, loader: () => Promise<void>): void;
+    getState(name: CapabilityName): CapabilityState;
+    isReady(name: CapabilityName): boolean;
+    /**
+     * Enable a capability.
+     * Valid from: unloaded, disabled, error (retry).
+     * Runs the registered loader if present; transitions to ready on success,
+     * error on failure.
+     */
+    enable(name: CapabilityName): Promise<void>;
+    /**
+     * Disable a ready capability.
+     * Valid from: ready only.
+     */
+    disable(name: CapabilityName): void;
+    /**
+     * Mark a loading capability as ready (external use, e.g. bridge protocol).
+     * Valid from: loading only.
+     */
+    markReady(name: CapabilityName): void;
+    /**
+     * Mark a loading capability as errored (external use, e.g. bridge protocol).
+     * Valid from: loading only.
+     */
+    markError(name: CapabilityName, error: string): void;
+    /**
+     * Report loading progress (0-100).
+     * Emits capability.loading with progress if the capability is currently loading.
+     * No-op if the capability is not in loading state.
+     */
+    reportProgress(name: CapabilityName, progress: number): void;
+    /** Set a human-readable progress message for a loading capability */
+    setProgress(name: CapabilityName, message: string): void;
+    /** Get the current progress message for a capability */
+    getProgress(name: CapabilityName): string | undefined;
+    getError(name: CapabilityName): string | undefined;
+    listAll(): Array<{
+        name: CapabilityName;
+        state: CapabilityState;
+    }>;
+}
+
+/**
+ * Sequential SQL migration runner for DatabaseClient.
+ * Tracks applied migrations in a schema_version table.
+ * Each migration runs in a transaction; version updated atomically.
+ */
+
+interface Migration {
+    version: number;
+    name: string;
+    sql: string;
+}
+declare class MigrationRunner {
+    private db;
+    private events?;
+    constructor(db: DatabaseClient, events?: TypedEventBus | undefined);
+    ensureSchemaTable(): Promise<void>;
+    getCurrentVersion(): Promise<number>;
+    apply(migrations: Migration[]): Promise<number>;
+    getAppliedMigrations(): Promise<Array<{
+        version: number;
+        name: string;
+    }>>;
+}
+
+declare const allMigrations: Migration[];
+
+/**
+ * Multi-archive manager for Fortemi.
+ * Each archive is a separate PGlite instance with its own persistence path.
+ * Migrations are applied automatically on open.
+ */
+
+interface ArchiveInfo {
+    name: string;
+    createdAt: string;
+}
+declare class ArchiveManager {
+    private events?;
+    private currentArchive;
+    private db;
+    private archives;
+    private persistence;
+    private backendFactory;
+    constructor(persistenceOrFactory: PersistenceMode | StorageBackendFactory, events?: TypedEventBus | undefined, persistenceOverride?: PersistenceMode);
+    getCurrentArchiveName(): string;
+    getDb(): StorageBackend | null;
+    open(archiveName?: string): Promise<StorageBackend>;
+    /**
+     * Adopt an already-created backend WITHOUT running migrations — for a backend
+     * whose schema is already present, e.g. a PGlite restored from a physical
+     * data-dir snapshot (issue #187, `restoreDbSnapshot`). Running migrations here
+     * would be wrong: the restored dir already carries them (and the HNSW index).
+     */
+    adopt(backend: StorageBackend, archiveName?: string): Promise<StorageBackend>;
+    create(archiveName: string): Promise<StorageBackend>;
+    switchTo(archiveName: string): Promise<StorageBackend>;
+    delete(archiveName: string): Promise<void>;
+    listArchives(): ArchiveInfo[];
+    close(): Promise<void>;
+}
+
+/**
+ * Factory function for creating a FortemiCore instance.
+ * All deployment modes use this entry point.
+ */
+
+interface FortemiConfig {
+    persistence: 'opfs' | 'idb' | 'memory';
+    archiveName?: string;
+}
+interface FortemiCore {
+    events: TypedEventBus;
+    config: FortemiConfig;
+    destroy(): void;
+}
+declare function createFortemi(config: FortemiConfig): FortemiCore;
+
+/**
+ * Compute a SHA-256 content hash for the given byte array.
+ *
+ * Returns a string in `algorithm:hex` format to match the server-side
+ * convention, e.g. `sha256:a3b4c5...` (64 hex characters after the prefix).
+ *
+ * @param data - Raw bytes to hash
+ * @returns `'sha256:<64-char lowercase hex>'`
+ */
+declare function computeHash(data: Uint8Array): string;
+
+interface SWRegistrationResult {
+    registered: boolean;
+    registration?: ServiceWorkerRegistration;
+    error?: string;
+}
+declare function registerServiceWorker(swUrl?: string): Promise<SWRegistrationResult>;
+
+/**
+ * REST route definitions for Service Worker.
+ * These are pure functions that transform HTTP Request → tool input and tool output → Response.
+ * The actual DB connection is injected at registration time.
+ *
+ * All routes currently return 503 Not Implemented — the DB wiring happens in a later issue.
+ * The URL structure and request/response shapes are the valuable contract defined here.
+ */
+interface RouteHandler {
+    method: string;
+    pattern: RegExp;
+    handler: (request: Request, match: RegExpMatchArray, params: URLSearchParams) => Promise<Response>;
+}
+/**
+ * Create route handlers.
+ * db parameter will be injected when the SW gets access to PGlite.
+ * For now, returns 503 Not Implemented for all routes.
+ */
+declare function createRoutes(): RouteHandler[];
+/**
+ * Match a request against the registered routes and return the first matching
+ * handler, or null if no route matches.
+ */
+declare function matchRoute(routes: RouteHandler[], request: Request, url: URL): RouteHandler | null;
+
 /**
- * Create route handlers.
- * db parameter will be injected when the SW gets access to PGlite.
- * For now, returns 503 Not Implemented for all routes.
- */
-declare function createRoutes(): RouteHandler[];
-/**
- * Match a request against the registered routes and return the first matching
- * handler, or null if no route matches.
- */
-declare function matchRoute(routes: RouteHandler[], request: Request, url: URL): RouteHandler | null;
-
-/**
  * Content-addressable blob storage.
  *
  * Path format: blobs/{dir1}/{dir2}/{hash}
@@ -1272,79 +2151,6 @@ declare class TagsRepository {
     }>>;
 }
 
-/**
- * CollectionsRepository — folder/category management for notes.
- *
- * Responsibilities:
- * - Create, read, update, and soft-delete collections
- * - Prevent circular parent references
- * - Assign and unassign notes from collections
- * - Return flat list and shallow tree views
- */
-
-interface CollectionRow {
-    id: string;
-    name: string;
-    description: string | null;
-    parent_id: string | null;
-    position: number;
-    created_at: Date;
-    updated_at: Date;
-    deleted_at: Date | null;
-}
-interface CollectionCreateInput {
-    name: string;
-    description?: string;
-    parent_id?: string;
-}
-declare class CollectionsRepository {
-    private db;
-    constructor(db: DatabaseClient);
-    create(input: CollectionCreateInput): Promise<CollectionRow>;
-    get(id: string): Promise<CollectionRow>;
-    list(): Promise<CollectionRow[]>;
-    listTree(): Promise<Array<CollectionRow & {
-        children: CollectionRow[];
-    }>>;
-    update(id: string, fields: Partial<Pick<CollectionRow, 'name' | 'description' | 'parent_id' | 'position'>>): Promise<CollectionRow>;
-    delete(id: string): Promise<void>;
-    assignNote(collectionId: string, noteId: string): Promise<void>;
-    unassignNote(collectionId: string, noteId: string): Promise<void>;
-    getNotesInCollection(collectionId: string): Promise<string[]>;
-}
-
-/**
- * LinksRepository — bidirectional note link management.
- *
- * Responsibilities:
- * - Create typed links between notes with duplicate prevention
- * - Soft-delete links
- * - Query outbound, inbound, and backlinks for a note
- */
-
-interface LinkRow {
-    id: string;
-    source_note_id: string;
-    target_note_id: string;
-    link_type: string;
-    confidence: number | null;
-    created_at: Date;
-    updated_at: Date | null;
-    deleted_at: Date | null;
-}
-declare class LinksRepository {
-    private db;
-    constructor(db: DatabaseClient);
-    create(sourceNoteId: string, targetNoteId: string, linkType?: string): Promise<LinkRow>;
-    get(id: string): Promise<LinkRow>;
-    listForNote(noteId: string): Promise<{
-        outbound: LinkRow[];
-        inbound: LinkRow[];
-    }>;
-    getBacklinks(noteId: string): Promise<string[]>;
-    delete(id: string): Promise<void>;
-}
-
 /**
  * SkosRepository — SKOS taxonomy management (schemes, concepts, relations).
  *
@@ -1468,19 +2274,19 @@ declare const CaptureKnowledgeInputSchema: z.ZodObject<{
     }, {
         content: string;
         title?: string | undefined;
-        format?: "markdown" | "plain" | "html" | undefined;
         tags?: string[] | undefined;
+        format?: "markdown" | "plain" | "html" | undefined;
     }>, "many">>;
     template: z.ZodOptional<z.ZodString>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     source: string;
     format: "markdown" | "plain" | "html";
-    visibility: "private" | "shared" | "public";
+    visibility: "private" | "public" | "shared";
     action: "create" | "bulk_create" | "from_template";
     title?: string | undefined;
-    archive_id?: string | undefined;
     tags?: string[] | undefined;
+    archive_id?: string | undefined;
     content?: string | undefined;
     notes?: {
         format: "markdown" | "plain" | "html";
@@ -1494,16 +2300,16 @@ declare const CaptureKnowledgeInputSchema: z.ZodObject<{
     action: "create" | "bulk_create" | "from_template";
     source?: string | undefined;
     title?: string | undefined;
+    tags?: string[] | undefined;
     archive_id?: string | undefined;
     format?: "markdown" | "plain" | "html" | undefined;
-    visibility?: "private" | "shared" | "public" | undefined;
-    tags?: string[] | undefined;
+    visibility?: "private" | "public" | "shared" | undefined;
     content?: string | undefined;
     notes?: {
         content: string;
         title?: string | undefined;
-        format?: "markdown" | "plain" | "html" | undefined;
         tags?: string[] | undefined;
+        format?: "markdown" | "plain" | "html" | undefined;
     }[] | undefined;
     template?: string | undefined;
     variables?: Record<string, string> | undefined;
@@ -1548,35 +2354,35 @@ declare const SearchInputSchema: z.ZodObject<{
     visibility: z.ZodOptional<z.ZodEnum<["private", "shared", "public"]>>;
     include_facets: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    limit: number;
+    query: string;
     offset: number;
+    limit: number;
     include_facets: boolean;
-    mode: "semantic" | "text" | "hybrid";
-    query: string;
+    mode: "text" | "semantic" | "hybrid";
     source?: string | undefined;
+    tags?: string[] | undefined;
     format?: "markdown" | "plain" | "html" | undefined;
-    visibility?: "private" | "shared" | "public" | undefined;
+    visibility?: "private" | "public" | "shared" | undefined;
     is_starred?: boolean | undefined;
     is_archived?: boolean | undefined;
-    tags?: string[] | undefined;
     collection_id?: string | undefined;
     date_from?: Date | undefined;
     date_to?: Date | undefined;
 }, {
     query: string;
     source?: string | undefined;
+    tags?: string[] | undefined;
+    offset?: number | undefined;
     format?: "markdown" | "plain" | "html" | undefined;
-    visibility?: "private" | "shared" | "public" | undefined;
+    visibility?: "private" | "public" | "shared" | undefined;
     is_starred?: boolean | undefined;
     is_archived?: boolean | undefined;
-    tags?: string[] | undefined;
     limit?: number | undefined;
-    offset?: number | undefined;
     collection_id?: string | undefined;
     date_from?: Date | undefined;
     date_to?: Date | undefined;
     include_facets?: boolean | undefined;
-    mode?: "semantic" | "text" | "hybrid" | undefined;
+    mode?: "text" | "semantic" | "hybrid" | undefined;
 }>;
 type SearchInput = z.infer<typeof SearchInputSchema>;
 
@@ -1654,22 +2460,22 @@ declare const ListNotesInputSchema: z.ZodObject<{
     collection_id: z.ZodOptional<z.ZodString>;
     include_deleted: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    sort: "created_at" | "updated_at" | "title";
-    limit: number;
+    sort: "title" | "updated_at" | "created_at";
     offset: number;
+    limit: number;
     order: "asc" | "desc";
+    tags?: string[] | undefined;
     is_starred?: boolean | undefined;
     is_archived?: boolean | undefined;
-    tags?: string[] | undefined;
     include_deleted?: boolean | undefined;
     collection_id?: string | undefined;
 }, {
-    sort?: "created_at" | "updated_at" | "title" | undefined;
+    tags?: string[] | undefined;
+    sort?: "title" | "updated_at" | "created_at" | undefined;
+    offset?: number | undefined;
     is_starred?: boolean | undefined;
     is_archived?: boolean | undefined;
-    tags?: string[] | undefined;
     limit?: number | undefined;
-    offset?: number | undefined;
     order?: "asc" | "desc" | undefined;
     include_deleted?: boolean | undefined;
     collection_id?: string | undefined;
@@ -1683,12 +2489,12 @@ declare const ManageTagsInputSchema: z.ZodObject<{
     tag: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     action: "add" | "remove" | "list_for_note" | "list_all";
-    note_id?: string | undefined;
     tag?: string | undefined;
+    note_id?: string | undefined;
 }, {
     action: "add" | "remove" | "list_for_note" | "list_all";
-    note_id?: string | undefined;
     tag?: string | undefined;
+    note_id?: string | undefined;
 }>;
 type ManageTagsInput = z.infer<typeof ManageTagsInputSchema>;
 interface ManageTagsResult {
@@ -1712,16 +2518,16 @@ declare const ManageCollectionsInputSchema: z.ZodObject<{
     action: "create" | "delete" | "list" | "assign" | "unassign" | "list_tree";
     name?: string | undefined;
     collection_id?: string | undefined;
+    note_id?: string | undefined;
     description?: string | undefined;
     parent_id?: string | undefined;
-    note_id?: string | undefined;
 }, {
     action: "create" | "delete" | "list" | "assign" | "unassign" | "list_tree";
     name?: string | undefined;
     collection_id?: string | undefined;
+    note_id?: string | undefined;
     description?: string | undefined;
     parent_id?: string | undefined;
-    note_id?: string | undefined;
 }>;
 type ManageCollectionsInput = z.infer<typeof ManageCollectionsInputSchema>;
 interface ManageCollectionsResult {
@@ -1792,10 +2598,10 @@ declare const ManageCapabilitiesInputSchema: z.ZodObject<{
     action: z.ZodEnum<["list", "enable", "disable", "status"]>;
     capability: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "enable" | "disable" | "status" | "list";
+    action: "status" | "enable" | "disable" | "list";
     capability?: string | undefined;
 }, {
-    action: "enable" | "disable" | "status" | "list";
+    action: "status" | "enable" | "disable" | "list";
     capability?: string | undefined;
 }>;
 type ManageCapabilitiesInput = z.infer<typeof ManageCapabilitiesInputSchema>;
@@ -1897,16 +2703,16 @@ declare const ManageAttachmentsInputSchema: z.ZodObject<{
     display_name: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     action: "delete" | "list" | "attach" | "get" | "get_blob";
-    filename?: string | undefined;
     note_id?: string | undefined;
+    filename?: string | undefined;
     attachment_id?: string | undefined;
     data_base64?: string | undefined;
     mime_type?: string | undefined;
     display_name?: string | undefined;
 }, {
     action: "delete" | "list" | "attach" | "get" | "get_blob";
-    filename?: string | undefined;
     note_id?: string | undefined;
+    filename?: string | undefined;
     attachment_id?: string | undefined;
     data_base64?: string | undefined;
     mime_type?: string | undefined;
@@ -2587,265 +3393,58 @@ interface FortemiBridge {
 }
 interface FortemiBridgeHost {
     fortemiBridge?: FortemiBridge;
-    fortemiSecureStorage?: FortemiSecretStore;
-}
-declare function getFortemiBridge(host?: FortemiBridgeHost | undefined): FortemiBridge | null;
-declare function getFortemiSecretStore(host?: FortemiBridgeHost | undefined): FortemiSecretStore | null;
-declare function hasFortemiSecureSecrets(host?: FortemiBridgeHost | undefined): Promise<boolean>;
-
-type CspDirectiveName = 'default-src' | 'base-uri' | 'object-src' | 'frame-ancestors' | 'img-src' | 'font-src' | 'style-src' | 'script-src' | 'connect-src' | 'worker-src' | 'manifest-src' | 'report-uri';
-type CspDirectives = Partial<Record<CspDirectiveName, string[]>>;
-interface PluginCspOptions {
-    scriptSrc?: string[];
-    connectSrc?: string[];
-    imgSrc?: string[];
-    styleSrc?: string[];
-    reportUri?: string;
-    extraDirectives?: CspDirectives;
-}
-interface PluginScriptPolicy {
-    allowedOrigins: string[];
-    allowedUrls?: string[];
-    requireSri?: boolean;
-}
-interface PluginScriptDescriptor {
-    url: string;
-    integrity?: string;
-    crossOrigin?: 'anonymous' | 'use-credentials';
-}
-interface LoadedPluginScript {
-    url: string;
-    integrity: string;
-    bytes: Uint8Array;
-    text: string;
-}
-interface CspViolationReport {
-    documentUri?: string;
-    violatedDirective?: string;
-    effectiveDirective?: string;
-    blockedUri?: string;
-    originalPolicy?: string;
-    disposition?: string;
-    sourceFile?: string;
-    lineNumber?: number;
-    columnNumber?: number;
-    raw: unknown;
-}
-declare function buildPluginCsp(options?: PluginCspOptions): string;
-declare function computeSri(data: Uint8Array | ArrayBuffer, algorithm?: string): Promise<string>;
-declare function verifySri(data: Uint8Array | ArrayBuffer, integrity: string): Promise<boolean>;
-declare function isPluginScriptAllowed(url: string, policy: PluginScriptPolicy): boolean;
-declare function fetchPluginScript(descriptor: PluginScriptDescriptor, policy: PluginScriptPolicy, fetchFn?: typeof fetch): Promise<LoadedPluginScript>;
-declare function appendPluginScript(descriptor: PluginScriptDescriptor, policy: PluginScriptPolicy, doc?: Document): Promise<HTMLScriptElement>;
-declare function parseCspReport(body: unknown): CspViolationReport;
-declare function createCspReportHandler(onReport: (report: CspViolationReport) => void | Promise<void>): (request: Request) => Promise<Response>;
-
-/**
- * Shard format types — matches the fortemi server matric-shard specification.
- *
- * A shard is a gzip-compressed tar archive (.shard) containing serialized
- * knowledge data with a manifest for integrity verification.
- */
-declare const CURRENT_SHARD_VERSION = "1.0.0";
-declare const SHARD_FORMAT = "matric-shard";
-/** Components that can appear in a shard archive. */
-type ShardComponent = 'notes' | 'collections' | 'tags' | 'links' | 'embedding_sets' | 'embedding_set_members' | 'embedding_configs' | 'embeddings' | 'skos_schemes' | 'skos_concepts' | 'skos_relations' | 'note_skos_tags' | 'provenance_edges' | 'community_assignments' | 'communities' | 'graph_edges' | 'graph_sources';
-/** Manifest included in every shard as manifest.json. */
-interface ShardManifest {
-    version: string;
-    matric_version: string;
-    format: typeof SHARD_FORMAT;
-    created_at: string;
-    components: ShardComponent[];
-    counts: Partial<Record<ShardComponent | 'community_sets', number>>;
-    checksums: Record<string, string>;
-    min_reader_version: string;
-}
-/** Options for shard export. */
-interface ExportOptions {
-    includeEmbeddings?: boolean;
-    /** Filter to specific collection (export only notes in this collection). */
-    collectionId?: string;
-    /** Filter to notes with this tag (e.g. 'app:research' for app-scoped export). */
-    tag?: string;
-    /** Export only these embedding sets and their member/vector rows. */
-    embeddingSetIds?: string[];
-    /** Preserve virtual selector materialization metadata and virtual member rows. */
-    includeMaterializedSelectors?: boolean;
-}
-/** Conflict resolution strategy for shard import. */
-type ConflictStrategy = 'skip' | 'replace' | 'error';
-/** Options for shard import. */
-interface ImportOptions {
-    conflictStrategy?: ConflictStrategy;
-    /** Rows processed between cooperative yields. Defaults to 250. */
-    batchSize?: number;
-    /** Progress callback for long-running import phases. */
-    onProgress?: (progress: ImportProgress) => void;
-}
-type ImportProgressPhase = 'unpack' | 'validate' | 'collections' | 'notes' | 'skos' | 'links' | 'provenance' | 'embedding_sets' | 'embeddings' | 'embedding_set_members' | 'graph' | 'communities' | 'index';
-interface ImportProgress {
-    phase: ImportProgressPhase;
-    done: number;
-    total: number;
-}
-/** Per-entity import counts. */
-interface ImportCounts {
-    notes: number;
-    collections: number;
-    tags: number;
-    links: number;
-    embedding_sets: number;
-    embedding_set_members: number;
-    embeddings: number;
-    skos_schemes: number;
-    skos_concepts: number;
-    skos_relations: number;
-    note_skos_tags: number;
-    provenance_edges: number;
-    graph_sources: number;
-    graph_edges: number;
-    community_sets: number;
-    communities: number;
-    community_assignments: number;
-}
-/** Result of a shard import operation. */
-interface ImportResult {
-    success: boolean;
-    counts: ImportCounts;
-    skipped: Partial<ImportCounts>;
-    warnings: string[];
-    errors: string[];
-    duration_ms: number;
-}
-/** Note as serialized in the shard JSONL. */
-interface ShardNote {
-    id: string;
-    title: string | null;
-    original_content: string;
-    revised_content: string | null;
-    format: string;
-    source: string;
-    starred: boolean;
-    archived: boolean;
-    tags: string[];
-    created_at: string;
-    updated_at: string;
-    deleted_at: string | null;
-}
-/** Collection as serialized in the shard JSON array. */
-interface ShardCollection {
-    id: string;
-    name: string;
-    description: string | null;
-    parent_id: string | null;
-    created_at: string;
-    note_count?: number;
-}
-/** Tag as serialized in the shard JSON array. */
-interface ShardTag {
-    name: string;
-    created_at: string;
-}
-/** Link as serialized in the shard JSONL. */
-interface ShardLink {
-    id: string;
-    from_note_id: string;
-    to_note_id: string;
-    kind: string;
-    score: number | null;
-    created_at: string;
-    metadata?: Record<string, unknown>;
-}
-/** Embedding set as serialized in the shard JSON array. */
-interface ShardEmbeddingSet {
-    id: string;
-    name?: string;
-    purpose?: string | null;
-    model: string;
-    dimension: number;
-    kind?: 'physical' | 'filter' | 'virtual';
-    mode?: 'auto' | 'manual' | 'mixed' | null;
-    truncate_dimension?: number | null;
-    criteria?: Record<string, unknown> | null;
-    source?: Record<string, unknown> | null;
-    compatibility?: Record<string, unknown> | null;
-    materialization?: Record<string, unknown> | null;
-    freshness?: ShardArtifactFreshness | null;
-    created_at: string;
-    updated_at?: string;
-}
-/** Embedding set member as serialized in the shard JSONL. */
-interface ShardEmbeddingSetMember {
-    embedding_set_id: string;
-    note_id: string;
-    embedding_id: string;
-}
-/** Embedding as serialized in the shard JSONL. */
-interface ShardEmbedding {
-    id: string;
-    note_id: string;
-    embedding_set_id: string;
-    vector: number[];
-    created_at: string;
-}
-/** SKOS scheme as serialized in the shard JSON array. */
-interface ShardSkosScheme {
-    id: string;
-    title: string;
-    description: string | null;
-    created_at: string;
-    updated_at: string;
-}
-/** SKOS concept as serialized in the shard JSON array. */
-interface ShardSkosConcept {
-    id: string;
-    scheme_id: string;
-    pref_label: string;
-    alt_labels: string[];
-    definition: string | null;
-    created_at: string;
-    updated_at: string;
+    fortemiSecureStorage?: FortemiSecretStore;
 }
-/** SKOS concept relation as serialized in the shard JSONL. */
-interface ShardSkosRelation {
-    id: string;
-    source_concept_id: string;
-    target_concept_id: string;
-    relation_type: 'broader' | 'narrower' | 'related';
-    created_at: string;
+declare function getFortemiBridge(host?: FortemiBridgeHost | undefined): FortemiBridge | null;
+declare function getFortemiSecretStore(host?: FortemiBridgeHost | undefined): FortemiSecretStore | null;
+declare function hasFortemiSecureSecrets(host?: FortemiBridgeHost | undefined): Promise<boolean>;
+
+type CspDirectiveName = 'default-src' | 'base-uri' | 'object-src' | 'frame-ancestors' | 'img-src' | 'font-src' | 'style-src' | 'script-src' | 'connect-src' | 'worker-src' | 'manifest-src' | 'report-uri';
+type CspDirectives = Partial<Record<CspDirectiveName, string[]>>;
+interface PluginCspOptions {
+    scriptSrc?: string[];
+    connectSrc?: string[];
+    imgSrc?: string[];
+    styleSrc?: string[];
+    reportUri?: string;
+    extraDirectives?: CspDirectives;
 }
-/** Note-to-SKOS-concept assignment as serialized in the shard JSONL. */
-interface ShardNoteSkosTag {
-    id: string;
-    note_id: string;
-    concept_id: string;
-    created_at: string;
+interface PluginScriptPolicy {
+    allowedOrigins: string[];
+    allowedUrls?: string[];
+    requireSri?: boolean;
 }
-/** Provenance edge as serialized in the shard JSONL. */
-interface ShardProvenanceEdge {
-    id: string;
-    entity_type: string;
-    entity_id: string;
-    activity: string;
-    agent: string;
-    started_at: string;
-    ended_at: string | null;
-    attributes: Record<string, unknown> | null;
+interface PluginScriptDescriptor {
+    url: string;
+    integrity?: string;
+    crossOrigin?: 'anonymous' | 'use-credentials';
 }
-interface ShardArtifactFreshness {
-    status: 'fresh' | 'stale' | 'unknown';
-    checked_at?: string;
-    stale_reason?: string;
-    source_hashes?: {
-        notes?: string;
-        links?: string;
-        embeddings?: string;
-        embedding_set_members?: string;
-        virtual_set_definition?: string;
-        parameters?: string;
-    };
+interface LoadedPluginScript {
+    url: string;
+    integrity: string;
+    bytes: Uint8Array;
+    text: string;
+}
+interface CspViolationReport {
+    documentUri?: string;
+    violatedDirective?: string;
+    effectiveDirective?: string;
+    blockedUri?: string;
+    originalPolicy?: string;
+    disposition?: string;
+    sourceFile?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    raw: unknown;
 }
+declare function buildPluginCsp(options?: PluginCspOptions): string;
+declare function computeSri(data: Uint8Array | ArrayBuffer, algorithm?: string): Promise<string>;
+declare function verifySri(data: Uint8Array | ArrayBuffer, integrity: string): Promise<boolean>;
+declare function isPluginScriptAllowed(url: string, policy: PluginScriptPolicy): boolean;
+declare function fetchPluginScript(descriptor: PluginScriptDescriptor, policy: PluginScriptPolicy, fetchFn?: typeof fetch): Promise<LoadedPluginScript>;
+declare function appendPluginScript(descriptor: PluginScriptDescriptor, policy: PluginScriptPolicy, doc?: Document): Promise<HTMLScriptElement>;
+declare function parseCspReport(body: unknown): CspViolationReport;
+declare function createCspReportHandler(onReport: (report: CspViolationReport) => void | Promise<void>): (request: Request) => Promise<Response>;
 
 /**
  * Minimal tar + gzip packing/unpacking for shard archives.
@@ -2887,164 +3486,6 @@ declare function validateChecksums(checksums: Record<string, string>, files: Map
     failures: string[];
 }>;
 
-/**
- * Field mapper — converts between browser schema and shard (server) schema.
- *
- * The browser uses different field names than the server shard format.
- * This module handles all rename transforms bidirectionally.
- */
-
-/** Browser-format note row from the export query (denormalized). */
-interface BrowserNoteExport {
-    id: string;
-    title: string | null;
-    format: string;
-    source: string;
-    is_starred: boolean;
-    is_archived: boolean;
-    created_at: Date | string;
-    updated_at: Date | string;
-    deleted_at: Date | string | null;
-    original_content: string;
-    revised_content: string | null;
-    tags: string[];
-}
-/** Convert a browser note to shard format. */
-declare function noteToShard(note: BrowserNoteExport): ShardNote;
-/** Convert a shard note back to browser-insertable format. */
-declare function noteFromShard(shard: ShardNote): BrowserNoteExport;
-/** Convert a browser link to shard format. */
-declare function linkToShard(link: LinkRow): ShardLink;
-/** Convert a shard link back to browser-insertable format. */
-declare function linkFromShard(shard: ShardLink): {
-    id: string;
-    source_note_id: string;
-    target_note_id: string;
-    link_type: string;
-    confidence: number | null;
-    created_at: string;
-};
-/** Convert a browser collection to shard format. */
-declare function collectionToShard(collection: CollectionRow, noteCount?: number): ShardCollection;
-/** Convert a shard collection back to browser-insertable format. */
-declare function collectionFromShard(shard: ShardCollection): {
-    id: string;
-    name: string;
-    description: string | null;
-    parent_id: string | null;
-    created_at: string;
-};
-/**
- * Convert SKOS concepts + note_tag associations into shard flat tag format.
- * Shard tags are simple string arrays — deduplicated across all notes.
- */
-declare function tagsToShard(allTags: Array<{
-    name: string;
-    created_at: Date | string;
-}>): ShardTag[];
-/**
- * Convert shard flat tags to browser format for insertion.
- * Returns unique tag names ready for note_tag association.
- */
-declare function tagsFromShard(shardTags: ShardTag[]): string[];
-/** Convert a browser embedding_set to shard format. */
-declare function embeddingSetToShard(set: {
-    id: string;
-    name?: string;
-    purpose?: string | null;
-    model_name: string;
-    dimensions: number;
-    kind?: 'physical' | 'filter' | 'virtual';
-    mode?: 'auto' | 'manual' | 'mixed' | null;
-    truncate_dimension?: number | null;
-    criteria_json?: unknown | null;
-    source_json?: unknown | null;
-    compatibility_json?: unknown | null;
-    materialization_json?: unknown | null;
-    freshness_json?: unknown | null;
-    created_at: Date | string;
-    updated_at?: Date | string;
-}): ShardEmbeddingSet;
-/** Convert a shard embedding set back to browser format. */
-declare function embeddingSetFromShard(shard: ShardEmbeddingSet): {
-    id: string;
-    name: string;
-    purpose: string | null;
-    model_name: string;
-    dimensions: number;
-    kind: 'physical' | 'filter' | 'virtual';
-    mode: 'auto' | 'manual' | 'mixed' | null;
-    truncate_dimension: number | null;
-    criteria_json: string | null;
-    source_json: string | null;
-    compatibility_json: string | null;
-    materialization_json: string | null;
-    freshness_json: string | null;
-    created_at: string;
-    updated_at: string | null;
-};
-/** Convert a browser embedding_set_member to shard format. */
-declare function embeddingSetMemberToShard(member: {
-    embedding_set_id: string;
-    note_id: string;
-    embedding_id: string;
-}): ShardEmbeddingSetMember;
-/** Convert a browser embedding to shard format. */
-declare function embeddingToShard(emb: {
-    id: string;
-    note_id: string;
-    embedding_set_id: string;
-    vector: string | number[];
-    created_at: Date | string;
-}): ShardEmbedding;
-/** Convert a shard embedding back to browser format. */
-declare function embeddingFromShard(shard: ShardEmbedding): {
-    id: string;
-    note_id: string;
-    embedding_set_id: string;
-    vector: string;
-    created_at: string;
-};
-declare function skosSchemeToShard(scheme: {
-    id: string;
-    title: string;
-    description: string | null;
-    created_at: Date | string;
-    updated_at: Date | string;
-}): ShardSkosScheme;
-declare function skosConceptToShard(concept: {
-    id: string;
-    scheme_id: string;
-    pref_label: string;
-    alt_labels: string[] | string | null;
-    definition: string | null;
-    created_at: Date | string;
-    updated_at: Date | string;
-}): ShardSkosConcept;
-declare function skosRelationToShard(relation: {
-    id: string;
-    source_concept_id: string;
-    target_concept_id: string;
-    relation_type: 'broader' | 'narrower' | 'related';
-    created_at: Date | string;
-}): ShardSkosRelation;
-declare function noteSkosTagToShard(tag: {
-    id: string;
-    note_id: string;
-    concept_id: string;
-    created_at: Date | string;
-}): ShardNoteSkosTag;
-declare function provenanceEdgeToShard(edge: {
-    id: string;
-    entity_type: string;
-    entity_id: string;
-    activity: string;
-    agent: string;
-    started_at: Date | string;
-    ended_at: Date | string | null;
-    attributes: Record<string, unknown> | string | null;
-}): ShardProvenanceEdge;
-
 /**
  * Shard export pipeline — query all entities, serialize, pack into .shard archive.
  *
@@ -3080,6 +3521,49 @@ declare function exportShard(db: DatabaseClient, options?: ExportOptions): Promi
  */
 declare function importShard(db: DatabaseClient, data: Uint8Array | ArrayBuffer, options?: ImportOptions): Promise<ImportResult>;
 
+/**
+ * Pluggable semantic providers for the in-place shard reader (issue #189).
+ *
+ * The static-file tier is text/facets-only by default. Semantic is opt-in via a
+ * `StaticSemanticProvider`, with three tradeoff points the host chooses from:
+ *
+ *   1. none          — don't configure a provider (text/facets only). Lightest.
+ *   2. cosine-small  — `createCosineSemanticProvider`: brute-force cosine over a
+ *                      small static vectors file. Zero prebuild; small corpora only.
+ *   3. ANN-full      — implement `StaticSemanticProvider` yourself over a prebuilt
+ *                      ANN snapshot (HNSW / flat-IVF served as a static asset),
+ *                      loading it in `prepare()` and querying it in `search()`.
+ *                      The interface is the extension point; no ANN engine is
+ *                      bundled here.
+ */
+
+/** A note id paired with its embedding vector, as stored in a static vectors file. */
+interface VectorEntry {
+    id: string;
+    vector: number[];
+}
+interface CosineSemanticProviderOptions {
+    /**
+     * Embeds the query into the SAME space as the corpus vectors. Host-owned so it
+     * matches the build-time embedding model exactly (sync or async).
+     */
+    embedQuery: (query: string) => Promise<number[]> | number[];
+    /**
+     * JSONL file (one `{ id, vector }` per line) mapping note id → vector, served
+     * as a static asset alongside the shard. Default `vectors.jsonl`.
+     */
+    vectorsFile?: string;
+    /** Pre-supplied vectors — skips loading from the component store. */
+    vectors?: VectorEntry[];
+}
+/**
+ * Brute-force cosine semantic provider — the "cosine-small" tradeoff point. Loads
+ * a static vectors file and scores the query embedding against every corpus
+ * vector. Fine for small/demo corpora; for the full corpus, supply a prebuilt-ANN
+ * `StaticSemanticProvider` instead.
+ */
+declare function createCosineSemanticProvider(options: CosineSemanticProviderOptions): StaticSemanticProvider;
+
 /**
  * Shard warm / prefetch API — pre-stage and (optionally) verify shard bytes
  * without building the index.
@@ -3205,4 +3689,4 @@ declare function clearPrefetchedShard(url?: string): void;
 
 declare const VERSION = "2026.6.4";
 
-export { type ArchiveInfo, ArchiveManager, type AttachInput, type AttachmentBlobRow, type AttachmentRow, AttachmentsRepository, type BlobStore, type BridgeCapability, type BridgeProviderInfo, type BrowserNoteExport, CURRENT_SHARD_VERSION, type CapabilityInfo, CapabilityManager, type CapabilityName, type CapabilityState, type CaptureKnowledgeInput, CaptureKnowledgeInputSchema, type CaptureKnowledgeResult, type CollectionCreateInput, type CollectionRow, CollectionsRepository, CommunitiesRepository, type CommunityAssignmentView, type CommunityCreateInput, type CommunityFilterDefinition, type CommunityGraph, type CommunityOptions, type CommunitySourceDescriptor, type CommunitySourceType, type CommunitySummary, type CompletionRequest, type CompletionResponse, type ConditionResult, type ConflictStrategy, type CooldownConfig, type CooldownEvent, type CspDirectiveName, type CspDirectives, type CspViolationReport, type DatabaseClient, type DiscoveredProvider, type DiscoveryOptions, EMBED_REQUEST_KIND, EMBED_RESPONSE_KIND, type EmbedFunction, type EmbedRequest, type EmbedRequestMessage, type EmbedResponse, type EmbedResponseMessage, type EmbedTransportPort, type EmbedWorkerOptions, type EmbeddingCompatibilityPolicy, type EmbeddingSetCreateInput, type EmbeddingSetCriteria, type EmbeddingSetDescriptor, type EmbeddingSetEmbeddingInput, type EmbeddingSetFreshness, type EmbeddingSetKind, type EmbeddingSetMode, type EmbeddingSetRow, type EmbeddingSetSelector, EmbeddingSetsRepository, type EnqueueJobInput, type ErrorCategory, type EventMap, type ExportOptions, type FallbackEvent, FallbackRouter, type FallbackRouterConfig, type FortemiBridge, type FortemiBridgeCapabilities, type FortemiBridgeHost, type FortemiConfig, type FortemiCore, type FortemiInferenceRouter, type FortemiSecretStore, type FortemiToolDefinition, FortemiToolManifest, type GetNoteInput, GetNoteInputSchema, type GpuCapabilities, type GraphCommunity, type GraphEdge, type GraphNode, GraphRepository, type IDisposable, type ImportCounts, type ImportOptions, type ImportProgress, type ImportProgressPhase, type ImportResult, type InferenceCapabilities, type InferenceProvider, JOB_CAPABILITIES, JOB_PRIORITIES, type JobQueueOptions, JobQueueWorker, type JobStatus, type JobType, LOCAL_ENDPOINTS, type LinkRow, LinksRepository, type ListNotesInput, ListNotesInputSchema, type LlmCapabilityOptions, type LlmCompleteFn, type LoadedPluginScript, type LocalEndpoint, type ManageArchiveInput, ManageArchiveInputSchema, type ManageArchiveResult, type ManageAttachmentsInput, ManageAttachmentsInputSchema, type ManageAttachmentsResult, type ManageCapabilitiesInput, ManageCapabilitiesInputSchema, type ManageCapabilitiesResult, type ManageCollectionsInput, ManageCollectionsInputSchema, type ManageCollectionsResult, type ManageLinksInput, ManageLinksInputSchema, type ManageLinksResult, type ManageNoteInput, ManageNoteInputSchema, type ManageNoteResult, type ManageTagsInput, ManageTagsInputSchema, type ManageTagsResult, MemoryBlobStore, type Migration, MigrationRunner, type ModelCategory, type ModelFitResult, type ModelInfo, type NoteCreateInput, type NoteFull, type NoteListOptions, type NoteRevision, type NoteSummary, type NoteUpdateInput, NotesRepository, OpenAICompatibleProvider, type OpenAIProviderConfig, PGliteStorageBackend, PGliteStorageBackendFactory, PGliteWorkerClient, PGliteWorkerStorageBackend, PGliteWorkerStorageBackendFactory, type PGliteWorkerStorageBackendFactoryOptions, type PaginatedResult, type PersistenceMode, type PluginCspOptions, type PluginScriptDescriptor, type PluginScriptPolicy, type PrefetchOptions, type PrefetchResult, type ProbeResult, type ProbeStatus, type ProviderCapabilities, ProviderRegistry, type ProviderTier, type QueryExecutor, type QueryResult, type RecommendedTier, type ResolvedEmbeddingRow, type ResolvedEmbeddingSet, type RouteHandler, SHARD_FORMAT, type SWRegistrationResult, type SearchFacets, type SearchInput, SearchInputSchema, type SearchOptions, SearchRepository, type SearchResponse, type SearchResult, type ShardCollection, type ShardComponent, type ShardEmbedding, type ShardEmbeddingSet, type ShardEmbeddingSetMember, type ShardLink, type ShardManifest, type ShardNote, type ShardNoteSkosTag, type ShardProvenanceEdge, type ShardSkosConcept, type ShardSkosRelation, type ShardSkosScheme, type ShardTag, type SimilarityGraphCacheKey, type SimilarityGraphOptions, type SimilarityGraphRequest, type SimilarityGraphResult, type SkosConcept, type SkosRelation, SkosRepository, type SkosScheme, type StorageBackend, type StorageBackendFactory, type StorageOpenRequest, type StorageTopology, type StreamChunk, TagsRepository, TransactionProxy, TypedEventBus, VERSION, type VirtualEmbeddingSetDefinition, type VirtualEmbeddingSetSource, type VirtualEmbeddingSetValidationError, type VirtualMaterializationPolicy, type VramTier, type WorkerRequest, type WorkerResponse, aiRevisionHandler, allMigrations, appendPluginScript, buildNoteConditions, buildPluginCsp, captureKnowledge, chunkText, classifyError, classifyModel, clearPrefetchedShard, collectionFromShard, collectionToShard, computeHash, computeSri, conceptTaggingHandler, cosineSimilarity, createBlobStore, createCspReportHandler, createFortemi, createLegacyProvider, createPGliteInstance, createRoutes, createWorkerEmbedFunction, defaultStorageBackendFactory, detectCommunities, detectGpuCapabilities, detectInferenceCapabilities, discoverLocalProviders, embeddingFromShard, embeddingGenerationHandler, embeddingSetFromShard, embeddingSetMemberToShard, embeddingSetToShard, embeddingToShard, enqueueFullWorkflow, enqueueJob, enqueueNoteCreationJobs, estimateModelFit, estimateVramMB, estimateVramTier, exportShard, fetchPluginScript, fortemiManifest, fromPrefetched, generateId, getEmbedFunction, getFortemiBridge, getFortemiSecretStore, getJobQueueStatus, getLlmFunction, getNote, getPrefetchedSha256, handleEmbedRequests, hasFortemiSecureSecrets, importShard, isPluginScriptAllowed, isShardPrefetched, linkFromShard, linkToShard, linkingHandler, listNotes, manageArchive, manageAttachments, manageCapabilities, manageCollections, manageLinks, manageNote, manageTags, matchRoute, noteFromShard, noteSkosTagToShard, noteToShard, packTarGz, parseCspReport, prefetchShard, provenanceEdgeToShard, registerLlmCapability, registerSemanticCapability, registerSemanticCapabilityWorker, registerServiceWorker, searchTool, selectLlmModel, setEmbedFunction, setLlmFunction, sha256Hex, skosConceptToShard, skosRelationToShard, skosSchemeToShard, suggestTags, tagsFromShard, tagsToShard, titleGenerationHandler, unpackTarGz, unregisterLlmCapability, unregisterSemanticCapability, validateChecksums, verifySri };
+export { type ArchiveInfo, ArchiveManager, type AttachInput, type AttachmentBlobRow, type AttachmentRow, AttachmentsRepository, type BackendCandidate, type BackendCapabilities, type BackendListOptions, type BackendNote, type BackendNoteFull, type BackendRequest, type BackendSearchHit, type BackendSearchQueryOptions, type BackendSearchResult, type BackendSelection, type BackendSemanticTier, type BackendStartupCost, type BlobStore, type BridgeCapability, type BridgeProviderInfo, type BrowserNoteExport, CURRENT_MIGRATION_HEAD, CURRENT_SHARD_VERSION, type CapabilityInfo, CapabilityManager, type CapabilityName, type CapabilityState, type CaptureKnowledgeInput, CaptureKnowledgeInputSchema, type CaptureKnowledgeResult, type CollectionCreateInput, type CollectionRow, CollectionsRepository, CommunitiesRepository, type CommunityAssignmentView, type CommunityCreateInput, type CommunityFilterDefinition, type CommunityGraph, type CommunityOptions, type CommunitySourceDescriptor, type CommunitySourceType, type CommunitySummary, type CompletionRequest, type CompletionResponse, type ConditionResult, type ConflictStrategy, type CooldownConfig, type CooldownEvent, type CosineSemanticProviderOptions, type CreatePGliteOptions, type CspDirectiveName, type CspDirectives, type CspViolationReport, DB_SNAPSHOT_SCHEMA_VERSION, type DataBackend, type DatabaseClient, type DbSnapshot, type DbSnapshotCompat, type DbSnapshotCompression, type DbSnapshotExpectations, type DbSnapshotMeta, type DbSnapshotSource, DbSnapshotVersionError, type DiscoveredProvider, type DiscoveryOptions, type DumpDbSnapshotOptions, type DumpableDb, EMBED_REQUEST_KIND, EMBED_RESPONSE_KIND, type EmbedFunction, type EmbedRequest, type EmbedRequestMessage, type EmbedResponse, type EmbedResponseMessage, type EmbedTransportPort, type EmbedWorkerOptions, type EmbeddingCompatibilityPolicy, type EmbeddingSetCreateInput, type EmbeddingSetCriteria, type EmbeddingSetDescriptor, type EmbeddingSetEmbeddingInput, type EmbeddingSetFreshness, type EmbeddingSetKind, type EmbeddingSetMode, type EmbeddingSetRow, type EmbeddingSetSelector, EmbeddingSetsRepository, type EnqueueJobInput, type ErrorCategory, type EventMap, type ExportOptions, type FallbackEvent, FallbackRouter, type FallbackRouterConfig, type FortemiBridge, type FortemiBridgeCapabilities, type FortemiBridgeHost, type FortemiConfig, type FortemiCore, type FortemiInferenceRouter, type FortemiSecretStore, type FortemiToolDefinition, FortemiToolManifest, type GetNoteInput, GetNoteInputSchema, type GpuCapabilities, type GraphCommunity, type GraphEdge, type GraphNode, GraphRepository, type IDisposable, type ImportCounts, type ImportOptions, type ImportProgress, type ImportProgressPhase, type ImportResult, type InferenceCapabilities, type InferenceProvider, JOB_CAPABILITIES, JOB_PRIORITIES, type JobQueueOptions, JobQueueWorker, type JobStatus, type JobType, LOCAL_ENDPOINTS, type LinkRow, LinksRepository, type ListNotesInput, ListNotesInputSchema, type LlmCapabilityOptions, type LlmCompleteFn, type LoadedPluginScript, type LocalEndpoint, type ManageArchiveInput, ManageArchiveInputSchema, type ManageArchiveResult, type ManageAttachmentsInput, ManageAttachmentsInputSchema, type ManageAttachmentsResult, type ManageCapabilitiesInput, ManageCapabilitiesInputSchema, type ManageCapabilitiesResult, type ManageCollectionsInput, ManageCollectionsInputSchema, type ManageCollectionsResult, type ManageLinksInput, ManageLinksInputSchema, type ManageLinksResult, type ManageNoteInput, ManageNoteInputSchema, type ManageNoteResult, type ManageTagsInput, ManageTagsInputSchema, type ManageTagsResult, MemoryBlobStore, type Migration, MigrationRunner, type ModelCategory, type ModelFitResult, type ModelInfo, type NoteCreateInput, type NoteFull, type NoteListOptions, type NoteRevision, type NoteSummary, type NoteUpdateInput, NotesRepository, OpenAICompatibleProvider, type OpenAIProviderConfig, type OpenShardOptions, type PGliteBackendOptions, PGliteStorageBackend, PGliteStorageBackendFactory, PGliteWorkerClient, PGliteWorkerStorageBackend, PGliteWorkerStorageBackendFactory, type PGliteWorkerStorageBackendFactoryOptions, type PaginatedResult, type PersistenceMode, type PluginCspOptions, type PluginScriptDescriptor, type PluginScriptPolicy, type PrefetchOptions, type PrefetchResult, type ProbeResult, type ProbeStatus, type ProviderCapabilities, ProviderRegistry, type ProviderTier, type QueryExecutor, type QueryResult, type RecommendedTier, type ResolvedEmbeddingRow, type ResolvedEmbeddingSet, type RestoreDbSnapshotOptions, type RouteHandler, SHARD_FORMAT, SUPPORTED_PGLITE_VERSION, type SWRegistrationResult, type SearchFacets, type SearchInput, SearchInputSchema, type SearchOptions, SearchRepository, type SearchResponse, type SearchResult, type ShardBackendOptions, type ShardClusterRef, type ShardCollection, type ShardComponent, type ShardComponentStore, type ShardEmbedding, type ShardEmbeddingSet, type ShardEmbeddingSetMember, type ShardLayout, type ShardLink, type ShardListOptions, type ShardManifest, type ShardNote, type ShardNoteFull, type ShardNoteSkosTag, type ShardProvenanceEdge, type ShardReader, type ShardReaderNote, type ShardReaderSource, type ShardSearchOptions, type ShardSearchRankedNote, type ShardSearchResult, type ShardSearchWeights, type ShardSkosConcept, type ShardSkosRelation, type ShardSkosScheme, type ShardTag, type SimilarityGraphCacheKey, type SimilarityGraphOptions, type SimilarityGraphRequest, type SimilarityGraphResult, type SkosConcept, type SkosRelation, SkosRepository, type SkosScheme, type StaticSemanticProvider, type StorageBackend, type StorageBackendFactory, type StorageOpenRequest, type StorageTopology, type StreamChunk, TagsRepository, TransactionProxy, TypedEventBus, VERSION, type VectorEntry, type VirtualEmbeddingSetDefinition, type VirtualEmbeddingSetSource, type VirtualEmbeddingSetValidationError, type VirtualMaterializationPolicy, type VramTier, type WorkerRequest, type WorkerResponse, aiRevisionHandler, allMigrations, appendPluginScript, buildNoteConditions, buildPluginCsp, captureKnowledge, chunkText, classifyError, classifyModel, clearPrefetchedShard, collectionFromShard, collectionToShard, computeHash, computeSri, conceptTaggingHandler, cosineSimilarity, createBlobStore, createCosineSemanticProvider, createCspReportHandler, createFortemi, createLegacyProvider, createPGliteBackend, createPGliteInstance, createRoutes, createShardBackend, createWorkerEmbedFunction, defaultStorageBackendFactory, detectCommunities, detectGpuCapabilities, detectInferenceCapabilities, discoverLocalProviders, dumpDbSnapshot, embeddingFromShard, embeddingGenerationHandler, embeddingSetFromShard, embeddingSetMemberToShard, embeddingSetToShard, embeddingToShard, enqueueFullWorkflow, enqueueJob, enqueueNoteCreationJobs, estimateModelFit, estimateVramMB, estimateVramTier, exportShard, fetchPluginScript, fortemiManifest, fromPrefetched, generateId, getEmbedFunction, getFortemiBridge, getFortemiSecretStore, getJobQueueStatus, getLlmFunction, getNote, getPrefetchedSha256, handleEmbedRequests, hasFortemiSecureSecrets, importShard, isPluginScriptAllowed, isShardPrefetched, linkFromShard, linkToShard, linkingHandler, listNotes, manageArchive, manageAttachments, manageCapabilities, manageCollections, manageLinks, manageNote, manageTags, matchRoute, noteFromShard, noteSkosTagToShard, noteToShard, openShard, packTarGz, parseCspReport, prefetchShard, provenanceEdgeToShard, registerLlmCapability, registerSemanticCapability, registerSemanticCapabilityWorker, registerServiceWorker, restoreDbSnapshot, searchTool, selectBackend, selectLlmModel, setEmbedFunction, setLlmFunction, sha256Hex, skosConceptToShard, skosRelationToShard, skosSchemeToShard, suggestTags, tagsFromShard, tagsToShard, titleGenerationHandler, unpackTarGz, unregisterLlmCapability, unregisterSemanticCapability, validateChecksums, verifyDbSnapshotMeta, verifySri };