@seanhogg/builderforce-memory 2026.9.31 → 2026.9.32

package/dist/evermind/textCoherence.js

@@ -0,0 +1,218 @@
+/**
+ * textCoherence — pure, zero-dependency text-quality primitives shared by every
+ * surface that must decide whether text a project's OWN SSM (Evermind) produced is
+ * fit to show a user. Kept dependency-free (no db/env/engine imports) so it can be
+ * imported by the memory-first resolver, the model probe and the gateway vendor —
+ * and by a browser client — without an import cycle.
+ */
+import { detectLatinLanguage, isCodeishToken, isFunctionWord, scoreEnglishWordiness, } from './wordLexicon.js';
+/** A reply shorter than this isn't a real answer — fall through to the LLM. Mirrors
+ *  the cloud/BrainService threshold so every surface adopts Evermind identically. */
+export const EVERMIND_ANSWER_MIN_CHARS = 20;
+/** Human-readable explanations, one per failure signal. */
+const FAILURE_DETAIL = {
+    'empty': 'the model returned nothing',
+    'replacement-chars': 'the output contains Unicode replacement characters (broken token decoding)',
+    'repetition': 'the decoder is stuck repeating the same word or phrase',
+    'dominant-token': 'the output recycles a handful of words — the head has collapsed onto part of its vocabulary',
+    'unbalanced-delimiters': 'the output closes brackets it never opened',
+    'no-function-words': 'the output has no recognisable function words in any supported language',
+    'non-words': 'most of the content words are not real words — the head is emitting invented tokens',
+};
+/**
+ * Cheap coherence gate for text a project's OWN SSM (Evermind) produced. An
+ * under-trained head emits fluent-LOOKING garbage — broken UTF-8 (Unicode
+ * replacement chars from byte-level BPE), degenerate word repetition ("commit …
+ * commit … commit", "in the in the"), and fluent-shaped prose made entirely of
+ * INVENTED words — that trivially clears a length check. Serving it makes the
+ * assistant reply in gibberish, so this gate rejects it and the caller falls through
+ * to a real LLM (a garbled reply IS a memory miss).
+ *
+ * Signals 1–4 are structural and language-agnostic. Signals 5–6 consult a lexicon and
+ * are therefore GUARDED: they run only on predominantly-Latin, non-code text, and the
+ * dictionary check only when the text is confidently English — so an es/fr/de/pt/it
+ * reply, a CJK reply, or a code block is never judged by an English word list.
+ */
+export function assessTextCoherence(text, opts = {}) {
+    const t = (text ?? '').trim();
+    if (!t)
+        return fail('empty');
+    // 1) Broken token decoding. A byte-level BPE emitting a low-probability token
+    //    sequence frequently yields invalid UTF-8 → the replacement char. Real
+    //    answers effectively never contain it → near-certain garbage.
+    if (t.includes('�'))
+        return fail('replacement-chars');
+    const words = t.toLowerCase().match(/\p{L}+/gu) ?? [];
+    // Too few alphabetic tokens to score structurally (CJK collapses to one run); it
+    // already cleared the length + replacement-char gates, so accept (a handful of
+    // clean words is a real answer).
+    if (words.length < 6)
+        return pass();
+    // 2) Adjacent runaway repetition: a stuck decoder repeats a token ("commit
+    //    commit") or a bigram ("in the in the"). A little is normal prose.
+    let rep = 0;
+    for (let i = 1; i < words.length; i++)
+        if (words[i] === words[i - 1])
+            rep++;
+    for (let i = 3; i < words.length; i++) {
+        if (words[i] === words[i - 2] && words[i - 1] === words[i - 3])
+            rep++;
+    }
+    if (rep >= 3 && rep / words.length > 0.06)
+        return fail('repetition');
+    // 3) Content-word collapse: an under-trained head that overfit its corpus stops
+    //    reaching for new words and recycles a handful ("update update the file update
+    //    the file update"). Judged on CONTENT words only — grammar is supposed to repeat,
+    //    and the length proxy this replaces (any token of 3+ letters) counted `the`,
+    //    `and`, `was` and `not` as content, which is why its floors had to be set so high
+    //    that they stopped meaning anything on a short reply.
+    if (collapsedVocabulary(words))
+        return fail('dominant-token');
+    // 4) Orphaned closing delimiters. The checks above key on REPETITION, so they miss
+    //    the other failure mode of an under-trained byte-BPE head: fluent-shaped text made
+    //    of invented words, each different. What that text does emit is punctuation it
+    //    never opened — it learned that `)` and `.` follow tokens, not that a bracket has
+    //    to be opened first. Structural, language-agnostic, and cheap: real prose and real
+    //    code balance their delimiters. The floor of TWO spares a legitimate stray paren.
+    if (unmatchedClosers(t) >= 2)
+        return fail('unbalanced-delimiters');
+    return assessVocabulary(t, words, opts);
+}
+/**
+ * Signals 5–6 — the LEXICAL half of the gate, split out so the guards that make it
+ * safe live in one readable place. This is what closes the gap the structural checks
+ * cannot see: invented words with balanced punctuation and no repetition.
+ *
+ * It is skipped entirely unless the text is predominantly Latin-script and mostly
+ * prose (not code), because outside that envelope a word list proves nothing.
+ */
+function assessVocabulary(t, words, opts) {
+    // Raw whitespace tokens paired with their alphabetic core, so the scorer can tell an
+    // identifier (`projectEvermindRef`, `api/src/x.ts`, `v2.1`) from a prose word.
+    const rawTokens = [];
+    const coreWords = [];
+    for (const raw of t.split(/\s+/u)) {
+        const core = raw
+            .replace(/^[^\p{L}]+/u, '')
+            .replace(/[^\p{L}]+$/u, '')
+            .toLowerCase()
+            .replace(/[''’-]/gu, '');
+        if (!core || !/^\p{L}+$/u.test(core)) {
+            rawTokens.push(raw);
+            coreWords.push('');
+            continue;
+        }
+        rawTokens.push(raw);
+        coreWords.push(core);
+    }
+    // Code-dominant text (a diff, a config dump, a stack trace) is legitimately made of
+    // non-words — never judge it lexically.
+    const codeish = rawTokens.filter((r) => r && isCodeishToken(r)).length;
+    if (rawTokens.length > 0 && codeish / rawTokens.length > 0.3)
+        return pass();
+    const lang = detectLatinLanguage(words, t);
+    if (!lang.latin)
+        return pass(); // CJK / Cyrillic / Arabic — out of scope by design.
+    // 5) No function words at all. Prose in EVERY supported language is ≥ ~10% function
+    //    words; a long Latin-script, non-code passage with essentially none is not a
+    //    language. This is the check that catches gibberish too degenerate to even
+    //    identify a language for — the case the dictionary check below can't reach.
+    if (words.length >= 25 && lang.anyShare < 0.04)
+        return fail('no-function-words');
+    // 6) Invented-word share. English-only: a reply that votes decisively for Spanish,
+    //    French, German, Portuguese or Italian is never measured against an English
+    //    lexicon. Everything else — English wins, or nothing wins and English still
+    //    leads — IS measured, because "no language won" describes gibberish at least as
+    //    often as it describes prose, and passing it unjudged was the hole that let
+    //    invented-word output through. The scorer additionally forgives any token that
+    //    echoes the prompt or recurs in the text, so jargon-dense real answers pass while
+    //    each-word-different gibberish does not.
+    if (!lang.englishLeads)
+        return pass();
+    const score = scoreEnglishWordiness(coreWords.filter(Boolean), rawTokens.filter((_, i) => !!coreWords[i]), opts.context);
+    if (score.scored && score.unknown >= 5 && score.unknownShare >= 0.5) {
+        return {
+            coherent: false,
+            failure: 'non-words',
+            detail: `${FAILURE_DETAIL['non-words']} (${score.unknown}/${score.eligible} unrecognised)`,
+        };
+    }
+    return pass();
+}
+const pass = () => ({ coherent: true, failure: null, detail: '' });
+const fail = (failure) => ({ coherent: false, failure, detail: FAILURE_DETAIL[failure] });
+/**
+ * Boolean form of {@link assessTextCoherence} — the shape every existing caller uses.
+ * Prefer the assessment when you have somewhere to SHOW the reason.
+ */
+export function looksLikeCoherentText(text, opts = {}) {
+    return assessTextCoherence(text, opts).coherent;
+}
+/** Is this text both substantive (long enough) AND coherent — the ONE bar every serve
+ *  path applies before showing SSM output to a user. Shared so the length threshold and
+ *  the gate can never drift apart between the memory resolver, the vendor and the probe. */
+export function isServableText(text, opts = {}) {
+    const t = (text ?? '').trim();
+    if (t.length < EVERMIND_ANSWER_MIN_CHARS) {
+        return { coherent: false, failure: 'empty', detail: `the model returned less than ${EVERMIND_ANSWER_MIN_CHARS} characters` };
+    }
+    return assessTextCoherence(t, opts);
+}
+/**
+ * Has the head stopped reaching for new words? Two independent shapes of the same
+ * failure, measured over CONTENT words (see {@link isFunctionWord}) so that ordinary
+ * grammar cannot trip either one:
+ *
+ *  - **Too few distinct words for the length.** A reply whose content vocabulary is at
+ *    most half its content tokens is recycling, not composing. This is what works on a
+ *    SHORT reply, where any absolute occurrence floor is out of reach: `update update
+ *    the file update the file update` is 7 content tokens drawn from 2 words.
+ *  - **One word taking most of the reply.** The long-form shape, where enough distinct
+ *    words survive to clear the diversity bar but one of them still dominates — the
+ *    observed `commit … commit … commit` sample sprayed it ~15 times.
+ *
+ * The dominance arm is measured against CONTENT tokens and needs a body of them, which
+ * is what spares a legitimately repetitive real answer: "every commit on that branch is
+ * a merge commit, so the commit history reads as one commit per pull request" says
+ * `commit` five times and is a perfectly good sentence — the previous rule, which
+ * measured against ALL tokens with a fixed floor of 5 occurrences, rejected it.
+ */
+function collapsedVocabulary(words) {
+    const freq = new Map();
+    let tokens = 0;
+    for (const w of words) {
+        if (w.length < 3 || isFunctionWord(w))
+            continue;
+        tokens++;
+        freq.set(w, (freq.get(w) ?? 0) + 1);
+    }
+    // Below this there is no vocabulary to have collapsed — a handful of content words is
+    // a terse answer, and every ratio over it is noise.
+    if (tokens < 5)
+        return false;
+    if (freq.size / tokens <= 0.5)
+        return true;
+    let maxCount = 0;
+    for (const c of freq.values())
+        if (c > maxCount)
+            maxCount = c;
+    return tokens >= 12 && maxCount / tokens > 0.4;
+}
+/** How many closing brackets appear with no opener before them. Pure counting — a
+ *  balanced or over-opened text scores 0. Shared by {@link assessTextCoherence}. */
+function unmatchedClosers(text) {
+    let depth = 0;
+    let orphans = 0;
+    for (const ch of text) {
+        if (ch === '(' || ch === '[' || ch === '{')
+            depth++;
+        else if (ch === ')' || ch === ']' || ch === '}') {
+            if (depth > 0)
+                depth--;
+            else
+                orphans++;
+        }
+    }
+    return orphans;
+}
+//# sourceMappingURL=textCoherence.js.map

