@bobobowis/jev-kit 0.0.0-stage → 0.1.0

package/dist/compact/should-compact.js

@@ -0,0 +1,87 @@
+/**
+ * Level 7, option A: should I compact.
+ * At the end of every agent turn, four questions about the work, one call. The numbers, context usage and the lines, stay in code. Jev judges whether the work moved on. The agent hears nothing, a notice, a recommendation, or a request.
+ */
+import { noul, score } from "../core/helpers.js";
+export const COMPACT_QUESTIONS = {
+    switched_gears: noul("Is `current_request` a different task from `previous_work`?", {
+        true: "A new feature, a different file area, a different goal, or an unrelated question",
+        false: "The same task continuing, a follow up, a fix to what was just done",
+    }),
+    at_boundary: noul("Did `recent_turn` finish a unit of work?", {
+        true: "Tests passed, a commit was made, a summary was given, or a question was asked of the user",
+        false: "Mid task, more steps clearly remain",
+    }),
+    needs_history: score("How much of `previous_work` does the next step need?", [
+        "None; the new work stands alone",
+        "Some references, a file name or a decision",
+        "Most of it; the work continues directly from it",
+    ]),
+    mid_operation: noul("Is the agent in the middle of a multi step edit whose partial state only exists in the conversation?", {
+        true: "Half applied changes, a plan being executed step by step, an unfinished refactor",
+        false: "A clean point, nothing half done",
+    }),
+};
+export const DEFAULT_LINES = { notice: 6000, recommend: 10_000, request: 14_000 };
+/** A gauge reading in words: "12k tokens, 6.0% of the window", or just the tokens. */
+export const usageText = (u) => `${Math.round(u.tokens / 1000)}k tokens${u.pct === null ? "" : `, ${u.pct.toFixed(1)}% of the window`}`;
+const clip = (s, n = 70) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+/**
+ * The decision, numbers in code. Silent when there is nothing to compact, when the agent is mid
+ * operation, or when the work has not moved on. Otherwise the tier follows usage against the lines.
+ */
+export function decideTier(a, usage, compactable, lines, state) {
+    if (!compactable)
+        return { tier: "silent", reason: "nothing to compact yet" };
+    if (a.mid_operation.noul > 0.6)
+        return { tier: "silent", reason: "mid operation" };
+    const switched = a.switched_gears.noul > 0.7;
+    const boundary = a.at_boundary.noul > 0.6 && a.needs_history.score < 1;
+    if (!switched && !boundary)
+        return { tier: "silent", reason: "same work continuing" };
+    const reason = switched
+        ? `The task changed${state ? ` from "${clip(state.previous_work)}" to "${clip(state.current_request)}"` : ""}.`
+        : "The last turn finished a unit of work and the next step needs little of the earlier context.";
+    // Without a usage reading there are no lines to place it against: the judgment alone earns a notice.
+    if (!usage)
+        return { tier: "notice", reason: `${reason} Context usage is unknown.` };
+    if (usage.tokens < lines.notice)
+        return { tier: "silent", reason: "below the notice line" };
+    if (usage.tokens < lines.recommend)
+        return { tier: "notice", reason };
+    if (usage.tokens < lines.request)
+        return { tier: "recommend", reason };
+    return { tier: "request", reason };
+}
+/** The exact text the agent sees on its next call. Silent returns null: nothing is injected. */
+export function tierMessage(d, usage, action = "compact_now") {
+    if (action === "ask_user")
+        return askUserMessage(d, usage);
+    if (!usage)
+        return d.tier === "silent" ? null : `${d.reason} Compacting is optional. If you do, call compact_now with a short note to yourself.`;
+    const pct = usageText(usage);
+    switch (d.tier) {
+        case "notice":
+            return `Context is at ${pct}. ${d.reason} Compacting is optional. If you do, call compact_now with a short note to yourself.`;
+        case "recommend":
+            return `Recommended: compact now. Context is at ${pct}. ${d.reason} Call compact_now with a short note to yourself, then continue.`;
+        case "request":
+            return `Please compact before continuing. Context is at ${pct}. ${d.reason} Call compact_now with a short note to yourself.`;
+        default:
+            return null;
+    }
+}
+function askUserMessage(d, usage) {
+    const at = usage ? `Context is at ${usageText(usage)}. ` : "";
+    const how = "You cannot compact yourself: ask the user to run /compact, and give them a one line note of what to keep, for example /compact keep the billing fix and its failing test.";
+    switch (d.tier) {
+        case "notice":
+            return `${at}${d.reason} Compacting is optional. At a clean point you may suggest it. ${how}`;
+        case "recommend":
+            return `Recommended: compact soon. ${at}${d.reason} When you reply, suggest it. ${how}`;
+        case "request":
+            return `Please ask the user to compact before continuing. ${at}${d.reason} ${how}`;
+        default:
+            return null;
+    }
+}

