@hviana/sema 0.9.3 → 0.9.5

package/docs/mechanisms/recall.md

@@ -1,68 +1,75 @@
-# Recall — Nearest Stored Form
+# Recall — The Nearest Stored Form
 
-Recall resonates the whole query's gist against the content index and grounds
-the nearest learned form. Resonance proposes; bytes decide.
+`recall` answers with the continuation of the stored form nearest the question.
+Resonance proposes, and bytes decide (`src/mind/mechanisms/recall.ts`). Its
+tiers degrade in order, and each one is priced as what it is. A tier that only
+resembles accounts for little, so anything that explains more beats it.
 
-## Gist and budget
+## Supply and budget
 
-Query gist is `pre.guide`; the single top-k read is `pre.resonance()` shared
-across the response. `Precomputed.k = 2·recallQueryK` tiers 0b/1/2/3 through it;
-the last tier re-folds bytes.
+All tiers read the response's single top-`k` resonance (`pre.resonance()`,
+`k = 2·recallQueryK`), guided by the query gist. The last tier re-folds the
+hit's bytes instead of trusting its estimate.
 
-## Tiers (degrading)
+## Tiers
 
-| Tier | Name                  | Gate                                                                                                                                                       | Action                                                                                                            |
-| ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| 0    | Exact identity        | `pre.queryResolved` exists                                                                                                                                 | Reverse-recall (`reverseContext`) to best-resonating predecessor at `STEP`                                        |
-| 0b   | RC8 argument binding  | One maximal `≥2W` edge-source constituent, no substantial `≥2W` form outside it                                                                            | `follow` its continuation; refuses if result is a subspan of the query                                            |
-| 1    | Clean resonance       | `score ≥ identityBar(D,W,len)` per hit                                                                                                                     | `project` hit; restating hits (bytes or `canon`-equivalent) only via reverse-recall                               |
-| 2    | Scaffolding-dominated | `score ≥ significanceBar(D)` and consensus-climb anchor clears `consensusFloor(N)` or `dominates(breadth,1) && peak>ln2`, and query is not all-scaffolding | `project` anchor at `CONCEPT`; refuses if continuation voices the anchor's displaced filler or is a query subspan |
-| 3    | Last resort + bridge  | Query-relative fraction `max(0,cos−sig)·√(lenG/lenQ) ≥ reachThreshold(W)`                                                                                  | Best grounded `project` hit at `STEP`                                                                             |
+| Tier | Name                                   | Gate                                                                                                                                                                                                                                         | Action                                                                                      |
+| ---- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| 0    | exact identity                         | the question resolves                                                                                                                                                                                                                        | reverse-recall to its best-resonating predecessor, at `STEP`                                |
+| 0b   | argument binding                       | one maximal recognised constituent of at least `2W` that is an edge source, with no substantial form outside it. Fragments that answer other questions are set aside first. When the pick would otherwise be blind, the climb is asked first | `follow` its continuation, guided by the whole question                                     |
+| 1    | clean resonance                        | per hit, `score ≥ identityBar(D, W, len)`                                                                                                                                                                                                    | `project` the hit. A hit that restates the question goes only through reverse-recall        |
+| —    | an argument held under the equivalence | no argument recognised, and a canonical index present                                                                                                                                                                                        | the climb's points that the question canonically contains bind as arguments (`evidence.md`) |
+| 2    | scaffolding-dominated                  | resonance `≥ significanceBar`; the climb's anchor clears `consensusFloor(N)` (or is broad with a peak above `ln 2`); the question is not all scaffolding                                                                                     | `project` the anchor at `CONCEPT`                                                           |
+| 3    | last resort                            | the share of the question the grounding explains, `max(0, cos − sig)·√(lenG/lenQ) ≥ reachThreshold(W)`                                                                                                                                       | `project` the best grounded hit, at `STEP`                                                  |
+| 3b   | substitution bridge                    | only after every gist tier failed (below)                                                                                                                                                                                                    | align and substitute                                                                        |
 
-W = `maxGroup` (river window); bars from `src/geometry.ts`.
+**Tier 2 refuses three things.** Each would voice the anchor's own occupant as
+the asker's:
+
+- a continuation that voices the anchor's displaced filler
+  (`voicesDisplacedFiller`);
+- a continuation that is a subspan of the question;
+- an anchor that is a co-instance of the question (`evidence.md`).
+
+Putting the asker's referent in that place is `reference`'s job, because it
+needs the corpus's own evidence of carriage.
 
 ## Echo — the refusing tail
 
