@hviana/sema 0.4.1 → 0.4.2

package/dist/src/mind/types.d.ts

@@ -1,323 +0,0 @@
-import type { Vec } from "../vec.js";
-import type { Sema } from "../sema.js";
-import type { BoundedMap, Store } from "../store.js";
-import type { Space } from "../sema.js";
-import type { Alphabet } from "../alphabet.js";
-import type { MindConfig } from "../config.js";
-import type { Meter } from "../meter.js";
-import type { GraphSearch, Leaf, Seg, Site } from "./graph-search.js";
-import type { Rationale } from "./rationale.js";
-import type { Grid, StableFold } from "../geometry.js";
-/** One {@link MindContext._depositTrees} entry — see that field's doc. */
-export interface DepositCacheEntry {
-    /** Turn boundaries accumulated over this content's deposit chain —
-     *  strictly increasing proper offsets, each a previously-deposited
-     *  whole-context length.  Empty for a first-seen (single-turn) input. */
-    boundaries: number[];
-    /** Stable-prefix segment folds (grown-context inputs only). */
-    stable?: StableFold;
-    /** The continuation bytes this ctxInput was paired with in ingestPair, if
-     *  any — the ONLY thing that makes a later, longer ctxInput a genuine next
-     *  TURN of the same conversation rather than an unrelated fact that
-     *  happens to share this one's byte prefix (e.g. "2+2" vs. "2+2=5").  A
-     *  later deposit only takes this entry as its stable-prefix `prev` when
-     *  its own suffix bytes-equal this exactly. */
-    nextBytes?: Uint8Array;
-}
-export type Input = string | Uint8Array | Grid | Grid[];
-/** The host capabilities GraphSearch consults during a cover.  MindContext
- *  extends this so the Mind can pass itself as the host. */
-export interface GraphSearchHost {
-    /** Work accumulator, or null/absent when nothing is profiling — see
-     *  src/meter.ts.  Declared here (not only on MindContext) so the graph
-     *  search can report its chart effort without importing mind code. */
-    readonly meter?: Meter | null;
-    resolve(bytes: Uint8Array): number | null;
-    recogniseSpan?(bytes: Uint8Array): {
-        sites: ReadonlyArray<Site>;
-        leaves: ReadonlyArray<Leaf>;
-        splits: ReadonlySet<number>;
-        starts: ReadonlySet<number>;
-    };
-    chooseNext?(node: number): number | undefined;
-}
-export interface Recognition {
-    /** Forms that can lead somewhere — they have an edge or a halo. */
-    sites: Site[];
-    /** The query's perceived leaves (the search's covering axioms). */
-    leaves: Leaf[];
-    /** Sub-leaf positions where a form boundary falls between leaf edges. */
-    splits: Set<number>;
-    /** Leaf-parent (chunk) start positions from the query's OWN perceived
-     *  fold — the positions the fold itself chose as a grouping boundary, as
-     *  opposed to an offset a byte-level scan merely happens to land on.  The
-     *  one boundary signal opportunistic cross-leaf recovery (recognition's
-     *  own canonical chains, the search's `fuse`) can lean on instead of
-     *  ASCII/word heuristics: see the `boundary` gate in recognition.ts. */
-    starts: Set<number>;
-}
-/** How the consensus climb weights a region's Document-Frequency reach. */
-export type DFMode = "inverse" | "direct" | "combined";
-/** One POINT OF ATTENTION the consensus climb resolved. */
-export interface Attention {
-    /** The learnt context this point resolves to. */
-    anchor: number;
-    /** IDF-weighted consensus vote — the strength that orders points. */
-    vote: number;
-    /** The union of the query byte-spans whose evidence supports this point. */
-    start: number;
-    end: number;
-    /** SCALE-INVARIANT confidence: the fraction of the query's OWN regions
-     *  whose evidence this point accounts for (Σ RegionVote.absorbed among
-     *  its contributors, over the query's total region count) — read PER-
-     *  ANCHOR, unlike the raw IDF vote (an absolute, ln(N)-scaled quantity
-     *  that means "strong" on a small store and "weak" on a large one for
-     *  the SAME degree of genuine consensus).  A point whose breadth clears
-     *  `dominates` (> half the query's regions corroborate it) is real
-     *  consensus; one that does not is a coincidental single-region echo —
-     *  see test/35-attention-confidence.test.mjs. */
-    breadth: number;
-    /** DISPERSION: the number of distinct clusters this point's contributing
-     *  regions form, merging any two whose gap is under one river-fold
-     *  quantum W.  Neither breadth NOR raw region count discriminates a
-     *  genuine further topic from a coincidental echo (both were tried and
-     *  falsified — breadth starves a genuine, evenly-split multi-topic query,
-     *  since no root in a real N-way split can exceed half the vote; raw
-     *  count doesn't separate them either, since a short, structurally simple
-     *  echo racks up as many corroborating regions as a real topic does).
-     *  Dispersion asks a different question: not how MUCH evidence, but how
-     *  many separate PLACES in the query corroborate it.  A coincidental
-     *  match — one local phrase resonating with an unrelated stored form —
-     *  is structurally confined to ONE cluster no matter how strong its vote;
-     *  a genuine further topic is named in its own distinctive wording
-     *  somewhere the query's scaffolding does not reach, always a SEPARATE
-     *  cluster from whatever else corroborates it.  See
-     *  test/37-cluster-dispersion-fusion.test.mjs. */
-    clusters: number;
-}
-/** Both read-outs of one consensus climb. */
-export interface AttentionRead {
-    roots: Attention[];
-    ranked: Attention[];
-}
-/** A positioned region of a byte stream paired with its gist. */
-export interface Segment {
-    start: number;
-    end: number;
-    v: Vec;
-}
-/** A region of the query's perceived tree for the consensus climb. */
-export interface Region {
-    v: Vec;
-    start: number;
-    end: number;
-    chunk: boolean;
-    /** Whether the region's bytes resolve to a KNOWN node (content-addressed,
-     *  exact).  Exact regions vote with full weight; approximate ones pay the
-     *  contrastive margin (see voteRegions) — under the linear fold a raw
-     *  resonance score is byte-overlap, evidence only in excess of its best
-     *  rival conclusion. */
-    known: boolean;
-}
-/** Per-region vote data from the consensus climb's resonance pass. */
-export interface RegionVote {
-    start: number;
-    end: number;
-    canonicalFailed: boolean;
-    roots: readonly number[];
-    w: number;
-    wFocus: number;
-    /** How many of the query's ORIGINAL regions this one vote's evidence
-     *  accounts for.  1 for an ordinary per-region vote (itself); for a
-     *  cross-region junction vote, 1 (itself) plus however many individual
-     *  votes it explained away (see crossRegionVotes) — the junction speaks
-     *  for all of them at once, and breadth accounting must not undercount it
-     *  to "one region" just because it collapsed to one pooled axiom.
-     *  Defaults to 1 when absent. */
-    absorbed?: number;
-    /** The SEPARATE query places this vote's evidence occupies, when that is
-     *  more than the one contiguous run [start, end].  A cross-region junction
-     *  vote is pooled as a single synthetic region spanning its endpoints and
-     *  the gap between them, so `[start, end]` reads as ONE place — yet the
-     *  vote exists precisely because two non-adjacent regions each voted and
-     *  only their conjunction resolved.  Cluster counting (Attention.clusters)
-     *  asks "how many separate places in the query corroborate this?", and
-     *  answering it from the merged span makes every joint binding look like a
-     *  single local neighbourhood; fusion's dispersion gate then drops it
-     *  unless it also explains most of the whole query, which a binding inside
-     *  a MULTI-topic query structurally cannot.  Absent for an ordinary
-     *  per-region vote, where the merged span already is the truth. */
-    parts?: readonly (readonly [number, number])[];
-}
-/** The structural gate that first decided an {@link edgeAncestors} climb was
- *  saturated (an abstention, not a discriminative conclusion) — pure
- *  instrumentation for {@link ClimbConsensusData}'s reach trace; it never
- *  feeds back into the climb itself. */
-export type SaturationReason = "byte-atom-commonality" | "predecessor-fan-in" | "distinct-context-limit" | "parent-fan-out" | "lateral-cone-limit";
-/** One saturation stop's provenance: which reason fired, at which node, the
- *  observed count against the bound that decided it. */
-export interface SaturationStop {
-    reason: SaturationReason;
-    node: number;
-    observed: number;
-    limit: number;
-}
-/** The edge-bearing contexts reached by climbing from a node, plus saturation info. */
-export interface AncestorReach {
-    roots: number[];
-    contextsReached: number;
-    saturated: boolean;
-    /** The saturation gate that stopped this climb, when {@link saturated} is
-     *  true and a trace was requested — see {@link edgeAncestors}.  Absent for
-     *  a non-saturated reach, and absent (even when saturated) when no trace
-     *  was requested — instrumentation must not allocate when tracing is off. */
-    saturation?: SaturationStop;
-    /** The number of nodes the climb actually PROCESSED (popped and examined
-     *  by its visit step; a transparent chain counts as its one terminal).
-     *  Present only when a trace was requested — same contract as
-     *  {@link saturation}: instrumentation must not allocate when tracing is
-     *  off.  Purely a read-out; the climb never consults it. */
-    visited?: number;
-    /** The maximum structural ascent distance (in parent/containment hops,
-     *  transparent-chain interiors counted) from the start node among the
-     *  processed nodes.  Present only when a trace was requested — see
-     *  {@link visited}. */
-    maxDepth?: number;
-}
-/** Saturated-interval information for the noise-drop gate. */
-export interface SaturationInfo {
-    leadingEnd: number;
-    hasLeading: boolean;
-    intervals: Array<{
-        start: number;
-        end: number;
-    }>;
-}
-/** The items of poolVotes' deduction system. */
-export type AItem = {
-    kind: "region";
-    ri: number;
-} | {
-    kind: "anchor";
-    id: number;
-} | {
-    kind: "anchorFocus";
-    id: number;
-};
-export interface MindContext extends GraphSearchHost {
-    store: Store;
-    /** The work accumulator for the inference call in flight, or null when
-     *  nothing is profiling — see src/meter.ts.  WRITE-ONLY from the engine's
-     *  point of view: no inference decision may read a counter, or the
-     *  determinism contract (AGENTS §2.1) is gone.  Every call site is
-     *  `ctx.meter?.x++`, so an unprofiled response allocates nothing. */
-    meter: Meter | null;
-    space: Space;
-    alphabet: Alphabet;
-    cfg: MindConfig;
-    search: GraphSearch;
-    trace: Rationale | null;
-    /** The content canonicalizer for THIS response, or null — injected by the
-     *  modality entry point (respondText passes the text canonicalizer; a
-     *  binary respond passes none).  Resolution uses it as a fallback: when
-     *  the exact content-addressed lookup misses, the span's canonical key is
-     *  probed against the store's canon index (see src/canon.ts).  The core
-     *  never inspects what the equivalence IS. */
-    canon: ((bytes: Uint8Array) => Uint8Array) | null;
-    /** Per-response memo of canonical-fallback resolutions, keyed by the
-     *  span's latin1 content key.  Null outside respond(). */
-    canonMemo: Map<string, number | null> | null;
-    /** Memo of the consensus climb — content-keyed (latin1) so results
-     *  persist across conversation turns where the same byte spans recur.
-     *  Null outside respond(); during respondTurn() the conversation's
-     *  persistent map is swapped in. */
-    climbMemo: Map<string, Map<string, AttentionRead>> | null;
-    /** Memo of {@link recognise} — content-keyed (latin1) so recognised
-     *  forms carry forward across conversation turns.  Bypassed while a
-     *  trace is attached.  Null outside respond(). */
-    recogniseMemo: Map<string, Recognition> | null;
-    /** Memo of {@link perceive} — content-keyed (latin1).  The general
-     *  cache the result-level memos each partially compensate for.  NOT
-     *  bypassed under trace — perception emits no rationale steps.
-     *  Null outside respond(). */
-    perceiveMemo: Map<string, Sema> | null;
-    /** Subtree-resolution cache: Sema node → its store id and byte length.
-     *  Populated by {@link foldTree} during inference; checked before
-     *  walking children.  When a conversation's pyramid reuses prefix
-     *  subtrees, this cache lets {@link recognise} skip them entirely —
-     *  O(suffix) instead of O(context).  Mind-lifetime (WeakMap keys are
-     *  the Sema objects the pyramid keeps alive). */
-    _resolvedSubtrees: WeakMap<Sema, {
-        id: number;
-        len: number;
-    }> | null;
-    _edgeGuide: Vec | null;
-    _edgeChoice: Map<number, number>;
-    _prevSeen: Set<number> | null;
-    /** Session cache of node-id → perceived gist, for candidate scoring
-     *  ({@link chooseAmong} in the reverse projection's recall path re-gists up to
-     *  √N contexts per pick — the measured bottleneck there).  `chooseNext` does
-     *  NOT use this cache; forward-edge disambiguation uses prevOf counts
-     *  (distributional evidence) instead of gist comparison, because for short
-     *  answer candidates the gist is dominated by accidental byte-pattern
-     *  correlations.  A node's bytes are immutable and perception is a pure
-     *  function of bytes, so an entry stays valid for the store's lifetime —
-     *  never invalidated.  Bounded LRU (byte-sized); a miss only re-perceives,
-     *  never a correctness risk. */
-    _gistCache: BoundedMap<number, Vec>;
-    /** DEPOSIT-path perception cache: content key (latin1) of a deposited
-     *  input → its accumulated turn BOUNDARIES plus reusable fold state.  A
-     *  deposit whose content extends a cached entry IS a conversation context
-     *  grown by one turn — the cached length is the new boundary — so it
-     *  folds with the SAME stable-prefix fold query-time perception uses
-     *  (structural train/inference agreement, load-bearing for recall),
-     *  reusing every already-folded segment via `stable` (see StableFold) —
-     *  O(turn) per deposit instead of O(context).  A first-seen input takes the
-     *  same fold with no boundaries at all, and caches the segments it produced
-     *  so a later turn of the same conversation reuses them.  Purely a
-     *  performance cache for the FOLD STATE; the boundaries are semantic but
-     *  derived only from the deposit sequence itself (an evicted chain falls
-     *  back to plain-fold behavior, exactly the pre-boundary shape). */
-    _depositTrees: BoundedMap<string, DepositCacheEntry>;
-    /** The byte lengths present in {@link _depositTrees} — the candidate
-     *  prefix lengths probed (longest first).  Drifts on eviction (a stale
-     *  length only costs a miss); cleared with the map when it outgrows the
-     *  probe budget. */
-    _depositLens: Set<number>;
-    /** Mind-lifetime intern memo by NODE IDENTITY: perceived-tree node → its
-     *  content-addressed id.  Valid forever (ids are permanent, Sema nodes
-     *  immutable); WeakMap, so entries live exactly as long as the pyramid
-     *  cache keeps the shared subtrees alive.  Lets internTreeIds skip whole
-     *  shared subtrees and indexSubSpans keep its seenBefore window skip. */
-    _internIds: WeakMap<Sema, number>;
-}
-/** Read a whole node's bytes. */
-export declare const ALL = 2147483647;
-/** Splice every chosen span in order — the whole cover as one byte string. */
-export declare function spliceAll(segs: Seg[]): Uint8Array | null;
-/** Whether a chosen span RESTATES the query rather than answering it: its
- *  SUBSTITUTED bytes (an edge followed from a recognised site, not the
- *  site's own literal text read back) already occur elsewhere in the query
- *  — the same principle recall.ts's tiers apply to a whole-query projection
- *  ("a projection that is a proper byte-subspan of the query restates part
- *  of the question").  A LITERAL span (the site's own bytes, unchanged) is
- *  exempt: naming what's already there at its OWN position is not a
- *  substitution.  A recognised site that is itself an entire PRIOR TURN of
- *  a multi-turn query is exactly this shape: it carries a genuine learnt
- *  continuation, but that continuation is something the asker already said
- *  moments later in the SAME query, not a new answer.  Below one river
- *  window, byte overlap is chance, not evidence — the same floor
- *  identityBar and reachThreshold hold every other structural-overlap claim
- *  to. */
-export declare function segRestatesQuery(s: Seg, query: Uint8Array, queryLen: number, W: number): boolean;
-/** Lift the answer out of the cover for think: the recognised region, free of
- *  the asker's surrounding (unrecognised) framing — and free of any chosen
- *  span that only RESTATES content the query already contains (see {@link
- *  segRestatesQuery}).  A restating span is excluded from both the framing
- *  (lo/hi) decision and the final concatenation: it is stale, not a second
- *  answer, but the OTHER spans a derivation chose are independent evidence
- *  and must not be discarded along with it. */
-export declare function liftAnswer(segs: Seg[], queryLen: number, query: Uint8Array, W: number): Uint8Array | null;
-/** The CHANGED NODES of a freshly-perceived `tree` against the node ids a previous
- *  tracked deposit interned (`prevSeen`). */
-export declare function changedNodes(tree: Sema, ids: Map<Sema, number>, prevSeen: Set<number>): Sema[];

