@hviana/sema 0.1.3 → 0.1.5

package/dist/src/sema.d.ts

@@ -0,0 +1,35 @@
+import { Permutation, Vec } from "./vec.js";
+/** The one structure. A node's vector is the gist of its whole subtree; it also
+ *  carries the structure the DAG store interns — its leaf bytes, or its kids. */
+export interface Sema {
+  v: Vec;
+  leaf: Uint8Array | null;
+  kids: Sema[] | null;
+}
+export declare const sema: (
+  v: Vec,
+  leaf?: Uint8Array | null,
+  kids?: Sema[] | null,
+) => Sema;
+/** Whether a node is a CHUNK — a leaf-parent whose children are ALL leaves,
+ *  the perception tree's smallest grouped unit.  The one predicate behind
+ *  region collection, canonical segmentation seams, and sub-span indexing;
+ *  named here beside the type so no consumer restates the shape inline. */
+export declare const isChunk: (n: Sema) => n is Sema & {
+  kids: Sema[];
+};
+/** The medium: dimension, keyring, and noise source. */
+export interface Space {
+  D: number;
+  seats: Permutation[];
+  rand: () => number;
+  maxGroup: number;
+}
+/** Bind one vector into a seat — the elementary half of fold. Used to index an
+ *  episode from either side and to pour a partner into a form's halo. */
+export declare const bindSeat: (space: Space, v: Vec, seat: number) => Vec;
+/** The company signature of node `id` — the halo's pour unit (see above). */
+export declare function companySignature(space: Space, id: number): Vec;
+/** fold — combine ordered children into one gist.
+ *  Each child is turned with its seat's own key, superposed, normalized. */
+export declare function fold(space: Space, kids: Vec[]): Vec;

package/dist/src/sema.js

@@ -0,0 +1,77 @@
+import {
+  addInto,
+  normalize,
+  permute,
+  permuteInto,
+  randomUnit,
+  rng,
+  zeros,
+} from "./vec.js";
+export const sema = (v, leaf = null, kids = null) => ({ v, leaf, kids });
+/** Whether a node is a CHUNK — a leaf-parent whose children are ALL leaves,
+ *  the perception tree's smallest grouped unit.  The one predicate behind
+ *  region collection, canonical segmentation seams, and sub-span indexing;
+ *  named here beside the type so no consumer restates the shape inline. */
+export const isChunk = (n) =>
+  n.kids !== null && n.kids.every((k) => k.kids === null);
+// Reusable permute buffer for fold.
+let _foldBuf = null;
+/** Bind one vector into a seat — the elementary half of fold. Used to index an
+ *  episode from either side and to pour a partner into a form's halo. */
+export const bindSeat = (space, v, seat) => permute(v, space.seats[seat].fwd);
+// ── Company signatures ──────────────────────────────────────────────────
+//
+// A halo is a superposition of EPISODE SIGNATURES: it answers "who does this
+// form keep company with", and two forms share a concept when they keep the
+// SAME company (the same partner nodes).  Pouring the partner's raw GIST was
+// an approximation of that: it worked while the hierarchical fold decorrelated
+// unrelated gists quickly, but any byte-overlap between partners leaks CONTENT
+// similarity into COMPANY similarity, silently shifting the halo null model
+// that conceptThreshold's derivation (unrelated halos ⇒ cosine 0 ± 1/√D)
+// depends on.  A signature makes the semantics exact and fold-independent:
+// a deterministic unit vector derived from the partner's IDENTITY, so two
+// halos correlate exactly as much as their company overlaps — never because
+// their partners merely contain similar bytes.
+//
+// Seeded by node id: ids are content-addressed mint order, stable for a given
+// corpus (including checkpoint/resume, which re-derives identical ids), and
+// halos are per-store training artifacts that are never compared across
+// stores.
+const _sigCache = new WeakMap();
+const SIG_CACHE_MAX = 65_536;
+/** The company signature of node `id` — the halo's pour unit (see above). */
+export function companySignature(space, id) {
+  let cache = _sigCache.get(space);
+  if (!cache) {
+    _sigCache.set(space, cache = new Map());
+  }
+  const hit = cache.get(id);
+  if (hit) {
+    return hit;
+  }
+  const v = randomUnit(space.D, rng((id ^ 0x9e3779b9) >>> 0));
+  if (cache.size >= SIG_CACHE_MAX) {
+    cache.clear(); // flat cap; regeneration is cheap
+  }
+  cache.set(id, v);
+  return v;
+}
+/** fold — combine ordered children into one gist.
+ *  Each child is turned with its seat's own key, superposed, normalized. */
+export function fold(space, kids) {
+  if (kids.length > space.seats.length) {
+    throw new Error(
+      `fold: ${kids.length} children but the keyring has only ${space.seats.length} seats`,
+    );
+  }
+  const out = zeros(space.D);
+  if (!_foldBuf || _foldBuf.length !== space.D) {
+    _foldBuf = new Float32Array(space.D);
+  }
+  const buf = _foldBuf;
+  for (let i = 0; i < kids.length; i++) {
+    permuteInto(buf, kids[i], space.seats[i].fwd);
+    addInto(out, buf);
+  }
+  return normalize(out);
+}