package/dist/core/client.d.ts

@@ -0,0 +1,93 @@
+import { type Questions, type State, type SystemOneRequest, type SystemOneResponse } from "./types.ts";
+export type JevProvider = "mock" | "openrouter" | "typesafe";
+/** Caller-supplied USD prices; no assumed provider/model rates. */
+export interface JevPricing {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}
+export type JevCost = {
+    amount: number;
+    source: "reported" | "estimated" | "mock";
+} | {
+    amount: null;
+    source: "unknown";
+};
+export interface JevClientOptions {
+    /** Overrides test isolation, JEV_BACKEND, and automatic key-based selection. */
+    provider?: JevProvider;
+    /** Requires opts.provider to explicitly name a live provider. */
+    apiKey?: string;
+    /** Full endpoint URL (not an origin). Redirects are refused. */
+    baseUrl?: string;
+    /** Pin a versioned model ID instead of the moving alias. */
+    model?: string;
+    /** Total budget including retries and response bodies. Default: 30,000 ms. */
+    timeoutMs?: number;
+    /** Exponential backoff base, plus up to 20% jitter. Default: 500 ms; 0 is allowed. */
+    retryDelayMs?: number;
+    /** Used only when usage.cost is not a valid reported cost. Snapshotted at construction. */
+    pricing?: JevPricing;
+}
+export interface JevRawExchange {
+    /** Snapshot of the JSON sent; no credentials or headers. */
+    request: SystemOneRequest;
+    requestText: string;
+    /** Unenriched provider payload, including unknown fields. */
+    response: SystemOneResponse;
+    /** Exact response body text; mock responses use synthetic JSON. */
+    responseText: string;
+}
+export interface SystemOneResult extends SystemOneResponse {
+    raw: JevRawExchange;
+    meta: {
+        provider: JevProvider;
+        requestedModel: string;
+        resolvedModel: string;
+        elapsedMs: number;
+        attempts: number;
+        /** USD, or null when no trustworthy cost is available. */
+        cost: JevCost;
+    };
+}
+export declare class ContractError extends Error {
+    constructor(message: string);
+}
+/** Live observation of every call — the web layer streams these to the UI. */
+export type JevEvent = {
+    kind: "request";
+    provider: JevProvider;
+    model: string;
+    state: State;
+    questions: Questions;
+} | {
+    kind: "response";
+    result: SystemOneResult;
+};
+export declare class JevClient {
+    readonly provider: JevProvider;
+    private readonly apiKey?;
+    private readonly endpoint?;
+    private readonly mock;
+    private readonly model?;
+    private readonly timeoutMs;
+    private readonly retryDelayMs;
+    private readonly pricing?;
+    private listeners;
+    /** Count of validated systemOne calls, for the demo's cost story. */
+    calls: number;
+    constructor(opts?: JevClientOptions);
+    get isLive(): boolean;
+    /** Observe every request and response this client makes. */
+    on(listener: (event: JevEvent) => void): () => void;
+    private emit;
+    systemOne(state: State, questions: Questions, opts?: {
+        model?: string;
+        signal?: AbortSignal;
+    }): Promise<SystemOneResult>;
+}
+/** Strict live contract; unknown payload fields are deliberately retained. */
+export declare function validateResponse(response: unknown, questions: Questions): asserts response is SystemOneResponse;
+/** Lazily constructed; provider and credentials resolve only on first use. */
+export declare function sharedJev(): JevClient;
+/** Shared client for every level. Use JEV_BACKEND=mock for an offline demo. */
+export declare const jev: JevClient;

