@hviana/sema 0.9.0 → 0.9.1

package/dist/src/mind/bridge.js

@@ -92,7 +92,7 @@
 import { cosine } from "../vec.js";
 import { conceptThreshold, dominates, significanceBar } from "../geometry.js";
 import { bytesEqual, indexOf } from "../bytes.js";
-import { foldTree, perceive, read } from "./primitives.js";
+import { exactNode, perceive, read } from "./primitives.js";
 import { chainReach, leafIdRun } from "./canonical.js";
 import { allWindowsAreScaffolding, corpusN, edgeAncestors, hubBound, sharedReachMemo, } from "./traverse.js";
 import { rItem, rNode } from "./trace.js";
@@ -438,7 +438,7 @@ async function bridgeImpl(ctx, query, proposed) {
             continue;
         let use = sid;
         if (!ctx.store.hasNext(use)) {
-            const folded = foldTree(ctx, perceive(ctx, tb), 0).node;
+            const folded = exactNode(ctx, tb);
             if (folded === null || folded === sid || !ctx.store.hasNext(folded)) {
                 continue;
             }
@@ -457,7 +457,7 @@ async function bridgeImpl(ctx, query, proposed) {
     // be a FLAT content twin whose continuation edge lives on the
     // fold-shaped deposit node with the same bytes — the same twin split
     // canonResolve bridges by re-folding (primitives.ts) — but the re-fold
-    // (a full perceive of the candidate's bytes) is paid only for proposals
+    // (an identity fold of the candidate's bytes) is paid only for proposals
     // that could align at all: alignment can only seed at a picked anchor
     // window occurring literally in the candidate (measured: unconditional
     // re-folds multiplied the refusal-path latency several-fold).

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

@@ -204,3 +204,43 @@ export declare function closure(d: DerivationState, query: Uint8Array, W: number
 onTaken?: (before: DerivationState, after: DerivationState, witnesses: ReadonlyArray<Witness>) => void, 
 /** Called when the law refused the continuation the layer offered. */
 onRefused?: (at: DerivationState) => void): Promise<DerivationState>;
+/** A LAYER of the closure — a named producer of continuations for one state.
+ *  The layer OFFERS (its {@link Offer} is the whole of what it decides); the
+ *  law admits; the engine sequences.  The hooks are the layer's own
+ *  instrumentation, called by the engine at the moments the law defines. */
+export interface ClosureLayer {
+    /** The layer's name — its rationale scope and its meter phase. */
+    readonly name: string;
+    /** Whether the layer has anything to offer this state at all.  A layer that
+     *  does not engage is not ENTERED: no offer is asked and no work is charged
+     *  to it.  Omitted: it always engages. */
+    readonly engages?: (d: DerivationState) => boolean;
+    /** The layer's continuations, one at a time ({@link Offer}'s contract). */
+    readonly offer: Offer;
+    /** Called for each step the law admits, with the state before and after. */
+    readonly onTaken?: (before: DerivationState, after: DerivationState, witnesses: ReadonlyArray<Witness>) => void;
+    /** Called when the law refused the continuation the layer offered. */
+    readonly onRefused?: (at: DerivationState) => void;
+    /** Called once the layer's walk has ended — the layer offered nothing more,
+     *  or the law refused — with the state it began from and the one it reached. */
+    readonly onEnd?: (from: DerivationState, to: DerivationState) => void;
+}
+/** THE CLOSURE ENGINE — close a derivation under the law, layer by layer.
+ *
+ *  Each layer is walked to its own end ({@link closure}: the layer offers, the
+ *  law admits or refuses), and the state it reaches is the state the next layer
+ *  is offered against.  Layers are PHASES, in the order given, never revisited:
+ *  a later layer composes what an earlier one produced, and nothing it adds is
+ *  re-offered to the earlier one.
+ *
+ *  THE LAW'S FIRST CLAUSE IS APPLIED HERE, ONCE.  A FIXED state admits no
+ *  transition (`admissible` refuses it before anything else), so no layer is
+ *  entered at all — the decision a caller used to spell as "skip the walk for a
+ *  complete grounding, and skip the fusion too" is the law's, not the caller's,
+ *  and it is taken before any layer pays for an offer it could never have
+ *  taken.
+ *
+ *  `enter` wraps each entered layer's walk — the caller's instrumentation (a
+ *  meter phase), which this module cannot import: it reads nothing but the
+ *  state and the layers. */
+export declare function closeOver(d: DerivationState, query: Uint8Array, W: number, layers: ReadonlyArray<ClosureLayer>, enter?: (name: string, walk: () => Promise<DerivationState>) => Promise<DerivationState>): Promise<DerivationState>;

package/dist/src/mind/derivation.js

@@ -334,3 +334,37 @@ onRefused) {
         d = next;
     }
 }
+/** THE CLOSURE ENGINE — close a derivation under the law, layer by layer.
+ *
+ *  Each layer is walked to its own end ({@link closure}: the layer offers, the
+ *  law admits or refuses), and the state it reaches is the state the next layer
+ *  is offered against.  Layers are PHASES, in the order given, never revisited:
+ *  a later layer composes what an earlier one produced, and nothing it adds is
+ *  re-offered to the earlier one.
+ *
+ *  THE LAW'S FIRST CLAUSE IS APPLIED HERE, ONCE.  A FIXED state admits no
+ *  transition (`admissible` refuses it before anything else), so no layer is
+ *  entered at all — the decision a caller used to spell as "skip the walk for a
+ *  complete grounding, and skip the fusion too" is the law's, not the caller's,
+ *  and it is taken before any layer pays for an offer it could never have
+ *  taken.
+ *
+ *  `enter` wraps each entered layer's walk — the caller's instrumentation (a
+ *  meter phase), which this module cannot import: it reads nothing but the
+ *  state and the layers. */
+export async function closeOver(d, query, W, layers, enter) {
+    for (const layer of layers) {
+        if (d.fixed)
+            return d;
+        if (layer.engages !== undefined && !layer.engages(d))
+            continue;
+        const from = d;
+        const walk = async () => {
+            const to = await closure(from, query, W, layer.offer, layer.onTaken, layer.onRefused);
+            layer.onEnd?.(from, to);
+            return to;
+        };
+        d = enter === undefined ? await walk() : await enter(layer.name, walk);
+    }
+    return d;
+}

package/dist/src/mind/graph-search.d.ts

@@ -46,6 +46,11 @@ export type GItem = {
      *  consolidated, more-explanatory reading wins over leaving the parts split.
      *  See {@link GraphSearch.fuse} and {@link GraphSearch.formRules}. */
     rcmp?: boolean;
+    /** Set on a concept hop's ASKING form: the edge-less form `node` whose halo
+     *  target the caller has not granted yet, held at the hop's own cost and
+     *  span.  Popping it asks for the target; it leads nowhere itself, so it
+     *  is never part of a final derivation (see {@link Licence}). */
+    ask?: boolean;
 } | {
     kind: "out";
     i: number;
@@ -145,6 +150,45 @@ export interface DerivationItem {
  *  conclusion shape (the rules carry no label, so this classifies by structure,
  *  the single place that maps rule geometry to a name). */
 export type DerivationMove = "axiom" | "follow-edge" | "concept-hop" | "voice" | "ground" | "splice-connector" | "split" | "fuse" | "recompose" | "derive-through" | "bridge" | "pool-vote" | "step";
+/** THE ASYNC PREMISES A COVER USES, RESOLVED ONLY WHERE THE SEARCH REACHES THEM.
+ *
+ *  Two of the cover's rules need data the synchronous search cannot fetch — a
+ *  connector splice (a bridge between two answers) and a concept hop (an
+ *  edge-less form's halo sibling) — and both used to be resolved for EVERY
+ *  candidate before the search ran.  A rule fires only from popped premises,
+ *  and the agenda pops in cost order up to the goal, so most of that work fed
+ *  rules the search never reached: measured on the 31.7M-node store, a 262-byte
+ *  query recognised whole paid 23 bridges (143,520 junction pops, 7.3 s of its
+ *  7.9 s) for sub-forms whose rewrites cost a STEP each and so never left the
+ *  agenda before the one-STEP goal — and then 1.2 s of halo reads for concept
+ *  hops priced at CONCEPT, ten times that goal.
+ *
+ *  So the caller OFFERS what it can resolve; where the search reaches an offered
+ *  key it uses a GRANTED value and ASKS for an ungranted one — a connector when
+ *  its splice's premises meet, a concept target when the hop's conclusion, held
+ *  as an asking form at the hop's own cost, is popped.  A run that asked
+ *  nothing is the run every key resolved in advance would have made: the pops
+ *  are decided only by the rules fired from popped items, a granted key fires
+ *  the very rule it fired before, and an asking form that was never popped fired
+ *  none.  So its cover is final.  A run that asked is PROVISIONAL: the caller
+ *  grants the asked keys (the async reads the search cannot run) and covers
+ *  again; every round grants at least one offered key, so the rounds end. */
+export interface Licence<K, V> {
+    /** Every key the caller can resolve. */
+    readonly offered: ReadonlySet<K>;
+    /** The keys resolved so far: their value, or null (nothing learnt). */
+    readonly granted: ReadonlyMap<K, V | null>;
+    /** Filled by the search: the offered keys it reached ungranted. */
+    readonly asked: Set<K>;
+}
+/** Connectors, keyed `L,R` by answer-node ids, valued by the learnt glue. */
+export type ConnectorLicence = Licence<string, Uint8Array>;
+/** Concept hops, keyed by an edge-less form's node, valued by the node its
+ *  halo sibling's edge leads to. */
+export type ConceptLicence = Licence<number, number>;
+/** Nothing offered: a cover with no async premises (a nested completion,
+ *  articulation's revoicing). */
+export declare function noLicence<K, V>(): Licence<K, V>;
 /** The lightest-derivation search over the Sema graph.  One instance binds the
  *  store, `maxGroup` (the fusible span ceiling), and the canonical
  *  {@link resolve} callback; {@link cover} then solves one query. */
@@ -162,13 +206,14 @@ export declare class GraphSearch {
      *  recursive completion), and chooseNext (distributional-evidence edge
      *  disambiguation when a recognised form has multiple continuations). */
     host: GraphSearchHost);
-    /** The nodes the QUERY canonically names — the same identity the store's keys
-     *  were written through.  A byte-exact test is not enough: the query writes
-     *  `Eiffel Tower country` and the deposited node is `eiffel tower country`, so
-     *  a join that filters the query's own subject by RAW bytes re-admits it —
-     *  measured: that is the trap's wrong answer (`The capital of Eiffel Tower
-     *  country is Berlin.`).  Cached by query identity, because the search is
-     *  reused across responses. */
+    /** The hub bound √N (bounded-reads.md) — the ONE fan-out cap, stated here
+     *  rather than imported from `traverse.ts` because this module is
+     *  deliberately host-based (it holds a bare Store, never a MindContext).
+     *  That is the same write/read-side duplication convention canonical.ts's
+     *  header documents: if the formula changes it must change in BOTH places.
+     *  It is stated ONCE per side, though — the expression used to be spelled
+     *  out at three call sites here, one of them inside a per-item rules
+     *  generator, and they had already drifted on the `Math.max(2, …)` floor. */
     private hubBound;
     /** Explore the Sema graph for the lightest cover of the query and return its
      *  chosen spans left-to-right — WITH the derivation's total weight (the g
@@ -185,8 +230,10 @@ export declare class GraphSearch {
      *
      *  Any learnt connector between two rewrites is spliced IN by the in-search
      *  connector rule (see {@link outRules}), so the returned spans already carry
-     *  it — there is no post-pass. */
-    cover(queryLen: number, sites: ReadonlyArray<Site>, conceptTarget: ReadonlyMap<number, number>, leaves: ReadonlyArray<Leaf>, splits: ReadonlySet<number>, substitutions?: ReadonlyMap<number, Uint8Array>, connectors?: ReadonlyMap<string, Uint8Array>, computedResults?: ReadonlyArray<ComputedResult>, 
+     *  it — there is no post-pass.  With a {@link ConnectorLicence}, a cover
+     *  returned while `connectors.asked` is non-empty is PROVISIONAL: grant the
+     *  asked pairs and cover again. */
+    cover(queryLen: number, sites: ReadonlyArray<Site>, concepts: ConceptLicence, leaves: ReadonlyArray<Leaf>, splits: ReadonlySet<number>, substitutions?: ReadonlyMap<number, Uint8Array>, connectors?: ConnectorLicence, computedResults?: ReadonlyArray<ComputedResult>, 
     /** When given, receives each solved span's lightest derivation — the full
      *  adapted A*LD proof tree as classified {@link DerivationStep}s — for the
      *  TOP cover AND every nested completion the sink is threaded into (see
@@ -262,11 +309,12 @@ export declare class GraphSearch {
     private bridgeRule;
     /** The connector-SPLICE rule for an oriented (l, r) pair, or null when the
      *  pair does not qualify — the ONE body behind {@link outRules}' two
-     *  mirror loops (this-as-left over resolved right partners, this-as-right
-     *  over resolved left partners).  Fires only when both sides are
+     *  mirror loops (this-as-left over offered right partners, this-as-right
+     *  over offered left partners).  Fires only when both sides are
      *  recognised, r starts at or after l ends, and the gap between them is
      *  empty or wholly recognised — never across the asker's own literal
-     *  separator. */
+     *  separator — and the pair's connector is granted and learnt.  A qualifying
+     *  pair not yet granted is ASKED for (see {@link ConnectorLicence}). */
     private trySplice;
     /** form(i,j,node,via): follow the graph out of `node`, or (in articulation)
      *  emit its substitute voice directly. */
@@ -307,6 +355,14 @@ export declare class GraphSearch {
      *  outs of a long query re-cover each distinct node at most once); reset at the
      *  top of {@link cover}. */
     private recompleteMemo;
+    /** {@link entityProposals}, per fact BYTES — a pure function of them while
+     *  the store is read-only (one response), so a fact the chart reaches as
+     *  several items (cover/fix variants, nested completions) is scanned once.
+     *  Reset at the top of {@link cover}, like {@link recompleteMemo}. */
+    private entityMemo;
+    /** The joins licensed under one cover's {@link Licence}, kept across its
+     *  re-covers (see {@link solve}). */
+    private readonly joinsKept;
     /** The derivation sink of the TOP cover, threaded into every nested
      *  completion so a produced form's own recompositions are reported in the
      *  same trace instead of vanishing after the first layer.  Undefined when
@@ -321,6 +377,21 @@ export declare class GraphSearch {
      *  most once per cover.  A Set, not a flag, because it states WHICH node is
      *  open — the invariant a reader needs to check the guard. */
     private recompleteOpen;
+    /** The ENTITIES a produced fact's bytes contain that lead somewhere — the
+     *  candidates a join may travel through.  The forms the fact CONTAINS, by the
+     *  same recogniser the query went through (so the evidence standard is the
+     *  query's), plus — because the recognition of a STORED WHOLE returns the
+     *  whole and stops (measured: one site, the fact's own node, for `The
+     *  director of Eva is Gustaf Molander.`) — the longest canonically-resolving
+     *  form at each offset.  A byte atom is never a subject.  The scan runs only
+     *  for a FORM (≥ W: per letter it measured 20-26 s in test/99), and each probe
+     *  is a `canonResolve` whose exact tier decides a miss by its segment probe,
+     *  without a fold.  The admission predicate is the store's `leadsSomewhere`
+     *  (edge or halo); the host lends its memoised form when it can.
+     *
+     *  The SOURCE of each proposal travels with it, so a refusal names which path
+     *  proposed the candidate.  Memoised per fact bytes ({@link entityMemo}). */
+    private entityProposals;
     /** DERIVE-THROUGH — a RULE this module's DeductionSystem was missing.  The
      *  A*LD library is untouched: this is one more `premises → conclusion + cost`
      *  rule in the system {@link buildSearch} hands to {@link lightestDerivation},
@@ -335,7 +406,10 @@ export declare class GraphSearch {
      *  fact reached through it.  On the ladder it is one STEP: a direct edge,
      *  exactly as following a literal continuation is.  Deterministic and
      *  point-probed (`resolve` + `nextFirst`, no scan), so it adds no read that
-     *  grows with the corpus.  The move is visible in the rationale as its own act
+     *  grows with the corpus.  Asked ONCE per fact a lightest derivation stood on
+     *  (the join license, {@link solve}) — never per fact the exploration merely
+     *  reached — so the number of facts it prices is the answer's, not the
+     *  corpus's.  The move is visible in the rationale as its own act
      *  (`classifyMove` reports `derive-through`), distinct from the
      *  byte-concatenating `fuse`/`splice` — and named `derive-through` rather than
      *  `join` so it cannot be read as the confluence mechanism's `Provenance`. */
@@ -343,8 +417,8 @@ export declare class GraphSearch {
     /** out(i,j,bytes,…): index it for the binary rules, then offer splicing a
      *  learnt connector (the in-search bridge), splitting (at a sub-leaf form
      *  boundary), bridging (cover(i) ∧ this → cover(j)), fusing with an adjacent
-     *  finalised out, and — for a produced fact — JOINING the entity it contains
-     *  with the query's tail ({@link deriveThrough}). */
+     *  finalised out, and — for a LICENSED fact — JOINING the entity it contains
+     *  with the query's tail ({@link deriveThrough}, granted in {@link solve}). */
     private outRules;
     /** Whether the query span [from, to) is wholly covered by RECOGNISED outs —
      *  the test that lets a connector jump across INTERIOR answers (an N-ary whole)