package/dist/src/store-sqlite.d.ts

@@ -1,149 +1,171 @@
-import { AbstractStore, type NodeId, type NodeRec, type Store } from "./store.js";
+import {
+  AbstractStore,
+  type NodeId,
+  type NodeRec,
+  type Store,
+} from "./store.js";
 import { type StoreConfig } from "./config.js";
 export interface SQliteStoreOptions extends Partial<StoreConfig> {
-    path?: string;
-    D?: number;
-    /** Fold group size used during training — tells indexSubtree how tight the
-     *  reach-net epsilon should be (1 − 1/(2·maxGroup)). Defaults to the
-     *  Mind's geometry.maxGroup. */
-    maxGroup?: number;
-    /** Query-side RaBitQ estimator precision for both vector indices. */
-    queryBits?: number;
+  path?: string;
+  D?: number;
+  /** Fold group size used during training — tells indexSubtree how tight the
+   *  reach-net epsilon should be (1 − 1/(2·maxGroup)). Defaults to the
+   *  Mind's geometry.maxGroup. */
+  maxGroup?: number;
+  /** Query-side RaBitQ estimator precision for both vector indices. */
+  queryBits?: number;
 }
 export declare class SQliteStore extends AbstractStore implements Store {
-    private readonly opts;
-    private readonly vectorCacheMb;
-    private readonly vectorSeed;
-    private content;
-    private halos;
-    private sqlite;
-    private _inTx;
-    private _insertNode;
-    private _insertKid;
-    private _selContain;
-    private _selParents;
-    private _selHalo;
-    private _upHalo;
-    private _selLeaf;
-    private _selFlat;
-    private _selKids;
-    private _selNode;
-    private _insertEdge;
-    private _selNext;
-    private _selPrev;
-    private _setMeta;
-    private _getMeta;
-    private _delMeta;
-    private _insSnapshot;
-    private _selSnapshot;
-    constructor(opts?: SQliteStoreOptions);
-    private vectorDbPath;
-    private openVectorDB;
-    protected _dbOpen(): Promise<void>;
-    protected _dbClose(): void;
-    protected _dbBeginTx(): void;
-    protected _dbCommitTx(): void;
-    protected _dbInsertNode(id: NodeId, leaf: Uint8Array | null, kids: Uint8Array | null, h: number): void;
-    protected _dbGetNode(id: NodeId): NodeRec | null;
-    protected _dbFindLeaf(h: number, bytes: Uint8Array): NodeId | null;
-    protected _dbFindBranchByLeaf(h: number, bytes: Uint8Array): NodeId | null;
-    protected _dbFindBranchByKids(h: number, packed: Uint8Array): NodeId | null;
-    protected _dbInsertKid(child: NodeId, parent: NodeId): void;
-    protected _dbGetParents(id: NodeId): NodeId[];
-    private _selParentsFirst;
-    protected _dbGetParentsFirst(id: NodeId, limit: number): NodeId[];
-    private _selChain;
-    /** {@link Store.chainRun}'s walk as ONE recursive CTE: the whole
-     *  transparent chain (no edge in or out, exactly one parent) is descended
-     *  inside SQLite — per-node work is the same three indexed probes as the
-     *  base class's loop, but without a JS↔SQLite round trip per node, which
-     *  dominates on the deep single-structure scaffolding this read exists
-     *  for. */
-    protected _chainWalk(id: NodeId, cap: number): NodeId[];
-    /** Width of the seq band inside the packed contain rowid: rowid =
-     *  child·SEQ_SPAN + seq.  Page sizes are geometric, so a chain of k live
-     *  pages needs a base of ≥ 2^k · 4 bytes — seq stays ≤ ~50 for any
-     *  physically possible list; the append path guards the band anyway. */
-    private static readonly SEQ_SPAN;
-    private _selContainExists;
-    protected _dbContainExists(child: NodeId): boolean;
-    private _selContainPages;
-    /** The child's page directory — (seq, byte length) per page, O(log fan-in)
-     *  rows, each read from the cell header without loading the blob. */
-    private containPages;
-    private _selContainPageSub;
-    private _selContainPage;
-    private containPage;
-    protected _dbGetContainParentsSlice(child: NodeId, offset: number, limit: number): NodeId[];
-    private _selContainCount;
-    protected _dbGetContainCount(child: NodeId): number;
-    protected _dbGetContainParents(child: NodeId): NodeId[];
-    private _upsContainPage;
-    private _delContainPage;
-    protected _dbAppendContain(child: NodeId, parents: NodeId[]): void;
-    protected _dbInsertEdge(src: NodeId, dst: NodeId): void;
-    protected _dbGetNextEdges(id: NodeId): NodeId[];
-    protected _dbGetPrevEdges(id: NodeId): NodeId[];
-    private _selNextFirst;
-    protected _dbGetNextEdgesFirst(id: NodeId, limit: number): NodeId[];
-    private _selPrevFirst;
-    protected _dbGetPrevEdgesFirst(id: NodeId, limit: number): NodeId[];
-    private _selPrevCount;
-    /** {@link Store.prevCount} — one indexed COUNT over idx_edge_dst, never a
-     *  row materialisation (a common continuation's reverse fan-in is
-     *  corpus-sized). */
-    prevCount(id: NodeId): number;
-    private _selSrcExists;
-    protected _dbEdgeSrcExists(src: NodeId): boolean;
-    protected _dbEdgeDistinctSrcCount(): number;
-    protected _dbGetHalo(id: NodeId): {
-        vec: Uint8Array;
-        mass: number;
-    } | null;
-    protected _dbUpsertHalo(id: NodeId, encodedVec: Uint8Array, mass: number): void;
-    protected _dbGetMeta(key: string): string | null;
-    protected _dbSetMeta(key: string, val: string): void;
-    protected _dbDeleteMeta(key: string): void;
-    protected _dbSaveSnapshot(bytes: Uint8Array): void;
-    protected _dbLoadSnapshot(): Uint8Array | null;
-    protected _vecContentUpsert(entries: Array<{
-        id: NodeId;
-        vector: Float32Array;
-        ef?: number;
-    }>): void;
-    protected _vecContentQuery(v: Float32Array, k: number, ef: number): Array<{
-        id: number;
-        distance: number;
-    }>;
-    protected _vecContentHas(id: NodeId): boolean;
-    protected _vecContentSize(): number;
-    protected _vecContentLastReads(): number;
-    protected _vecContentPhysicalSize(): number;
-    protected _vecContentCompact(): void;
-    protected _vecContentDeleteMany(ids: NodeId[]): void;
-    protected _vecContentEntriesSince(after: number): IterableIterator<{
-        ext: NodeId;
-        internal: number;
-    }>;
-    /** {@link AbstractStore._dbEdgeOrHaloIds} — one C-side scan; UNION dedups
-     *  and (with the ORDER BY) sorts, so the result is ready for the binary-
-     *  search membership probes and the ascending-id maintenance walks. */
-    protected _dbEdgeOrHaloIds(): NodeId[];
-    protected _vecHaloUpsert(entries: Array<{
-        id: NodeId;
-        vector: Float32Array;
-    }>): void;
-    protected _vecHaloQuery(v: Float32Array, k: number, ef: number): Array<{
-        id: number;
-        distance: number;
-    }>;
-    protected _vecHaloSize(): number;
-    protected _vecHaloPhysicalSize(): number;
-    protected _vecHaloCompact(): void;
-    /** Pre-fill both vector indices' RAM caches with sequential scans (up to
-     *  their budget caps) — seconds of streaming instead of the minutes of
-     *  random point reads a cold training/query session otherwise pays while
-     *  warming.  Optional; call once after open before sustained work.
-     *  Returns rows warmed. */
-    warmVectorCaches(): Promise<number>;
+  private readonly opts;
+  private readonly vectorCacheMb;
+  private readonly vectorSeed;
+  private content;
+  private halos;
+  private sqlite;
+  private _inTx;
+  private _insertNode;
+  private _insertKid;
+  private _selContain;
+  private _selParents;
+  private _selHalo;
+  private _upHalo;
+  private _selLeaf;
+  private _selFlat;
+  private _selKids;
+  private _selNode;
+  private _insertEdge;
+  private _selNext;
+  private _selPrev;
+  private _setMeta;
+  private _getMeta;
+  private _delMeta;
+  private _insSnapshot;
+  private _selSnapshot;
+  constructor(opts?: SQliteStoreOptions);
+  private vectorDbPath;
+  private openVectorDB;
+  protected _dbOpen(): Promise<void>;
+  protected _dbClose(): void;
+  protected _dbBeginTx(): void;
+  protected _dbCommitTx(): void;
+  protected _dbInsertNode(
+    id: NodeId,
+    leaf: Uint8Array | null,
+    kids: Uint8Array | null,
+    h: number,
+  ): void;
+  protected _dbGetNode(id: NodeId): NodeRec | null;
+  protected _dbFindLeaf(h: number, bytes: Uint8Array): NodeId | null;
+  protected _dbFindBranchByLeaf(h: number, bytes: Uint8Array): NodeId | null;
+  protected _dbFindBranchByKids(h: number, packed: Uint8Array): NodeId | null;
+  protected _dbInsertKid(child: NodeId, parent: NodeId): void;
+  protected _dbGetParents(id: NodeId): NodeId[];
+  private _selParentsFirst;
+  protected _dbGetParentsFirst(id: NodeId, limit: number): NodeId[];
+  private _selChain;
+  /** {@link Store.chainRun}'s walk as ONE recursive CTE: the whole
+   *  transparent chain (no edge in or out, exactly one parent) is descended
+   *  inside SQLite — per-node work is the same three indexed probes as the
+   *  base class's loop, but without a JS↔SQLite round trip per node, which
+   *  dominates on the deep single-structure scaffolding this read exists
+   *  for. */
+  protected _chainWalk(id: NodeId, cap: number): NodeId[];
+  /** Width of the seq band inside the packed contain rowid: rowid =
+   *  child·SEQ_SPAN + seq.  Page sizes are geometric, so a chain of k live
+   *  pages needs a base of ≥ 2^k · 4 bytes — seq stays ≤ ~50 for any
+   *  physically possible list; the append path guards the band anyway. */
+  private static readonly SEQ_SPAN;
+  private _selContainExists;
+  protected _dbContainExists(child: NodeId): boolean;
+  private _selContainPages;
+  /** The child's page directory — (seq, byte length) per page, O(log fan-in)
+   *  rows, each read from the cell header without loading the blob. */
+  private containPages;
+  private _selContainPageSub;
+  private _selContainPage;
+  private containPage;
+  protected _dbGetContainParentsSlice(
+    child: NodeId,
+    offset: number,
+    limit: number,
+  ): NodeId[];
+  private _selContainCount;
+  protected _dbGetContainCount(child: NodeId): number;
+  protected _dbGetContainParents(child: NodeId): NodeId[];
+  private _upsContainPage;
+  private _delContainPage;
+  protected _dbAppendContain(child: NodeId, parents: NodeId[]): void;
+  protected _dbInsertEdge(src: NodeId, dst: NodeId): void;
+  protected _dbGetNextEdges(id: NodeId): NodeId[];
+  protected _dbGetPrevEdges(id: NodeId): NodeId[];
+  private _selNextFirst;
+  protected _dbGetNextEdgesFirst(id: NodeId, limit: number): NodeId[];
+  private _selPrevFirst;
+  protected _dbGetPrevEdgesFirst(id: NodeId, limit: number): NodeId[];
+  private _selPrevCount;
+  /** {@link Store.prevCount} — one indexed COUNT over idx_edge_dst, never a
+   *  row materialisation (a common continuation's reverse fan-in is
+   *  corpus-sized). */
+  prevCount(id: NodeId): number;
+  private _selSrcExists;
+  protected _dbEdgeSrcExists(src: NodeId): boolean;
+  protected _dbEdgeDistinctSrcCount(): number;
+  protected _dbGetHalo(id: NodeId): {
+    vec: Uint8Array;
+    mass: number;
+  } | null;
+  protected _dbUpsertHalo(
+    id: NodeId,
+    encodedVec: Uint8Array,
+    mass: number,
+  ): void;
+  protected _dbGetMeta(key: string): string | null;
+  protected _dbSetMeta(key: string, val: string): void;
+  protected _dbDeleteMeta(key: string): void;
+  protected _dbSaveSnapshot(bytes: Uint8Array): void;
+  protected _dbLoadSnapshot(): Uint8Array | null;
+  protected _vecContentUpsert(
+    entries: Array<{
+      id: NodeId;
+      vector: Float32Array;
+      ef?: number;
+    }>,
+  ): void;
+  protected _vecContentQuery(v: Float32Array, k: number, ef: number): Array<{
+    id: number;
+    distance: number;
+  }>;
+  protected _vecContentHas(id: NodeId): boolean;
+  protected _vecContentSize(): number;
+  protected _vecContentLastReads(): number;
+  protected _vecContentPhysicalSize(): number;
+  protected _vecContentCompact(): void;
+  protected _vecContentDeleteMany(ids: NodeId[]): void;
+  protected _vecContentEntriesSince(after: number): IterableIterator<{
+    ext: NodeId;
+    internal: number;
+  }>;
+  /** {@link AbstractStore._dbEdgeOrHaloIds} — one C-side scan; UNION dedups
+   *  and (with the ORDER BY) sorts, so the result is ready for the binary-
+   *  search membership probes and the ascending-id maintenance walks. */
+  protected _dbEdgeOrHaloIds(): NodeId[];
+  protected _vecHaloUpsert(
+    entries: Array<{
+      id: NodeId;
+      vector: Float32Array;
+    }>,
+  ): void;
+  protected _vecHaloQuery(v: Float32Array, k: number, ef: number): Array<{
+    id: number;
+    distance: number;
+  }>;
+  protected _vecHaloSize(): number;
+  protected _vecHaloPhysicalSize(): number;
+  protected _vecHaloCompact(): void;
+  /** Pre-fill both vector indices' RAM caches with sequential scans (up to
+   *  their budget caps) — seconds of streaming instead of the minutes of
+   *  random point reads a cold training/query session otherwise pays while
+   *  warming.  Optional; call once after open before sustained work.
+   *  Returns rows warmed. */
+  warmVectorCaches(): Promise<number>;
 }