package/dist/core/client.js

@@ -0,0 +1,295 @@
+/**
+ * JevClient — a provider and credential snapshot, with no runtime fallback.
+ * Auto-selection prefers TypeSafe, then OpenRouter. Mock requires an explicit
+ * selection or node:test isolation; missing production credentials fail closed.
+ */
+import { MockJev } from "./mock.js";
+import { QuestionValidationError, validateRequest, } from "./types.js";
+const ENDPOINTS = {
+    openrouter: "https://openrouter.ai/api/alpha/decisions",
+    typesafe: "https://api.typesafe.ai/v1/systemone",
+};
+const DEFAULT_MODELS = {
+    openrouter: "~typesafe/jev-latest",
+    typesafe: "jev-latest",
+};
+const KEY_ENV = {
+    openrouter: "OPENROUTER_API_KEY",
+    typesafe: "TYPESAFE_API_KEY",
+};
+const RETRY_STATUSES = new Set([429, 502, 503, 529]);
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ATTEMPTS = 3;
+export class ContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContractError";
+    }
+}
+export class JevClient {
+    provider;
+    apiKey;
+    endpoint;
+    mock = new MockJev();
+    model;
+    timeoutMs;
+    retryDelayMs;
+    pricing;
+    listeners = [];
+    /** Count of validated systemOne calls, for the demo's cost story. */
+    calls = 0;
+    constructor(opts = {}) {
+        if (opts.apiKey !== undefined && opts.provider !== "typesafe" && opts.provider !== "openrouter") {
+            throw new Error("apiKey requires an explicit live opts.provider (typesafe or openrouter).");
+        }
+        this.provider = selectProvider(opts.provider);
+        this.model = opts.model;
+        this.timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
+        this.retryDelayMs = opts.retryDelayMs ?? 500;
+        if (!Number.isInteger(this.timeoutMs) || this.timeoutMs <= 0 || this.timeoutMs > 2_147_483_647) {
+            throw new Error("timeoutMs must be a positive integer no greater than 2147483647.");
+        }
+        if (!isNonnegative(this.retryDelayMs))
+            throw new Error("retryDelayMs must be finite and nonnegative.");
+        if (opts.pricing !== undefined) {
+            if (!opts.pricing || !isNonnegative(opts.pricing.inputPerMillion) || !isNonnegative(opts.pricing.outputPerMillion)) {
+                throw new Error("pricing requires finite, nonnegative inputPerMillion and outputPerMillion USD rates.");
+            }
+            this.pricing = { ...opts.pricing };
+        }
+        if (this.provider === "mock")
+            return;
+        this.apiKey = (opts.apiKey ?? process.env[KEY_ENV[this.provider]])?.trim();
+        this.endpoint = opts.baseUrl ?? ENDPOINTS[this.provider];
+        if (!this.apiKey) {
+            throw new Error(`Provider "${this.provider}" needs a nonblank apiKey or ${KEY_ENV[this.provider]}.`);
+        }
+    }
+    get isLive() {
+        return this.provider !== "mock";
+    }
+    /** Observe every request and response this client makes. */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners)
+            listener(event);
+    }
+    async systemOne(state, questions, opts = {}) {
+        opts.signal?.throwIfAborted();
+        const requestedModel = opts.model ?? this.model ??
+            (this.provider === "mock" ? this.mock.model : DEFAULT_MODELS[this.provider]);
+        const body = { model: requestedModel, state, questions };
+        validateRequest(body);
+        let requestText;
+        try {
+            requestText = JSON.stringify(body);
+        }
+        catch {
+            throw new QuestionValidationError("Request must be JSON-serializable (no cycles or BigInt).");
+        }
+        const request = JSON.parse(requestText);
+        // Validate the actual wire snapshot too (e.g. user-defined toJSON methods).
+        validateRequest(request);
+        this.calls++;
+        const started = performance.now();
+        this.emit({ kind: "request", provider: this.provider, model: requestedModel, state, questions });
+        if (this.provider === "mock") {
+            opts.signal?.throwIfAborted();
+            const response = this.mock.systemOne(request);
+            const raw = { request, requestText, response, responseText: JSON.stringify(response) };
+            const out = withMeta(raw, this.provider, requestedModel, started, 1, this.pricing);
+            this.emit({ kind: "response", result: out });
+            return out;
+        }
+        const deadline = new AbortController();
+        const timer = setTimeout(() => {
+            deadline.abort(new DOMException("Jev request timed out.", "TimeoutError"));
+        }, this.timeoutMs);
+        const signal = opts.signal ? AbortSignal.any([deadline.signal, opts.signal]) : deadline.signal;
+        try {
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                signal.throwIfAborted();
+                const res = await fetch(this.endpoint, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+                    body: requestText,
+                    signal,
+                    redirect: "error",
+                });
+                signal.throwIfAborted();
+                if (RETRY_STATUSES.has(res.status) && attempt < MAX_ATTEMPTS) {
+                    const backoff = this.retryDelayMs * 2 ** (attempt - 1) * (1 + Math.random() * 0.2);
+                    const delay = Math.min(8000, Math.max(backoff, retryAfterMs(res.headers.get("retry-after"))));
+                    await res.body?.cancel();
+                    await sleep(delay, signal);
+                    continue;
+                }
+                if (!res.ok) {
+                    await res.body?.cancel();
+                    const hint = res.status === 401 ? ` Check the ${KEY_ENV[this.provider]} key.`
+                        : res.status === 402 ? " Check account credits." : "";
+                    throw new Error(`${this.provider} HTTP ${res.status}.${hint}`);
+                }
+                const responseText = await res.text();
+                signal.throwIfAborted();
+                let response;
+                try {
+                    response = JSON.parse(responseText);
+                }
+                catch {
+                    throw new ContractError("Invalid response JSON.");
+                }
+                validateResponse(response, request.questions);
+                const raw = { request, requestText, response, responseText };
+                const out = withMeta(raw, this.provider, requestedModel, started, attempt, this.pricing);
+                this.emit({ kind: "response", result: out });
+                return out;
+            }
+            throw new Error(`${this.provider} retries exhausted`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function selectProvider(explicit) {
+    // node:test cannot accidentally use ambient live credentials/overrides.
+    // Explicit opts.provider or the existing JEV_LIVE=1 opt-in bypass isolation.
+    const isolated = process.env.NODE_TEST_CONTEXT && process.env.JEV_LIVE !== "1";
+    const selected = explicit ?? (isolated ? "mock" : process.env.JEV_BACKEND?.trim() || undefined);
+    if (selected !== undefined) {
+        if (selected === "mock" || selected === "typesafe" || selected === "openrouter")
+            return selected;
+        throw new Error(`Unknown JEV backend "${selected}"; use mock, openrouter, or typesafe.`);
+    }
+    if (process.env.TYPESAFE_API_KEY?.trim())
+        return "typesafe";
+    if (process.env.OPENROUTER_API_KEY?.trim())
+        return "openrouter";
+    throw new Error("No Jev credentials: set TYPESAFE_API_KEY or OPENROUTER_API_KEY, or explicitly select provider: mock / JEV_BACKEND=mock for offline use.");
+}
+function resultCost(response, provider, pricing) {
+    if (provider === "mock")
+        return { amount: 0, source: "mock" };
+    if (isNonnegative(response.usage.cost))
+        return { amount: response.usage.cost, source: "reported" };
+    if (pricing) {
+        const amount = response.usage.input_tokens / 1_000_000 * pricing.inputPerMillion +
+            response.usage.output_tokens / 1_000_000 * pricing.outputPerMillion;
+        if (isNonnegative(amount))
+            return { amount, source: "estimated" };
+    }
+    return { amount: null, source: "unknown" };
+}
+function withMeta(raw, provider, requestedModel, started, attempts, pricing) {
+    return {
+        // Separate nested answers/usage from raw; enrichment never edits provider data.
+        ...structuredClone(raw.response),
+        raw,
+        meta: {
+            provider,
+            requestedModel,
+            resolvedModel: raw.response.model,
+            elapsedMs: Math.round(performance.now() - started),
+            attempts,
+            cost: resultCost(raw.response, provider, pricing),
+        },
+    };
+}
+/** Ignore malformed/negative values instead of letting NaN erase the backoff. */
+function retryAfterMs(header) {
+    if (!header?.trim())
+        return 0;
+    const value = header.trim();
+    if (/^\d+(?:\.\d+)?$/.test(value)) {
+        const ms = Number(value) * 1000;
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    // HTTP-date forms begin with a weekday; Date.parse alone also accepts "-1".
+    if (!/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)/i.test(value))
+        return 0;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(signal.reason);
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isNonnegative = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0;
+const isUnit = (x) => isNonnegative(x) && x <= 1;
+const isTokenCount = (x) => isNonnegative(x) && Number.isSafeInteger(x);
+/** Strict live contract; unknown payload fields are deliberately retained. */
+export function validateResponse(response, questions) {
+    if (!isObject(response) || !isObject(response.answers) || typeof response.model !== "string" || !response.model.trim()) {
+        throw new ContractError("Invalid response envelope: expected model and answers.");
+    }
+    if (!isObject(response.usage) || !isTokenCount(response.usage.input_tokens) || !isTokenCount(response.usage.output_tokens)) {
+        throw new ContractError("Invalid response usage: expected nonnegative integer input_tokens and output_tokens.");
+    }
+    for (const [id, q] of Object.entries(questions)) {
+        const answer = response.answers[id];
+        if (!Object.hasOwn(response.answers, id) || !isObject(answer) || answer.type !== q.type) {
+            throw new ContractError(`Missing or mismatched answer: ${id}`);
+        }
+        if (q.type === "noul") {
+            if (!isUnit(answer.noul))
+                throw new ContractError(`Invalid noul: ${id}`);
+            continue;
+        }
+        if (!isUnit(answer.confidence) || !isObject(answer.probabilities)) {
+            throw new ContractError(`Invalid distribution: ${id}`);
+        }
+        const keys = q.type === "choice" ? Object.keys(q.criteria) : q.criteria.map((_, i) => String(i));
+        const probs = answer.probabilities;
+        if (Object.keys(probs).length !== keys.length || !keys.every((k) => Object.hasOwn(probs, k) && isUnit(probs[k]))) {
+            throw new ContractError(`Distribution keys must match the declared criteria: ${id}`);
+        }
+        const sum = keys.reduce((acc, k) => acc + probs[k], 0);
+        if (Math.abs(sum - 1) > 0.025)
+            throw new ContractError(`Distribution does not sum to one: ${id} (${sum})`);
+        if (q.type === "choice" && (typeof answer.choice !== "string" || !keys.includes(answer.choice))) {
+            throw new ContractError(`Undeclared choice returned: ${id}`);
+        }
+        if (q.type === "score") {
+            if (!isNonnegative(answer.score) || answer.score > keys.length - 1) {
+                throw new ContractError(`Score out of range: ${id}`);
+            }
+            const legend = answer.legend;
+            if (!isObject(legend) || Object.keys(legend).length !== keys.length ||
+                !keys.every((k, i) => Object.hasOwn(legend, k) && legend[k] === q.criteria[i])) {
+                throw new ContractError(`Score legend must match the declared criteria: ${id}`);
+            }
+        }
+    }
+}
+let _shared;
+/** Lazily constructed; provider and credentials resolve only on first use. */
+export function sharedJev() {
+    if (!_shared)
+        _shared = new JevClient();
+    return _shared;
+}
+/** Shared client for every level. Use JEV_BACKEND=mock for an offline demo. */
+export const jev = new Proxy({}, {
+    get(_target, prop) {
+        const value = sharedJev()[prop];
+        return typeof value === "function" ? value.bind(sharedJev()) : value;
+    },
+});

package/dist/core/helpers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Question builders, matching the @typesafe-ai/sdk helper style.
+ * Answer types are inferred from the question you build.
+ */
+import type { ChoiceAnswer, ChoiceCriteria, ChoiceQuestion, Instructions, NoulAnswer, NoulCriteria, NoulQuestion, Question, ScoreAnswer, ScoreCriteria, ScoreQuestion } from "./types.ts";
+export declare function noul(instructions: Instructions, criteria?: NoulCriteria): NoulQuestion;
+export declare function choice(instructions: Instructions, criteria: ChoiceCriteria): ChoiceQuestion;
+export declare function score(instructions: Instructions, criteria: ScoreCriteria): ScoreQuestion;
+/** Infer the answer type a question returns. */
+export type AnswerOf<Q> = Q extends NoulQuestion ? NoulAnswer : Q extends ChoiceQuestion ? ChoiceAnswer : Q extends ScoreQuestion ? ScoreAnswer : never;
+/** Typed question map -> typed answer map. */
+export type AnswersOf<Q extends Record<string, Question>> = {
+    [K in keyof Q]: AnswerOf<Q[K]>;
+};

package/dist/core/helpers.js

@@ -0,0 +1,9 @@
+export function noul(instructions, criteria) {
+    return criteria ? { type: "noul", instructions, criteria } : { type: "noul", instructions };
+}
+export function choice(instructions, criteria) {
+    return { type: "choice", instructions, criteria };
+}
+export function score(instructions, criteria) {
+    return { type: "score", instructions, criteria };
+}

package/dist/core/mock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MockJev — a deterministic, offline stand-in for the real System One endpoint.
+ *
+ * It exists so every level in this codebase runs (and its tests pass) without an
+ * API key. It mimics the exact wire contract: typed answers, probability
+ * distributions that sum to 1, legends on scores, and confidence derived from
+ * how peaked the distribution is.
+ *
+ * How it decides: token overlap between the flattened state and each option /
+ * level / criteria description, run through a softmax. It is a stand-in for
+ * *shape*, not for intelligence — with a real key, the same code paths hit
+ * https://api.typesafe.ai/v1/systemone and nothing else changes.
+ */
+import type { State, SystemOneRequest, SystemOneResponse } from "./types.ts";
+/** Flatten any state shape into text the overlap engine can read. */
+export declare function flattenState(state: State): string;
+export declare class MockJev {
+    readonly model = "jev-1.13.0-mock";
+    systemOne(req: SystemOneRequest): SystemOneResponse;
+}

package/dist/core/mock.js

@@ -0,0 +1,132 @@
+const STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "but", "if", "then", "than", "of", "to", "in", "on", "at", "for",
+    "with", "without", "is", "are", "was", "were", "be", "been", "being", "do", "does", "did", "done",
+    "this", "that", "these", "those", "it", "its", "as", "by", "from", "into", "about", "against",
+    "between", "through", "during", "before", "after", "above", "below", "up", "down", "out", "off",
+    "over", "under", "again", "further", "once", "here", "there", "when", "where", "why", "how",
+    "all", "any", "both", "each", "few", "more", "most", "other", "some", "such", "no", "nor", "not",
+    "only", "own", "same", "so", "too", "very", "s", "t", "can", "will", "just", "don", "should",
+    "now", "d", "ll", "m", "o", "re", "ve", "y", "i", "you", "we", "they", "he", "she", "what",
+    "which", "who", "whom", "am", "has", "have", "had", "having", "message", "text", "given",
+]);
+function stem(t) {
+    if (t.length > 4 && t.endsWith("ing"))
+        return t.slice(0, -3);
+    if (t.length > 4 && t.endsWith("ed"))
+        return t.slice(0, -2);
+    if (t.length > 3 && t.endsWith("es"))
+        return t.slice(0, -2);
+    if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
+        return t.slice(0, -1);
+    return t;
+}
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .replace(/[`_*#>/\[\]{}()"',.;:!?\\-]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 1 && !STOPWORDS.has(t))
+        .map(stem));
+}
+/** Flatten any state shape into text the overlap engine can read. */
+export function flattenState(state) {
+    if (typeof state === "string")
+        return state;
+    return JSON.stringify(state, null, 2);
+}
+function instructionsText(q) {
+    if (typeof q.instructions === "string")
+        return q.instructions;
+    return JSON.stringify(q.instructions);
+}
+function softmax(values, temperature = 0.6) {
+    if (values.every((v) => v === 0)) {
+        return values.map(() => 1 / values.length);
+    }
+    const max = Math.max(...values);
+    const exps = values.map((v) => Math.exp((v - max) / temperature));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+}
+/** Affinity: how many meaningful tokens the state shares with a description, weighted by rarity-free overlap. */
+function affinity(stateTokens, description) {
+    const descTokens = tokenize(description);
+    let shared = 0;
+    for (const t of descTokens)
+        if (stateTokens.has(t))
+            shared++;
+    return shared;
+}
+function round(n, places = 4) {
+    const f = 10 ** places;
+    return Math.round(n * f) / f;
+}
+function noulAnswer(q, stateTokens) {
+    const yesText = instructionsText(q) + " " + (q.criteria?.true ?? "");
+    const noText = q.criteria?.false ?? "";
+    const yes = affinity(stateTokens, yesText);
+    const no = affinity(stateTokens, noText);
+    // Smoothed signal in [-1, 1]; logistic to [0, 1]. No signal -> 0.5.
+    const k = 2.5;
+    const signal = (yes - no) / (yes + no + k);
+    const p = 1 / (1 + Math.exp(-4 * signal));
+    return { type: "noul", noul: round(p) };
+}
+function choiceAnswer(q, stateTokens) {
+    const entries = Object.entries(q.criteria);
+    const affinities = entries.map(([option, desc]) => {
+        const keyText = option.replace(/_/g, " ");
+        return affinity(stateTokens, keyText) * 1.5 + affinity(stateTokens, desc ?? "") * 1.0;
+    });
+    const probs = softmax(affinities);
+    const probabilities = {};
+    entries.forEach(([option], i) => (probabilities[option] = round(probs[i])));
+    let best = 0;
+    entries.forEach((_, i) => {
+        if (probs[i] > probs[best])
+            best = i;
+    });
+    return {
+        type: "choice",
+        choice: entries[best][0],
+        probabilities,
+        confidence: round(probs[best]),
+    };
+}
+function scoreAnswer(q, stateTokens) {
+    const affinities = q.criteria.map((level) => affinity(stateTokens, level) + 1e-9);
+    const probs = softmax(affinities);
+    const legend = {};
+    q.criteria.forEach((level, i) => (legend[String(i)] = level));
+    const probabilities = {};
+    q.criteria.forEach((_, i) => (probabilities[String(i)] = round(probs[i])));
+    const scoreValue = probs.reduce((acc, p, i) => acc + p * i, 0);
+    const confidence = Math.max(...probs);
+    return {
+        type: "score",
+        score: round(scoreValue, 2),
+        legend,
+        probabilities,
+        confidence: round(confidence),
+    };
+}
+export class MockJev {
+    model = "jev-1.13.0-mock";
+    systemOne(req) {
+        const stateTokens = tokenize(flattenState(req.state));
+        const answers = {};
+        for (const [id, q] of Object.entries(req.questions)) {
+            if (q.type === "noul")
+                answers[id] = noulAnswer(q, stateTokens);
+            else if (q.type === "choice")
+                answers[id] = choiceAnswer(q, stateTokens);
+            else
+                answers[id] = scoreAnswer(q, stateTokens);
+        }
+        const usage = {
+            input_tokens: Math.ceil(flattenState(req.state).length / 4) + 20 * Object.keys(req.questions).length,
+            output_tokens: 20 * Object.keys(req.questions).length,
+        };
+        return { model: this.model, answers, usage };
+    }
+}