package/dist/evermind/textCoherence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textCoherence.js","sourceRoot":"","sources":["../../src/evermind/textCoherence.ts"],"names":[],"mappings":"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"}

package/dist/evermind/toolCall.d.ts

@@ -0,0 +1,175 @@
+/**
+ * toolCall — function calling for Evermind, a project's OWN SSM.
+ *
+ * Evermind used to REFUSE every tool-bearing request, on the reasoning that a head
+ * which generates raw text cannot emit `tool_calls` and that narrating a call is
+ * worse than an error. The refusal was right about the failure mode and wrong about
+ * the remedy: "can the architecture emit a JSON tool call?" is not a property of the
+ * weights at all, it is a property of the DECODING STRATEGY. A tiny under-trained
+ * head asked to free-generate `{"name":…,"arguments":{…}}` will indeed produce
+ * malformed junk — so this module never asks it to.
+ *
+ * The approach is schema-driven CONSTRAINED DECODING (the jsonformer/outlines shape):
+ * the JSON is ASSEMBLED HERE as a real JS object from the tool's JSON Schema, and the
+ * model is only ever consulted for the leaves it is qualified to fill:
+ *
+ *   • a finite choice (which tool, an `enum`, a boolean) → every candidate is SCORED
+ *     by likelihood and the argmax wins, so the answer is always a legal value;
+ *   • a free value (a string, a number) → generated, then parsed/escaped by us.
+ *
+ * Structural validity is therefore guaranteed BY CONSTRUCTION — the braces, quotes,
+ * commas and key names are never sampled, so there is no such thing as a malformed
+ * Evermind tool call. `JSON.stringify` of a real object cannot be invalid JSON.
+ *
+ * What that does NOT buy is a good CHOICE, and this is where the original file's
+ * instinct is kept rather than discarded. A head that cannot tell `read_file` from
+ * `open_pull_request` will still pick one — structurally perfect, semantically a coin
+ * flip — and an agent loop acting on coin flips writes files for no reason. So the
+ * planner reports the MARGIN between its best and runner-up candidate, and the vendor
+ * refuses (400 → cascade) when the head is measurably guessing. Fitness to tool-call
+ * is now measured, the same way {@link ./textCoherence} measures fitness to answer in
+ * prose, instead of being assumed absent.
+ *
+ * Pure + port-based (no engine, no R2, no db imports) so the whole planner is unit
+ * testable against a fake decoder; the model-backed adapter lives in
+ * {@link ./runtime}.
+ */
+/** A tool the model may call, normalized out of the OpenAI wire shape. */
+export interface NormalizedTool {
+    name: string;
+    description: string;
+    /** JSON Schema for the arguments object (`{ type:'object', properties, required }`). */
+    parameters: JsonSchema;
+}
+/** The slice of JSON Schema this decoder understands. Anything unrecognised is
+ *  filled as a string, which is always representable. */
+export interface JsonSchema {
+    type?: string | string[];
+    description?: string;
+    enum?: unknown[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    maxLength?: number;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * What the caller's `tool_choice` resolved to. Mirrors the OpenAI contract:
+ * `none` never calls, `auto` lets the model decide, `required` must call something,
+ * and a pinned function forces exactly one.
+ */
+export type ToolChoicePlan = {
+    mode: 'none';
+} | {
+    mode: 'auto';
+} | {
+    mode: 'required';
+} | {
+    mode: 'forced';
+    name: string;
+};
+/**
+ * The two capabilities the planner needs from a language model. Kept this narrow so
+ * the planner has no engine dependency — {@link ./runtime} supplies the
+ * EvermindLM-backed implementation and tests supply a deterministic fake.
+ */
+export interface EvermindToolDecoder {
+    /**
+     * Length-normalized mean log-probability of `continuation` following `prompt`
+     * (higher = more likely). Length normalization is what makes candidates of
+     * different token counts comparable — without it the shortest tool name wins
+     * every vote purely for being short.
+     */
+    score(prompt: string, continuation: string): number;
+    /** Free-text continuation of `prompt`, at most `maxTokens` new tokens. */
+    generate(prompt: string, maxTokens: number): string;
+}
+/**
+ * Minimum separation (in mean log-prob) between the winning candidate and the
+ * runner-up for a choice to count as a DECISION rather than a coin flip.
+ *
+ * This is the tool-calling analogue of the coherence bar: it is what stops a
+ * structurally-perfect-but-meaningless call from driving an agent loop. Tuned low
+ * on purpose — the job is to catch a head with no preference at all (margins at
+ * ~1e-3), not to demand confidence a small model never shows.
+ */
+export declare const TOOL_CHOICE_MIN_MARGIN = 0.02;
+/**
+ * The margin bar in force for a raw override (the host reads it from its own config —
+ * the gateway's `EVERMIND_TOOL_CHOICE_MIN_MARGIN`). ONE resolver, shared by the
+ * serve-time gate and the bench, so the bench can never report a bar the gateway is
+ * not applying.
+ *
+ * The default is an analytic placeholder and documented as one; the override is what
+ * lets it be CALIBRATED from logged margins without a deploy per candidate value.
+ */
+export declare function resolveToolChoiceMinMargin(override?: string | null): number;
+/**
+ * Normalize the OpenAI `tools` array into {@link NormalizedTool}s, accepting both the
+ * nested chat-completions shape (`{ type:'function', function:{…} }`) and the already
+ * flattened Responses shape (`{ type:'function', name, … }`) — the gateway carries
+ * both, and a vendor that understood only one would silently see zero tools.
+ * Entries without a usable name are dropped rather than half-registered.
+ */
+export declare function normalizeEvermindTools(tools: unknown[] | undefined): NormalizedTool[];
+/**
+ * Resolve the caller's `tool_choice` against the tools actually on offer. A pinned
+ * function that isn't in the list degrades to `required` rather than forcing a name
+ * the caller never declared (which would produce a call no agent loop can dispatch).
+ */
+export declare function resolveEvermindToolChoice(toolChoice: unknown, tools: NormalizedTool[]): ToolChoicePlan;
+/**
+ * The tool catalogue, rendered into the prompt so the head's choice is INFORMED by
+ * the descriptions rather than made from the tool names alone. Shared by the decision
+ * vote and every argument fill so the model sees one consistent context.
+ */
+export declare function renderToolsPreamble(tools: NormalizedTool[]): string;
+/** One planned call. */
+export interface EvermindPlannedCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/** A planned call plus the evidence for how confidently it was chosen. */
+export interface EvermindToolPlan {
+    /** The FIRST chosen call, or null when the head elected to answer in prose
+     *  (`auto` only). Kept as the single-call view every existing reader uses;
+     *  {@link EvermindToolPlan.calls} is the full list. */
+    call: EvermindPlannedCall | null;
+    /**
+     * Every call this turn emits, in order.
+     *
+     * The OpenAI shape has always been an ARRAY and frontier models emit parallel
+     * calls; Evermind used to plan exactly one, so a caller that relies on parallel
+     * calls silently got serialized behaviour. After the first call the head is asked
+     * "another call?" — the same continue-vote the array filler already uses for list
+     * length — so a model with nothing more to do still emits exactly one.
+     * Empty when `call` is null.
+     */
+    calls: EvermindPlannedCall[];
+    /**
+     * Separation between the winning tool and the runner-up. The vendor gates on this:
+     * a head with no preference is guessing, and a guessed tool call is exactly the
+     * "silently doing the wrong thing" this backend refuses to do.
+     * `Infinity` when the choice was forced or unopposed (nothing was guessed).
+     */
+    margin: number;
+}
+/**
+ * Choose a tool and fill its arguments under the caller's `tool_choice` contract.
+ *
+ * The decision and every argument come from the model; the JSON structure comes from
+ * the schema. Returns `{ call: null }` only in `auto` mode, and only when answering
+ * directly out-scored every tool — `required`/`forced` always produce a call.
+ */
+export declare function planEvermindToolCall(decoder: EvermindToolDecoder, basePrompt: string, tools: NormalizedTool[], choice: ToolChoicePlan): EvermindToolPlan;
+/** Wrap a planned call in the OpenAI `tool_calls` wire shape. `id` is supplied by the
+ *  caller so the completion builder controls id generation (and tests stay stable). */
+export declare function toOpenAIToolCall(call: {
+    name: string;
+    arguments: Record<string, unknown>;
+}, id: string): Record<string, unknown>;
+//# sourceMappingURL=toolCall.d.ts.map

package/dist/evermind/toolCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCall.d.ts","sourceRoot":"","sources":["../../src/evermind/toolCall.ts"],"names":[],"mappings":"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"}