@hviana/sema 0.1.3 → 0.1.5

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

@@ -12,36 +12,72 @@ import type { Input, MindContext } from "./types.js";
  *  O(new nodes) per deposit instead of O(context).  Only the hit node
  *  itself enters `ids`; descendants stay reachable via the memo (see
  *  idOf in indexSubSpans and the changedNodes prune). */
-export declare function internTreeIds(ctx: MindContext, node: Sema, ids: Map<Sema, number>): Promise<number>;
+export declare function internTreeIds(
+  ctx: MindContext,
+  node: Sema,
+  ids: Map<Sema, number>,
+): Promise<number>;
 /** Index flat branches for sub-spans of a deposit's byte stream, linked to
  *  their structural chunks via durable CONTAINMENT edges. */
-export declare function indexSubSpans(ctx: MindContext, tree: Sema, ids: Map<Sema, number>): Promise<boolean>;
+export declare function indexSubSpans(
+  ctx: MindContext,
+  tree: Sema,
+  ids: Map<Sema, number>,
+): Promise<boolean>;
 /** Perceive, intern, and index a single input.  Returns the perceived tree,
  *  root id, id map, and the changed (new) subtrees for halo reinforcement. */
-export declare function deposit(ctx: MindContext, input: Input, track: boolean): Promise<{
-    tree: Sema;
-    rootId: number;
-    ids: Map<Sema, number>;
-    changed: Sema[];
+export declare function deposit(
+  ctx: MindContext,
+  input: Input,
+  track: boolean,
+): Promise<{
+  tree: Sema;
+  rootId: number;
+  ids: Map<Sema, number>;
+  changed: Sema[];
 }>;
 /** Ingest a single input (a bare experience, no continuation). */
-export declare function ingestOne(ctx: MindContext, input: Input): Promise<Sema & {
+export declare function ingestOne(
+  ctx: MindContext,
+  input: Input,
+): Promise<
+  Sema & {
     id: number;
-}>;
+  }
+>;
 /** Ingest a pair (context, continuation) — learn an edge and pour halos. */
-export declare function ingestPair(ctx: MindContext, ctxInput: Input, cont: Input): Promise<void>;
+export declare function ingestPair(
+  ctx: MindContext,
+  ctxInput: Input,
+  cont: Input,
+): Promise<void>;
 /** Dispatch the public ingest input shapes onto one-input / pair handlers —
  *  THE one reading of ingest's polymorphic surface (scalar, (context,
  *  continuation) pair, or a list mixing bare inputs and pairs).  Both ingest
  *  paths — the direct one below and {@link CachedIngest} — route through
  *  this, so the shape-detection can never drift between them again (the
  *  ingest cache once re-implemented it and drifted). */
-export declare function dispatchIngest(input: Input | (Input | [Input, Input])[], second: Input | undefined, onOne: (input: Input) => Promise<Sema & {
-    id: number;
-}>, onPair: (ctxInput: Input, cont: Input) => Promise<void>): Promise<(Sema & {
+export declare function dispatchIngest(
+  input: Input | (Input | [Input, Input])[],
+  second: Input | undefined,
+  onOne: (input: Input) => Promise<
+    Sema & {
+      id: number;
+    }
+  >,
+  onPair: (ctxInput: Input, cont: Input) => Promise<void>,
+): Promise<
+  (Sema & {
     id: number;
-}) | undefined>;
+  }) | undefined
+>;
 /** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
-export declare function ingest(ctx: MindContext, input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
+export declare function ingest(
+  ctx: MindContext,
+  input: Input | (Input | [Input, Input])[],
+  second?: Input,
+): Promise<
+  (Sema & {
     id: number;
-}) | undefined>;
+  }) | undefined
+>;

package/dist/src/mind/learning.js

@@ -20,152 +20,166 @@ import { fold as foldVecs } from "../sema.js";
  *  itself enters `ids`; descendants stay reachable via the memo (see
  *  idOf in indexSubSpans and the changedNodes prune). */
 export async function internTreeIds(ctx, node, ids) {
-    const known = ctx._internIds.get(node);
-    if (known !== undefined) {
-        ids.set(node, known);
-        return known;
+  const known = ctx._internIds.get(node);
+  if (known !== undefined) {
+    ids.set(node, known);
+    return known;
+  }
+  let id;
+  if (node.kids === null) {
+    id = await ctx.store.putLeaf(node.leaf ?? new Uint8Array(0), node.v);
+  } else {
+    const kds = [];
+    for (const k of node.kids) {
+      kds.push(await internTreeIds(ctx, k, ids));
     }
-    let id;
-    if (node.kids === null) {
-        id = await ctx.store.putLeaf(node.leaf ?? new Uint8Array(0), node.v);
-    }
-    else {
-        const kds = [];
-        for (const k of node.kids)
-            kds.push(await internTreeIds(ctx, k, ids));
-        id = await ctx.store.putBranch(kds, node.v);
-    }
-    ids.set(node, id);
-    ctx._internIds.set(node, id);
-    return id;
+    id = await ctx.store.putBranch(kds, node.v);
+  }
+  ids.set(node, id);
+  ctx._internIds.set(node, id);
+  return id;
 }
 /** Index flat branches for sub-spans of a deposit's byte stream, linked to
  *  their structural chunks via durable CONTAINMENT edges. */
 export async function indexSubSpans(ctx, tree, ids) {
-    const chunkOf = [];
-    const streamIds = [];
-    const streamVecs = [];
-    const collect = (n) => {
-        if (isChunk(n)) {
-            // A chunk inside a memo-skipped shared subtree is absent from `ids`;
-            // the intern memo still knows it (same object).  A miss on both (the
-            // WeakMap entry was collected) only forfeits the seenBefore skip.
-            const chunkId = ids.get(n) ?? ctx._internIds.get(n);
-            for (const k of n.kids) {
-                const lid = k.leaf ? ctx.store.findLeaf(k.leaf) : null;
-                if (lid === null)
-                    return false;
-                streamIds.push(lid);
-                streamVecs.push(k.v);
-                chunkOf.push(chunkId);
-            }
-            return true;
+  const chunkOf = [];
+  const streamIds = [];
+  const streamVecs = [];
+  const collect = (n) => {
+    if (isChunk(n)) {
+      // A chunk inside a memo-skipped shared subtree is absent from `ids`;
+      // the intern memo still knows it (same object).  A miss on both (the
+      // WeakMap entry was collected) only forfeits the seenBefore skip.
+      const chunkId = ids.get(n) ?? ctx._internIds.get(n);
+      for (const k of n.kids) {
+        const lid = k.leaf ? ctx.store.findLeaf(k.leaf) : null;
+        if (lid === null) {
+          return false;
         }
-        if (n.kids) {
-            for (const k of n.kids)
-                if (!collect(k))
-                    return false;
+        streamIds.push(lid);
+        streamVecs.push(k.v);
+        chunkOf.push(chunkId);
+      }
+      return true;
+    }
+    if (n.kids) {
+      for (const k of n.kids) {
+        if (!collect(k)) {
+          return false;
         }
-        return true;
-    };
-    if (!collect(tree))
+      }
+    }
+    return true;
+  };
+  if (!collect(tree)) {
+    return false;
+  }
+  const W = ctx.space.maxGroup; // write side of the canonical contract
+  const prev = ctx._prevSeen;
+  const seenBefore = (off, len) => {
+    if (!prev) {
+      return false;
+    }
+    for (let i = off; i < off + len; i++) {
+      const c = chunkOf[i];
+      if (c === undefined || !prev.has(c)) {
         return false;
-    const W = ctx.space.maxGroup; // write side of the canonical contract
-    const prev = ctx._prevSeen;
-    const seenBefore = (off, len) => {
-        if (!prev)
-            return false;
-        for (let i = off; i < off + len; i++) {
-            const c = chunkOf[i];
-            if (c === undefined || !prev.has(c))
-                return false;
-        }
-        return true;
-    };
-    const lens = streamIds.length >= W ? canonicalWindows(W) : [streamIds.length];
-    for (const len of lens) {
-        if (len < 1)
-            continue;
-        for (let off = 0; off + len <= streamIds.length; off++) {
-            if (seenBefore(off, len))
-                continue;
-            const winIds = streamIds.slice(off, off + len);
-            const flatId = ctx.store.findBranch(winIds) ??
-                await ctx.store.putBranch(winIds, foldVecs(ctx.space, streamVecs.slice(off, off + len)));
-            for (let i = off; i < off + len; i++) {
-                const c = chunkOf[i];
-                if (c !== undefined)
-                    ctx.store.addContainer(flatId, c);
-            }
-        }
+      }
     }
     return true;
+  };
+  const lens = streamIds.length >= W ? canonicalWindows(W) : [streamIds.length];
+  for (const len of lens) {
+    if (len < 1) {
+      continue;
+    }
+    for (let off = 0; off + len <= streamIds.length; off++) {
+      if (seenBefore(off, len)) {
+        continue;
+      }
+      const winIds = streamIds.slice(off, off + len);
+      const flatId = ctx.store.findBranch(winIds) ??
+        await ctx.store.putBranch(
+          winIds,
+          foldVecs(ctx.space, streamVecs.slice(off, off + len)),
+        );
+      for (let i = off; i < off + len; i++) {
+        const c = chunkOf[i];
+        if (c !== undefined) {
+          ctx.store.addContainer(flatId, c);
+        }
+      }
+    }
+  }
+  return true;
 }
 /** Perceive, intern, and index a single input.  Returns the perceived tree,
  *  root id, id map, and the changed (new) subtrees for halo reinforcement. */
 export async function deposit(ctx, input, track) {
-    const bytes = inputBytes(ctx, input);
-    // Deposit-shaped perception: stable-prefix tree SEEDING (see
-    // perceiveDeposit) — an accumulated context re-folds only its new suffix,
-    // O(turn) instead of O(context) per conversation turn.  Cache-only here
-    // (no store-probe fallback): a knownPrefixLength scan on every novel fact
-    // would cost O(n²) hashing, while conversation replays are always warm —
-    // re-deposition replays from the first turn, rebuilding the cache as it
-    // goes.
-    const tree = perceiveDeposit(ctx, bytes);
-    const ids = new Map();
-    const rootId = await internTreeIds(ctx, tree, ids);
-    const indexed = await indexSubSpans(ctx, tree, ids);
-    const leafIds = leafIdPrefix(ctx, bytes);
-    if (leafIds.length === bytes.length && leafIds.length >= 2) {
-        await ctx.store.putBranch(leafIds, tree.v);
-    }
-    const changed = (track && ctx._prevSeen)
-        ? changedNodes(tree, ids, ctx._prevSeen)
-        : [tree];
-    if (track)
-        ctx._prevSeen = indexed ? new Set(ids.values()) : null;
-    return { tree, rootId, ids, changed };
+  const bytes = inputBytes(ctx, input);
+  // Deposit-shaped perception: stable-prefix tree SEEDING (see
+  // perceiveDeposit) — an accumulated context re-folds only its new suffix,
+  // O(turn) instead of O(context) per conversation turn.  Cache-only here
+  // (no store-probe fallback): a knownPrefixLength scan on every novel fact
+  // would cost O(n²) hashing, while conversation replays are always warm —
+  // re-deposition replays from the first turn, rebuilding the cache as it
+  // goes.
+  const tree = perceiveDeposit(ctx, bytes);
+  const ids = new Map();
+  const rootId = await internTreeIds(ctx, tree, ids);
+  const indexed = await indexSubSpans(ctx, tree, ids);
+  const leafIds = leafIdPrefix(ctx, bytes);
+  if (leafIds.length === bytes.length && leafIds.length >= 2) {
+    await ctx.store.putBranch(leafIds, tree.v);
+  }
+  const changed = (track && ctx._prevSeen)
+    ? changedNodes(tree, ids, ctx._prevSeen)
+    : [tree];
+  if (track) {
+    ctx._prevSeen = indexed ? new Set(ids.values()) : null;
+  }
+  return { tree, rootId, ids, changed };
 }
 /** Ingest a single input (a bare experience, no continuation). */
 export async function ingestOne(ctx, input) {
-    const { tree, rootId, ids } = await deposit(ctx, input, true);
-    ctx.store.indexTarget(rootId);
-    const parts = tree.kids
-        ? tree.kids.map((k) => ids.get(k))
-        : [rootId];
-    const stride = ctx.space.maxGroup;
-    if (parts.length > stride) {
-        for (let i = 0; i + stride < parts.length; i += stride) {
-            await ctx.store.link(parts[i], parts[i + stride]);
-        }
-        if ((parts.length - 1) % stride !== 0) {
-            const lastStart = Math.floor((parts.length - 1) / stride) * stride;
-            if (lastStart < parts.length - 1) {
-                await ctx.store.link(parts[lastStart], parts[parts.length - 1]);
-            }
-        }
+  const { tree, rootId, ids } = await deposit(ctx, input, true);
+  ctx.store.indexTarget(rootId);
+  const parts = tree.kids ? tree.kids.map((k) => ids.get(k)) : [rootId];
+  const stride = ctx.space.maxGroup;
+  if (parts.length > stride) {
+    for (let i = 0; i + stride < parts.length; i += stride) {
+      await ctx.store.link(parts[i], parts[i + stride]);
+    }
+    if ((parts.length - 1) % stride !== 0) {
+      const lastStart = Math.floor((parts.length - 1) / stride) * stride;
+      if (lastStart < parts.length - 1) {
+        await ctx.store.link(parts[lastStart], parts[parts.length - 1]);
+      }
     }
-    else {
-        for (const id of parts)
-            ctx.store.indexTarget(id);
+  } else {
+    for (const id of parts) {
+      ctx.store.indexTarget(id);
     }
-    return Object.assign(tree, { id: rootId });
+  }
+  return Object.assign(tree, { id: rootId });
 }
 /** Ingest a pair (context, continuation) — learn an edge and pour halos. */
 export async function ingestPair(ctx, ctxInput, cont) {
-    const c = await deposit(ctx, ctxInput, true);
-    const cont_ = await deposit(ctx, cont, false);
-    const ctxId = c.rootId, contId = cont_.rootId;
-    await ctx.store.link(ctxId, contId);
-    // Halos pour company SIGNATURES (identity), not gists (content) — see
-    // companySignature in sema.ts.
-    const contSeat = bindSeat(ctx.space, companySignature(ctx.space, contId), 1);
-    for (const part of c.changed) {
-        const partId = c.ids.get(part);
-        await ctx.store.pourHalo(partId, contSeat);
-        await ctx.store.pourHalo(contId, bindSeat(ctx.space, companySignature(ctx.space, partId), 0));
-    }
+  const c = await deposit(ctx, ctxInput, true);
+  const cont_ = await deposit(ctx, cont, false);
+  const ctxId = c.rootId, contId = cont_.rootId;
+  await ctx.store.link(ctxId, contId);
+  // Halos pour company SIGNATURES (identity), not gists (content) — see
+  // companySignature in sema.ts.
+  const contSeat = bindSeat(ctx.space, companySignature(ctx.space, contId), 1);
+  for (const part of c.changed) {
+    const partId = c.ids.get(part);
+    await ctx.store.pourHalo(partId, contSeat);
+    await ctx.store.pourHalo(
+      contId,
+      bindSeat(ctx.space, companySignature(ctx.space, partId), 0),
+    );
+  }
 }
 /** Dispatch the public ingest input shapes onto one-input / pair handlers —
  *  THE one reading of ingest's polymorphic surface (scalar, (context,
@@ -174,28 +188,36 @@ export async function ingestPair(ctx, ctxInput, cont) {
  *  this, so the shape-detection can never drift between them again (the
  *  ingest cache once re-implemented it and drifted). */
 export async function dispatchIngest(input, second, onOne, onPair) {
-    if (Array.isArray(input) && !(input instanceof Uint8Array) &&
-        input.width === undefined) {
-        const arr = input;
-        if (arr.length === 2 && !Array.isArray(arr[0]) && !Array.isArray(arr[1])) {
-            await onPair(arr[0], arr[1]);
-            return undefined;
-        }
-        for (const item of arr) {
-            if (Array.isArray(item) && item.length === 2) {
-                await onPair(item[0], item[1]);
-            }
-            else
-                await onOne(item);
-        }
-        return undefined;
+  if (
+    Array.isArray(input) && !(input instanceof Uint8Array) &&
+    input.width === undefined
+  ) {
+    const arr = input;
+    if (arr.length === 2 && !Array.isArray(arr[0]) && !Array.isArray(arr[1])) {
+      await onPair(arr[0], arr[1]);
+      return undefined;
+    }
+    for (const item of arr) {
+      if (Array.isArray(item) && item.length === 2) {
+        await onPair(item[0], item[1]);
+      } else {
+        await onOne(item);
+      }
     }
-    if (second === undefined)
-        return onOne(input);
-    await onPair(input, second);
     return undefined;
+  }
+  if (second === undefined) {
+    return onOne(input);
+  }
+  await onPair(input, second);
+  return undefined;
 }
 /** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
 export async function ingest(ctx, input, second) {
-    return dispatchIngest(input, second, (i) => ingestOne(ctx, i), (a, b) => ingestPair(ctx, a, b));
+  return dispatchIngest(
+    input,
+    second,
+    (i) => ingestOne(ctx, i),
+    (a, b) => ingestPair(ctx, a, b),
+  );
 }

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

@@ -14,17 +14,27 @@ import type { Site } from "./graph-search.js";
  *                (gate: identityBar — scale-aware).
  *
  *  Returns the absolute byte position, or −1. */
-export declare function locate(ctx: MindContext, haystack: Uint8Array, needle: Uint8Array, fromPos: number, sites?: ReadonlyArray<Site>): number;
+export declare function locate(
+  ctx: MindContext,
+  haystack: Uint8Array,
+  needle: Uint8Array,
+  fromPos: number,
+  sites?: ReadonlyArray<Site>,
+): number;
 /** The ALIGNED matcher: maximal literal matching runs between `query` and
  *  `ct` (a learned context's bytes), by seed-and-extend over
  *  `space.maxGroup`-sized n-gram seeds.  Where locate() finds ONE position of
  *  a short frame, this finds EVERY run two whole structures share — the
  *  matcher CAST detects a woven query with.  Returns non-overlapping runs
  *  sorted by query position. */
-export declare function alignRuns(ctx: MindContext, query: Uint8Array, ct: Uint8Array): Array<{
-    qs: number;
-    qe: number;
-    cs: number;
+export declare function alignRuns(
+  ctx: MindContext,
+  query: Uint8Array,
+  ct: Uint8Array,
+): Array<{
+  qs: number;
+  qe: number;
+  cs: number;
 }>;
 /** A run from {@link alignGraded} — the ALIGNED matcher extended with the
  *  same graded-evidence ladder as {@link locate}.  Literal runs carry
@@ -34,10 +44,10 @@ export declare function alignRuns(ctx: MindContext, query: Uint8Array, ct: Uint8
  *  kind, so the substitution/redirection schemas work unchanged on conceptual
  *  alignment. */
 export interface GradedRun {
-    qs: number;
-    qe: number;
-    cs: number;
-    weight: number;
+  qs: number;
+  qe: number;
+  cs: number;
+  weight: number;
 }
 /** The GRADED alignment matcher: extends literal W-gram alignment
  *  ({@link alignRuns}) with halo-matched recognised sites in query regions
@@ -49,23 +59,42 @@ export interface GradedRun {
  *  `querySites` are the pre-computed recognition sites for the query
  *  (optional — when absent, only literal alignment fires and graded degrades
  *  to the original behaviour).  Context sites are recognised internally. */
-export declare function alignGraded(ctx: MindContext, query: Uint8Array, contextBytes: Uint8Array, querySites?: ReadonlyArray<Site>): GradedRun[];
+export declare function alignGraded(
+  ctx: MindContext,
+  query: Uint8Array,
+  contextBytes: Uint8Array,
+  querySites?: ReadonlyArray<Site>,
+): GradedRun[];
 /** The IN-LIST halo matcher: the best halo-mate for `halo` among EXPLICIT
  *  candidates, above the concept threshold — the list counterpart of
  *  {@link haloSiblings}, which asks the halo INDEX for candidates instead.
  *  Behind locate()'s halo step and articulation's voice matching; a third
  *  "best halo among these" decision must come here, not inline. */
-export declare function bestHaloMate<T>(ctx: MindContext, halo: Vec, items: Iterable<T>, haloOf: (item: T) => Vec | null | undefined): {
-    item: T;
-    score: number;
+export declare function bestHaloMate<T>(
+  ctx: MindContext,
+  halo: Vec,
+  items: Iterable<T>,
+  haloOf: (item: T) => Vec | null | undefined,
+): {
+  item: T;
+  score: number;
 } | null;
-export declare function haloSiblings(ctx: MindContext, id: number, halo?: Vec | null, bar?: number): Promise<Hit[]>;
+export declare function haloSiblings(
+  ctx: MindContext,
+  id: number,
+  halo?: Vec | null,
+  bar?: number,
+): Promise<Hit[]>;
 /** The DISTRIBUTIONAL matcher between two nodes: mutual-nearest-neighbour
  *  strength, not a pick.  Returns the direct halo cosine, or failing that the
  *  highest mutual-halo-sibling min-score (second-order analogy), or failing
  *  that the SHARED-FRAME strength (below) — the gate CAST's comparison
  *  schema validates genuine analogs with (bar: significanceBar). */
-export declare function analogyStrength(ctx: MindContext, a: number, b: number): Promise<number>;
+export declare function analogyStrength(
+  ctx: MindContext,
+  a: number,
+  b: number,
+): Promise<number>;
 /** The STRUCTURAL analogy tier: two nodes are analogs when their byte
  *  streams share a LEARNT frame — a content-addressed flat form of at least
  *  one full river window (W bytes, the perception quantum) that occurs in
@@ -78,17 +107,28 @@ export declare function analogyStrength(ctx: MindContext, a: number, b: number):
  *  a fraction, comparable to the cosine tiers above.  Derived: the window
  *  is maxGroup, the same quantum differsByOneWindow and canonicalChunkId
  *  measure by; no tuned constants. */
-export declare function sharedFrameStrength(ctx: MindContext, a: number, b: number): number;
+export declare function sharedFrameStrength(
+  ctx: MindContext,
+  a: number,
+  b: number,
+): number;
 /** FORWARD through a synonym: the continuation an edge-less node borrows from
  *  a concept (halo) sibling — resonate the node's halo, take the first
  *  sibling above the concept threshold that itself has a direct edge. */
-export declare function conceptHop(ctx: MindContext, id: number): Promise<number | null>;
+export declare function conceptHop(
+  ctx: MindContext,
+  id: number,
+): Promise<number | null>;
 /** FORWARD projection: follow continuation edges from a node to its fixpoint.
  *  The first hop may cross a concept (halo) link — a synonym.  The rest
  *  follow direct edges.  Convergence is intrinsic: the seen set guards
  *  against cycles.  `guide` disambiguates multi-continuation nodes by
  *  resonance. */
-export declare function follow(ctx: MindContext, id: number, guide?: Vec | null): Promise<Uint8Array | null>;
+export declare function follow(
+  ctx: MindContext,
+  id: number,
+  guide?: Vec | null,
+): Promise<Uint8Array | null>;
 /** REVERSE projection: the context a learnt continuation follows, voiced as
  *  bytes.  A common continuation ("Yes.") follows MANY contexts; with a
  *  `guide` the context whose gist resonates with the query wins (seat
@@ -103,9 +143,18 @@ export declare function follow(ctx: MindContext, id: number, guide?: Vec | null)
  *  context reads empty (a zero-length context is no grounding: an empty
  *  Uint8Array is truthy, and returning it would flow a hollow "answer"
  *  onward). */
-export declare function reverseContext(ctx: MindContext, id: number, guide?: Vec | null, rev?: readonly number[]): Uint8Array | null;
+export declare function reverseContext(
+  ctx: MindContext,
+  id: number,
+  guide?: Vec | null,
+  rev?: readonly number[],
+): Uint8Array | null;
 /** THE projection: ground a matched node to answer bytes — FORWARD to its
  *  continuation fixpoint (which may cross a concept hop), else REVERSE to
  *  the context it follows.  This is the direction ladder every mechanism's
  *  final grounding step reduces to. */
-export declare function project(ctx: MindContext, id: number, guide?: Vec | null): Promise<Uint8Array | null>;
+export declare function project(
+  ctx: MindContext,
+  id: number,
+  guide?: Vec | null,
+): Promise<Uint8Array | null>;