package/dist/src/mind/types.js

@@ -1,130 +0,0 @@
-// types.ts — all interfaces, types, and free functions for the mind.
-//
-// GraphSearchHost is defined first (minimal imports) so GraphSearch can import
-// it without pulling in the full MindContext.
-import { bytesEqual, concatBytes, indexOf } from "../bytes.js";
-import { dominates } from "../geometry.js";
-// ═══════════════════════════════════════════════════════════════════════════
-// FREE FUNCTIONS (pure, no state)
-// ═══════════════════════════════════════════════════════════════════════════
-/** Read a whole node's bytes. */
-export const ALL = 0x7fffffff;
-/** Splice every chosen span in order — the whole cover as one byte string. */
-export function spliceAll(segs) {
-    if (!segs.some((s) => s.rec))
-        return null;
-    return concatBytes(segs.map((s) => s.bytes));
-}
-/** Whether a chosen span RESTATES the query rather than answering it: its
- *  SUBSTITUTED bytes (an edge followed from a recognised site, not the
- *  site's own literal text read back) already occur elsewhere in the query
- *  — the same principle recall.ts's tiers apply to a whole-query projection
- *  ("a projection that is a proper byte-subspan of the query restates part
- *  of the question").  A LITERAL span (the site's own bytes, unchanged) is
- *  exempt: naming what's already there at its OWN position is not a
- *  substitution.  A recognised site that is itself an entire PRIOR TURN of
- *  a multi-turn query is exactly this shape: it carries a genuine learnt
- *  continuation, but that continuation is something the asker already said
- *  moments later in the SAME query, not a new answer.  Below one river
- *  window, byte overlap is chance, not evidence — the same floor
- *  identityBar and reachThreshold hold every other structural-overlap claim
- *  to. */
-export function segRestatesQuery(s, query, queryLen, W) {
-    if (!s.rec)
-        return false;
-    const literal = s.j - s.i === s.bytes.length &&
-        bytesEqual(s.bytes, query.subarray(s.i, s.j));
-    if (literal)
-        return false;
-    return s.bytes.length >= W && s.bytes.length < queryLen &&
-        indexOf(query, s.bytes, 0) >= 0;
-}
-/** Lift the answer out of the cover for think: the recognised region, free of
- *  the asker's surrounding (unrecognised) framing — and free of any chosen
- *  span that only RESTATES content the query already contains (see {@link
- *  segRestatesQuery}).  A restating span is excluded from both the framing
- *  (lo/hi) decision and the final concatenation: it is stale, not a second
- *  answer, but the OTHER spans a derivation chose are independent evidence
- *  and must not be discarded along with it. */
-export function liftAnswer(segs, queryLen, query, W) {
-    const restated = segs.map((s) => segRestatesQuery(s, query, queryLen, W));
-    const recognised = [];
-    for (let k = 0; k < segs.length; k++) {
-        if (segs[k].rec && !restated[k])
-            recognised.push(k);
-    }
-    if (recognised.length === 0)
-        return null;
-    if (recognised.length === 1) {
-        const s = segs[recognised[0]];
-        // A COMPUTED span's query-side width is operand digit-count, not
-        // evidence of how much of the query's meaning it accounts for — the
-        // half-dominance check below (built for a genuinely RECOGNISED learned
-        // form) is not a valid framing signal for it (see the `computed` field
-        // doc on Seg/GItem): "1000 - 421" outweighs "what is …?" by width only
-        // because the operands are big, not because the framing matters less.
-        // A LITERAL PREFIX before a computed span is unambiguous framing
-        // regardless of width — an arithmetic expression is never itself
-        // preceded by more literal computed content, so anything literal before
-        // it is question wording ("what is ", "compute ") to lift clear of.
-        // With no prefix (s.i === 0) the span is judged by the ordinary
-        // half-dominance rule below, which already correctly keeps a short
-        // trailing glue byte ("2+2." → "4.", the span dominates a 4-byte query).
-        if (s.computed && s.i > 0)
-            return s.bytes;
-        if (dominates(s.j - s.i, queryLen)) {
-            return concatBytes(segs.filter((_, k) => !restated[k]).map((x) => x.bytes));
-        }
-        return s.bytes;
-    }
-    const lo = recognised[0];
-    const hi = recognised[recognised.length - 1];
-    return concatBytes(segs.slice(lo, hi + 1).filter((_, k) => !restated[lo + k]).map((x) => x.bytes));
-}
-/** The CHANGED NODES of a freshly-perceived `tree` against the node ids a previous
- *  tracked deposit interned (`prevSeen`). */
-export function changedNodes(tree, ids, prevSeen) {
-    const newCount = new Map();
-    const count = (n) => {
-        const memo = newCount.get(n);
-        if (memo !== undefined)
-            return memo;
-        const id = ids.get(n);
-        // PRUNE: a node whose id the previous deposit already interned is old,
-        // and content addressing makes that transitive — the same id names the
-        // same content, so every descendant was interned then too.  The whole
-        // subtree counts 0 without walking it; with the pyramid fold sharing a
-        // conversation's prefix subtree, this is what keeps the changed-nodes
-        // read O(new nodes) instead of O(context).  (A node internTreeIds
-        // memo-skipped has an id here exactly when it is such a shared root.)
-        if (id !== undefined && prevSeen.has(id)) {
-            newCount.set(n, 0);
-            return 0;
-        }
-        let c = 1; // reachable only when NOT pruned above ⇒ this node is new
-        if (n.kids) {
-            for (const k of n.kids)
-                c += count(k);
-        }
-        newCount.set(n, c);
-        return c;
-    };
-    const total = count(tree);
-    if (total === 0)
-        return [tree];
-    let n = tree;
-    for (;;) {
-        if (n.kids === null)
-            return [n];
-        let holder = null;
-        for (const k of n.kids) {
-            if (newCount.get(k) === total) {
-                holder = k;
-                break;
-            }
-        }
-        if (holder === null)
-            return [n];
-        n = holder;
-    }
-}