-If no tier grounded, the exact cosine of the top hit is re-folded (`gistOf` on
-its bytes). It uses that exact value in the same chance-corrected fraction —
-never the RaBitQ estimate. Below `reach` → silence; restating → silence;
-otherwise the hit's own bytes are returned as an ungrounded echo.
-
-## Provenance
-
-Grounded answers carry `recall`; the echo carries `recall-echo` (`echoed: true`
-on `RecallResult`); it declares `used: ∅`. Consumers distinguish a continuation
-through learned edges from a near-identity echo.
-
-## Substitution bridge — refusal-path only (`src/mind/bridge.ts`)
-
-Runs only after every gist tier failed, reusing the same top-k proposals (the
-bridge's cap is `2·recallQueryK`; every proposal is byte-verified). A candidate
-context is byte-aligned around the rarest stored W-windows. A mismatch becomes a
-corroborated substitution only when its query span is corpus-attested (every
-W-window stored, one reused ≥2 containers), its geometry clears
-`conceptThreshold(D)` or its halo clears `significanceBar(D)`, its frame is
-unanimous, and the raw gap is length-balanced. Coverage must dominate the query
-and no dismissed gap may hide known content (`dismissedKnownContent` gate). Cost
-is `CONCEPT` per substitution plus `STEP`; accounted spans include matched and
-substituted ranges (so a 28/29-byte paraphrase is not charged `PASS` per
-substituted byte — the double-charge that let `cast` outbid the bridge).
-Zero-substitution identity bridges carry `complete: true` (the whole read-out);
-substituted bridges do not.
-
-Scaffolding-only queries abstain: when every window that could anchor is
-saturated (corpus-global scaffolding, `allWindowsAreScaffolding`), the bridge
-returns nothing — one substituted word cannot carry the load.
+When no tier grounds, the top hit's exact cosine is recomputed from its bytes
+and read with the same chance-corrected fraction. The outcome is one of two:
+
+- **Silence,** when the fraction is below reach, or when the hit restates the
+  question.
+- **An echo,** otherwise: the hit's own bytes, labelled `recall-echo` and
+  declaring `used: ∅`. It tells the asker that the answer is near, not derived.
+
+## The substitution bridge — refusal path only (`src/mind/bridge.ts`)
+
+The bridge aligns a candidate around the rarest stored windows. A mismatch
+becomes a corroborated substitution only when all of these hold:
+
+- the question's span is attested in the corpus;
+- the geometry clears `conceptThreshold`, or the halo clears `significanceBar`;
+- the frame is unanimous;
+- the gap is balanced in length.
+
+Coverage must dominate the question, and no dismissed gap may hide known content
+(`dismissedKnownContent`). Each substitution costs `CONCEPT`, and the
+substituted spans are accounted. A question made only of scaffolding abstains,
+because one substituted word cannot carry it. A zero-substitution identity
+bridge is `complete`.
 
 ## Cost
 
-Tiers 0/1/3 price `STEP` (one hop); tier 2 and the bridge price `CONCEPT` per
-substitution/scaffold step. Mechanism `floor` is `STEP`; weight is
-`moves + PASS·unaccounted`.
+Tiers 0, 0b, 1 and 3 cost `STEP`. Tier 2 and the bridge cost `CONCEPT` per
+substitution or scaffolding step. The floor is `STEP`.
 
 ## Pins
 
-- `test/03-recall.test.mjs` — exact identity and reverse-recall
-- `test/16-bridge.test.mjs` — corroborated substitutions
-- `test/73-scaffolding-only-bridge-abstains.test.mjs` — scaffolding-only queries
-  stay silent
+- `test/03` — exact identity and reverse-recall.
+- `test/16`, `test/56` — corroborated substitutions, and the bridge's admission
+  by identity.
+- `test/73` — a question made only of scaffolding stays silent.
+- `test/154.6`, `test/154.8` — a stranger fragment is not bound; an argument
+  held only under the equivalence binds.

package/docs/mechanisms/reference.md

@@ -1,58 +1,72 @@
-# Reference — Voicing a Slot with the Asker's Bytes
-
-Reference voices a slot of a learned frame with the bytes the asker supplied in
-that position — asserting _position_, not equivalence. The bytes are the
-asker's, so voicing them cannot fabricate corpus knowledge; the fabricable claim
-is the _relation_ about them, which the licence withholds.
-
-## Matcher — `frameSlots` inventory
-
-The shared matcher is `frameSlots` (`src/mind/match.ts`) via
-`Precomputed.frames()`.
-
-- Seeded at origin `(0,0)`, `alignAround` finds common runs (seed `W`) then
-  sweeps both directions; each gap is contracted by `contractGap` to its varying
-  core (shared prefix/suffix stripped) and tagged
-  `substitution | insertion | deletion`.
-- `frameSlots` **reports, never judges**: every gap (any kind, any size), sorted
-  by `qs`, plus `covered` (shared bytes) and `matched` spans. No gate is applied
-  there.
-
-## Gate — reference elects and licences; matcher does not
-
-All voicing gates belong to the **consumer**
-(`src/mind/mechanisms/reference.ts`), not the matcher. A shared layer that
-refused on their behalf would be reference-shaped and hide most real pairings.
-
-- **Election:** `electFrame` groups inventory by full slot signature
-  (`qs:qe,...`) and keeps the modal group — one frame, not one slot.
-- **Carriage licence:** `carriesFillers` —
-  `substituteAll(contA, fillersA→fillersB) == contB` byte-exact, all slots
-  simultaneously (longest needle first). Constant continuations pass vacuously;
-  filler-dependent content is refused.
-- **Four voicing gates** (in `voiceable` + caller):
-  1. frame `dominates` query (`covered > |query|/2`);
-  2. every slot reaches one window `W` on _both_ sides;
-  3. no insertion/deletion (substitutions only);
-  4. fillers pairwise distinct. Additional: referents pairwise distinct and no
-     slot inside `answeredSpans`.
-
-Matched frame + every slot is `accounted`; `complete: true`.
+# Reference — Voice a Slot With the Asker's Bytes
 
-## Cost
+`reference` learns a frame from worked examples and voices its slot with the
+bytes the asker put in that position (`src/mind/mechanisms/reference.ts`). It
+asserts _position_ ("this is the thing you named, where the corpus keeps one"),
+not equivalence. The voiced bytes are the asker's, so they cannot fabricate
+corpus knowledge. What can be fabricated is the relation claimed about them, and
+the licence exists to withhold that.
+
+The substitution bridge refuses this shape, and is right to. A substitution
+asserts that two spans mean the same, which no corpus can corroborate for bytes
+it has never seen.
+
+## Matcher — the frame inventory
+
+`Precomputed.frames()` reads the ranked candidates as instances of the
+question's own frame, through `frameSlots`, which reports and elects nothing
+(`match-project.md`).
+
+Its supply is the shared top-`k` resonance, so a frame the corpus instantiates
+only once within `k` is out of reach. Measured on the trained store,
+`How do you say 'flurbish' in French?` finds one instance of its frame in the
+top 24, so `reference` abstains. Widening the supply is not the fix: abstaining
+on thin evidence is.
+
+## Election and voicing gates
 
-`moves = STEP·slots + STEP` (one binding per slot + one edge follow). Not
-`CONCEPT` — byte identity, not halo. `scaffolding` is never reported; a referent
-is explained, not carried for lack of explanation.
+`electFrame` keeps the modal group of instances that place the question's slots
+alike. It needs at least `MIN_INSTANCES = 2`, because one alignment agrees with
+nothing. Each instance must also be voiceable:
+
+1. the frame dominates the question, covering more than half of it;
+2. every slot reaches one window `W` on both sides;
+3. substitutions only, with no insertion or deletion;
+4. the fillers are pairwise distinct, the referents are distinct, and no slot
+   lies inside an already answered span.
+
+## The licence — what a new referent may inherit
+
+Each instance's continuation is followed, one at a time, because refusal is the
+common outcome and usually comes on the second instance. Two checks apply:
+
+- **Co-variation.** `carriesFillers` requires
+  `substituteAll(contA, fillersA → fillersB) == contB`, byte for byte, for all
+  slots at once. Content that depends on which filler stands in the slot is
+  refused.
+- **A fact filed under a filler is not a carriage.** A continuation that does
+  not vary passes co-variation vacuously, and coincidence lives there. If an
+  instance's answer is a continuation of its own filler, it is something the
+  corpus knows _about_ that filler. Two people born in Wellington once gave an
+  unknown `Zorblax` the same birthplace. `Run gcc hello.c` is filed under the
+  question alone, so it still carries.
+
+## Cost
 
-`floor` is `STEP+STEP`, investment-disciplined before touching `frames()`.
+`moves = STEP · slots + STEP`: one binding per slot and one edge followed. It is
+not `CONCEPT`, because the reading is byte identity, not halo. The matched frame
+and every slot are `accounted`, the answer is `complete`, and no scaffolding is
+reported. The floor is `2·STEP`, checked with `worthRunning` before `frames()`
+is touched.
 
 ## Provenance
 
-`provenance: "reference"` with trace steps `bindReferent` / `referenceLicence`.
+`reference`, with the trace steps `bindReferent` and `referenceLicence`.
 
 ## Pins
 
-- `test/76-reference-binding` — inventory vs gate split, carried/absorbed/
-  refused, multi-slot licence, `complete` and answered-span guard.
-- `test/76-type-level-company` — type-level halo company underpinning.
+- `test/76-reference-binding` — the split between inventory and gate; carried,
+  absorbed and refused frames; the multi-slot licence; `complete`; the guard on
+  answered spans; a fact filed under its filler is no carriage.
+- `test/76-type-level-company` — the halo company by type that the inventory's
+  supply relies on.

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://jsr.io/schema/config-file.v1.json",
   "name": "@hviana/sema",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "exports": "./src/index.ts"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hviana/sema",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Sema: a non-parametric, instance-based reasoning system.",
   "repository": {
     "type": "git",