package/dist/src/rabitq-ivf/src/database.d.ts

@@ -1,113 +0,0 @@
-/** External ids are integers only. */
-export type ExternalId = number;
-export interface DatabaseOptions {
-    /** Path to the SQLite database file (use ":memory:" for a transient store). */
-    dbPath: string;
-    /** Vector dimensionality. Required for a new database; ignored when reopening. */
-    dim?: number;
-    /** Query breadth: clusters probed per query = ceil(efSearch / 4).  Default
-     *  64 (16 probes). Tunable at runtime and at reopen. */
-    efSearch?: number;
-    /** Bits used to scalar-quantise the query for the RaBitQ estimator.
-     *  Query-side only (stored codes are independent of it), so it is tunable
-     *  at reopen, like efSearch.  Default 8. */
-    queryBits?: number;
-    /** Number of sign-flip + Hadamard rounds in the random rotation. Default 3. */
-    rotationRounds?: number;
-    /** Seed for the rotation. Default fixed. */
-    seed?: number;
-    /** Optional centroid the vectors are centered by before quantisation. */
-    centroid?: ArrayLike<number>;
-    /** SQLite page-cache budget in MiB.  Purely a latency knob: correctness and
-     *  the per-operation storage-read count are identical with it at 0. */
-    cacheSizeMb?: number;
-}
-export interface QueryResult {
-    id: ExternalId;
-    /** Estimated cosine distance (1 - cosine). */
-    distance: number;
-}
-export interface StorageStats {
-    float32BytesPerVector: number;
-    codeBytesPerVector: number;
-    bytesPerVector: number;
-    compressionRatio: number;
-}
-/**
- * A persistent vector database: an adaptive PARTITIONED (IVF) index over
- * 1-bit RaBitQ codes (cosine), stored entirely in SQLite at `dbPath`.  See
- * ivf.ts for the index design.  The original float vectors are never
- * retained — only the sign codes — so a 1024-d vector costs 128 bytes.
- *
- * Inserting is route-and-append: cost is essentially FLAT in collection size
- * (one RAM scan of the pivot table + one chunk append — no per-insert graph
- * walk).  Query cost is bounded by nprobe × cluster size — constant in N
- * once the collection is past its first splits.
- */
-export declare class VectorDatabase {
-    private readonly index;
-    constructor(options: DatabaseOptions);
-    get dim(): number;
-    /** Number of live (non-deleted) vectors. */
-    get size(): number;
-    /** Physical slot count including tombstones from deletes/updates. */
-    get physicalSize(): number;
-    /** Number of clusters (partitions) currently in the index. */
-    get clusterCount(): number;
-    get efSearch(): number;
-    set efSearch(value: number);
-    /** Distance computations performed during the most recent query. */
-    get lastQueryDistanceComputations(): number;
-    /** Storage row reads issued by the most recent query — the honest,
-     *  cache-independent scalability metric. */
-    get lastQueryStorageReads(): number;
-    get storage(): StorageStats;
-    private checkId;
-    /** Convert a value to code bytes, selecting by length: `codeWords`
-     *  elements → an existing 1-bit code; otherwise a raw `dim`-vector. */
-    private toCodeBytes;
-    has(id: ExternalId): boolean;
-    /** Stream every live external id (bounded memory). */
-    keys(): IterableIterator<ExternalId>;
-    /** Stream live entries whose INTERNAL id is > `after` — a durable
-     *  incremental watermark (internal ids are monotone at insert and preserved
-     *  by update and compact). */
-    keysSince(after: number): IterableIterator<{
-        ext: ExternalId;
-        internal: number;
-    }>;
-    /** Read the stored 1-bit code for an id (a copy as a Uint32Array), or null. */
-    get(id: ExternalId): Uint32Array | null;
-    insert(id: ExternalId, value: ArrayLike<number>): void;
-    update(id: ExternalId, value: ArrayLike<number>): void;
-    upsert(id: ExternalId, value: ArrayLike<number>): void;
-    /**
-     * Upsert many vectors under ONE transaction — one WAL commit for the whole
-     * batch instead of one per vector, with chunk appends to the same cluster
-     * coalesced in the index's write-back buffer.
-     */
-    upsertMany(entries: Array<{
-        id: ExternalId;
-        vector: ArrayLike<number>;
-    }>): void;
-    /** Delete many ids under ONE transaction. Absent ids are skipped.
-     *  Returns the number of vectors actually removed. */
-    deleteMany(ids: ExternalId[]): number;
-    /** Delete the vector bound to an id. Returns false if absent. */
-    delete(id: ExternalId): boolean;
-    /** Heat the SQLite page cache with sequential scans (latency only). */
-    warmCache(): number;
-    /** Reclaim tombstoned slots by rewriting the clusters that carry any, then
-     *  VACUUM.  Internal ids and cluster assignment are preserved. */
-    compact(): void;
-    /**
-     * k-NN search. The argument's length selects the mode:
-     *  - `dim` elements       → a raw vector (accurate estimator)
-     *  - `codeWords` elements → a 1-bit code, by sign-bit Hamming
-     */
-    query(query: ArrayLike<number>, k?: number, opts?: {
-        ef?: number;
-    }): QueryResult[];
-    /** Close the underlying database. The instance must not be used afterwards. */
-    close(): void;
-}