@loomwork/reasoning 0.0.0-stage → 0.1.1

package/dist/router.d.ts

@@ -0,0 +1,39 @@
+import type { Router } from "./types";
+export declare const tagRouter: Router;
+export interface ArmStats {
+    key: string;
+    /** Mean reward. Higher = better. */
+    rank: number;
+    /** How many outcomes produced `rank`. */
+    count: number;
+}
+/** Rankings with counts (preferred) or the legacy count-free record. */
+export type Rankings = Record<string, number> | readonly ArmStats[];
+export interface RankedRouterOptions {
+    /**
+     * Sample floor. Arms with fewer than this many outcomes are treated as UNRANKED
+     * rather than as evidence — the fix for "one lucky success at n=1 outranks a
+     * proven arm at n=10000 forever". Requires `ArmStats[]`; a count-free record
+     * throws at construction rather than silently no-opping the floor.
+     */
+    minSamples?: number;
+    /** Router for unranked/under-sampled requests. Default: cheap-first `tagRouter`. */
+    fallback?: Router;
+}
+export declare function rankedRouter(rankings: Rankings, opts?: RankedRouterOptions): Router;
+export interface Ucb1Options {
+    /** Exploration weight. 1 = textbook UCB1; lower is greedier, 0 is pure exploit. */
+    exploration?: number;
+    /** Router for the cold start (no samples at all). Default: cheap-first `tagRouter`. */
+    fallback?: Router;
+}
+export declare function ucb1(stats: readonly ArmStats[], opts?: Ucb1Options): Router;
+export interface EpsilonGreedyOptions {
+    /** Probability in [0,1] of sampling a uniformly random route instead of exploiting. */
+    epsilon: number;
+    /** Injected RNG (default `Math.random`). Pass a seeded PRNG for tests and DST runs. */
+    rng?: () => number;
+}
+export declare function epsilonGreedy(inner: Router, opts: EpsilonGreedyOptions): Router;
+export declare function fixedRouter(modelId: string): Router;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgC,MAAM,EAAE,MAAM,SAAS,CAAC;AASpE,eAAO,MAAM,SAAS,EAAE,MAYvB,CAAC;AASF,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wEAAwE;AACxE,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,QAAQ,EAAE,CAAC;AAoBpE,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgBD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAqCvF;AAED,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAYD,wBAAgB,IAAI,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,MAAM,CAoC/E;AAED,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAgB/E;AAID,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnD"}

package/dist/router.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagRouter = void 0;
+exports.rankedRouter = rankedRouter;
+exports.ucb1 = ucb1;
+exports.epsilonGreedy = epsilonGreedy;
+exports.fixedRouter = fixedRouter;
+// Default routing policy: the lowest-tier route whose tags include the request's
+// strategy, else the lowest-tier route overall. This implements "use the cheap
+// model first; elevate only when confidence is low" (the P3 elevation ladder).
+//
+// Contract: `routes` are expected tier-ascending. ReasoningRuntime owns the sort
+// (once, at construction) and always passes its sorted `routes`, so this router
+// takes the first tag/overall match without re-sorting on every call.
+exports.tagRouter = {
+    select(req, routes) {
+        if (req.strategy !== undefined) {
+            const tagged = routes.find((r) => r.tags?.includes(req.strategy));
+            if (tagged !== undefined)
+                return tagged;
+        }
+        const first = routes[0];
+        if (first === undefined) {
+            throw new Error("ReasoningRuntime: no routes configured");
+        }
+        return first;
+    },
+};
+function indexRankings(rankings) {
+    if (Array.isArray(rankings)) {
+        const m = new Map();
+        for (const s of rankings)
+            m.set(s.key, { rank: s.rank, count: s.count });
+        return m;
+    }
+    const m = new Map();
+    for (const [key, rank] of Object.entries(rankings))
+        m.set(key, { rank });
+    return m;
+}
+// M10 self-optimization — a "learned" router. Given a ranking (e.g. from
+// @loomwork/analytics `rankModels`/`outcomeAnalytics`, mined from historical logs),
+// prefer the highest-ranked route that exists, falling back to cheap-first
+// (`tagRouter`) for unranked requests. Used inside ReasoningRuntime with
+// `ctx.decide`, its choice is recorded as a durable decision (P9) — auditable and
+// override-able, never silently autonomous (P10).
+//
+// PURE EXPLOIT. This router never tries an arm to learn about it: an arm absent
+// from `rankings` can never be selected while any other arm is ranked, so a
+// ranking mined from a log that this router itself produced will narrow over time
+// (the arms it stops choosing stop generating outcomes). `minSamples` bounds the
+// damage from thin evidence, but if you want the loop to keep learning, wrap it —
+// `epsilonGreedy(rankedRouter(stats), { epsilon: 0.1 })` — or use `ucb1`, which
+// allocates exploration by uncertainty instead of by coin flip.
+function rankedRouter(rankings, opts = {}) {
+    // Index the ranking once at construction; each select is then a single O(R)
+    // max-scan instead of an O(R log R) filter+sort per call (routing decisions
+    // are on the reasoning hot path). Ties keep the tier-ascending order the
+    // caller passes — the first route holding the max rank wins, which is exactly
+    // what a stable sort's `[0]` yielded.
+    const rank = indexRankings(rankings);
+    const minSamples = opts.minSamples ?? 0;
+    const fallback = opts.fallback ?? exports.tagRouter;
+    if (minSamples > 0) {
+        for (const arm of rank.values()) {
+            if (arm.count === undefined) {
+                throw new Error("rankedRouter: minSamples needs sample counts — pass ArmStats[] " +
+                    "(e.g. outcomeAnalytics(events)), not a count-free rankings record");
+            }
+        }
+    }
+    return {
+        select(req, routes) {
+            let best;
+            let bestRank = Number.NEGATIVE_INFINITY;
+            for (const r of routes) {
+                const arm = rank.get(r.id);
+                if (arm === undefined)
+                    continue;
+                if (arm.count !== undefined && arm.count < minSamples)
+                    continue;
+                if (arm.rank > bestRank) {
+                    bestRank = arm.rank;
+                    best = r;
+                }
+            }
+            return best ?? fallback.select(req, routes);
+        },
+    };
+}
+// UCB1 — the principled fix for the ranked router's collapse, and the recommended
+// default for a live learning loop. Scores each arm `mean + c·sqrt(2·ln N / n)`:
+// the bonus is large while an arm is under-sampled and shrinks as evidence
+// accumulates, so a lucky n=1 arm cannot pin the router (its rivals keep their own
+// large bonus until they are tried too) and an arm with NO samples scores +Inf and
+// is guaranteed a trial. Deterministic — no RNG — which is what you want in a
+// replay-first runtime: the same evidence always yields the same route.
+//
+// Assumes rewards on a comparable scale (the [0,1] of `success`/normalized `score`
+// that `outcomeAnalytics` produces); `exploration` is the knob if yours differ.
+function ucb1(stats, opts = {}) {
+    const c = opts.exploration ?? 1;
+    const fallback = opts.fallback ?? exports.tagRouter;
+    // Fold the evidence once at construction — per-select work is then one O(R)
+    // scan with no logarithm (`lnTotal` is loop-invariant across every select).
+    const arms = new Map();
+    let total = 0;
+    for (const s of stats) {
+        arms.set(s.key, s);
+        total += s.count;
+    }
+    const lnTotal = Math.log(total);
+    return {
+        select(req, routes) {
+            if (total === 0)
+                return fallback.select(req, routes);
+            let best;
+            let bestScore = Number.NEGATIVE_INFINITY;
+            for (const r of routes) {
+                const arm = arms.get(r.id);
+                // Never sampled → must-try. Ties resolve to the first route, so a cold
+                // start walks the tier-ascending ladder one trial at a time.
+                const score = arm === undefined || arm.count <= 0
+                    ? Number.POSITIVE_INFINITY
+                    : arm.rank + c * Math.sqrt((2 * lnTotal) / arm.count);
+                if (score > bestScore) {
+                    bestScore = score;
+                    best = r;
+                }
+            }
+            return best ?? fallback.select(req, routes);
+        },
+    };
+}
+// ε-greedy — the simplest way to stop any exploit-only router from starving its
+// own evidence: with probability ε ignore `inner` and sample a route uniformly.
+//
+// The randomness is replay-safe WHERE IT MATTERS: ReasoningRuntime resolves the
+// route inside `ctx.decide`, so the sampled id is committed as DECISION_RECORDED
+// and replay serves that recording back — `select` is never called again and the
+// RNG is never re-rolled. Standalone callers (no `decide` sink) get no such
+// guarantee; inject `rng` if you need them reproducible.
+function epsilonGreedy(inner, opts) {
+    const { epsilon } = opts;
+    if (!(epsilon >= 0 && epsilon <= 1)) {
+        throw new Error(`epsilonGreedy: epsilon must be in [0,1], got ${epsilon}`);
+    }
+    const rng = opts.rng ?? Math.random;
+    return {
+        select(req, routes) {
+            if (routes.length > 0 && rng() < epsilon) {
+                const picked = routes[Math.min(routes.length - 1, Math.floor(rng() * routes.length))];
+                if (picked !== undefined)
+                    return picked;
+            }
+            return inner.select(req, routes);
+        },
+    };
+}
+// A fixed router that always selects a specific model id — handy for tests and for
+// pinning a strategy to one model.
+function fixedRouter(modelId) {
+    return {
+        select(_req, routes) {
+            const route = routes.find((r) => r.id === modelId);
+            if (route === undefined) {
+                throw new Error(`ReasoningRuntime: fixedRouter target "${modelId}" not in routes`);
+            }
+            return route;
+        },
+    };
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

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

package/dist/routing.bench.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=routing.bench.d.ts.map

package/dist/routing.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.bench.d.ts","sourceRoot":"","sources":["../src/routing.bench.ts"],"names":[],"mappings":""}

package/dist/routing.bench.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const ReasoningRuntime_1 = require("./ReasoningRuntime");
+const router_1 = require("./router");
+// Benches for the two routing hot paths made O(1)/O(n):
+//   1. tagRouter no longer re-sorts the route list on every select().
+//   2. Elevation hops via a precomputed next-tier index instead of an O(n) scan,
+//      so walking a deep ladder is O(n) not O(n^2).
+class FakeProvider {
+    res;
+    constructor(res) {
+        this.res = res;
+    }
+    async complete() {
+        return this.res;
+    }
+}
+const weak = { content: "weak", stopReason: "max_tokens" };
+// Force elevation all the way up the ladder every call.
+const alwaysLow = { score: () => 0 };
+function makeRoutes(n) {
+    const provider = new FakeProvider(weak);
+    return Array.from({ length: n }, (_, i) => ({
+        id: `m${i}`,
+        provider,
+        tier: i,
+        ...(i === 0 && { tags: ["planning"] }),
+    }));
+}
+const routes = makeRoutes(64);
+(0, vitest_1.describe)("tagRouter.select over 64 routes", () => {
+    const req = { messages: [{ role: "user", content: "hi" }], strategy: "planning" };
+    (0, vitest_1.bench)("re-sort baseline (previous shape)", () => {
+        const sorted = [...routes].sort((a, b) => a.tier - b.tier);
+        sorted.find((r) => r.tags?.includes("planning"));
+    });
+    (0, vitest_1.bench)("tagRouter.select (pre-sorted, no re-sort)", () => {
+        router_1.tagRouter.select(req, routes);
+    });
+});
+(0, vitest_1.describe)("reason() full elevation up a 64-tier ladder", () => {
+    const runtime = new ReasoningRuntime_1.ReasoningRuntime({ routes, confidence: alwaysLow });
+    (0, vitest_1.bench)("reason (O(1) tier hops)", async () => {
+        await runtime.reason({ messages: [{ role: "user", content: "hi" }] });
+    });
+});
+//# sourceMappingURL=routing.bench.js.map

package/dist/routing.bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.bench.js","sourceRoot":"","sources":["../src/routing.bench.ts"],"names":[],"mappings":";;AACA,mCAAyC;AACzC,yDAAsD;AACtD,qCAAqC;AAGrC,wDAAwD;AACxD,sEAAsE;AACtE,iFAAiF;AACjF,oDAAoD;AAEpD,MAAM,YAAY;IACa;IAA7B,YAA6B,GAAgB;QAAhB,QAAG,GAAH,GAAG,CAAa;IAAG,CAAC;IACjD,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;CACF;AAED,MAAM,IAAI,GAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACxE,wDAAwD;AACxD,MAAM,SAAS,GAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC;AAEvD,SAAS,UAAU,CAAC,CAAS;IAC3B,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1C,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,QAAQ;QACR,IAAI,EAAE,CAAC;QACP,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;KACvC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;AAE9B,IAAA,iBAAQ,EAAC,iCAAiC,EAAE,GAAG,EAAE;IAC/C,MAAM,GAAG,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;IAE3F,IAAA,cAAK,EAAC,mCAAmC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,IAAA,cAAK,EAAC,2CAA2C,EAAE,GAAG,EAAE;QACtD,kBAAS,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAA,iBAAQ,EAAC,6CAA6C,EAAE,GAAG,EAAE;IAC3D,MAAM,OAAO,GAAG,IAAI,mCAAgB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAExE,IAAA,cAAK,EAAC,yBAAyB,EAAE,KAAK,IAAI,EAAE;QAC1C,MAAM,OAAO,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,134 @@
+import type { ContentResolveContext, ContentResolver, LlmContent, LlmMessageInput, LlmProvider, LlmResponse, LlmToolCall, LlmToolSpecInput } from "@loomwork/llm";
+export type DecideFn = <T = unknown>(decisionId: string, decider: () => T | Promise<T>) => Promise<T>;
+export interface ModelRoute {
+    id: string;
+    provider: LlmProvider;
+    tier: number;
+    /** Strategy hints (e.g. "planning", "coding", "review") for tag-based routing. */
+    tags?: string[];
+}
+export interface ReasoningRequest {
+    messages: LlmMessageInput[];
+    system?: LlmContent;
+    /** Picks a route by tag and namespaces the logged decisions. */
+    strategy?: string;
+    tools?: LlmToolSpecInput[];
+    maxTokens?: number;
+    temperature?: number;
+    signal?: AbortSignal;
+    /** Budget cap — never elevate above this tier. Default: the highest tier available. */
+    maxTier?: number;
+}
+export interface ReasoningTraceEntry {
+    modelId: string;
+    tier: number;
+    confidence: number;
+    elevated: boolean;
+}
+export interface ReasoningResult {
+    content: string;
+    toolCalls?: LlmToolCall[];
+    stopReason: LlmResponse["stopReason"];
+    usage?: LlmResponse["usage"];
+    /**
+     * ADR 0133 - the answering route's reasoning, as the call returned it. Through an effect-backed
+     * `invoke` these are recorded `LlmReasoningPart`s; a caller keeps only those (`type: "reasoning"`).
+     */
+    reasoning?: LlmResponse["reasoning"];
+    /** ADR 0133 D5 - the answering call's block order (positions only), so a transcript can reproduce the vendor sequence. */
+    layout?: LlmResponse["layout"];
+    modelId: string;
+    confidence: number;
+    elevated: boolean;
+    trace: ReasoningTraceEntry[];
+}
+export interface ConfidenceSignal {
+    score(req: ReasoningRequest, res: LlmResponse): number | Promise<number>;
+}
+export interface Router {
+    select(req: ReasoningRequest, routes: ModelRoute[]): ModelRoute;
+}
+export interface ReasoningCache {
+    get(key: string): LlmResponse | undefined;
+    set(key: string, value: LlmResponse): void;
+}
+/**
+ * The request a {@link ModelInvoker} receives: the reasoning request minus the routing-only
+ * fields and minus `signal` (a signal is not data — an effect-backed invoker gets its
+ * cancellation from the effect context, not from here).
+ */
+export interface ModelCallRequest {
+    messages: LlmMessageInput[];
+    system?: LlmContent;
+    tools?: LlmToolSpecInput[];
+    maxTokens?: number;
+    temperature?: number;
+}
+/**
+ * R9 — how a chosen route's model call is MADE. Without one, the runtime calls
+ * `route.provider.complete` directly, which is outside the effect ring (no K2 authorization,
+ * no metering, no kill switch). Supplying an invoker hands the call to the host so it can run
+ * as an effect: `agentLoop$` passes one that resolves each call through `ctx.execute`, so the
+ * call is authorized, metered, kill-switched and `guardRequest`-checked, and is JOURNALED —
+ * a replay serves the recorded response instead of re-calling the model.
+ *
+ * The runtime's response cache is BYPASSED when an invoker is supplied: a cache hit would skip
+ * the invoker, so whether a durable frame exists would depend on a process-local cache and a
+ * replay could diverge from the run.
+ */
+export type ModelInvoker = (route: ModelRoute, request: ModelCallRequest) => Promise<LlmResponse>;
+export interface ReasonOptionsBase {
+    /** When provided, route/elevation choices are recorded through it (P9). */
+    decide?: DecideFn;
+    /** R9 — make each model call through the host instead of the route's provider. See {@link ModelInvoker}. */
+    invoke?: ModelInvoker;
+    /**
+     * R10 — partition the response cache. The cache key is the request as written plus the route; two
+     * callers with an identical prompt would otherwise share a cached response. The runtime already
+     * adds the `resolveContext.principal` identity (tenant, actor, onBehalfOf) when it has one; a host
+     * that cannot hand over a principal (a runner body cannot read its own) passes a stable scope
+     * string here, e.g. the tenant id. Unset on a single-tenant host = one shared cache, as before.
+     *
+     * NOTE on metering: a cache hit makes no provider call, so on the direct path (no effect ring) it
+     * is not metered. That is the cache's purpose; a host that must meter every request routes the
+     * call through an effect (`invoke`), which bypasses this cache.
+     */
+    cacheScope?: string;
+    /**
+     * R10 — journal the live provider call. Unlike {@link invoke} (which REPLACES the call so the host
+     * can run it as an effect), this wraps it: the runtime still guards the request, checks the route's
+     * modalities and keys its response cache on the request as written, and hands the host only the
+     * part that touches the network (cache lookup, content resolution, `provider.complete`, cache
+     * fill) as `run`. The host records `run`'s result (`ctx.decide`) so a replay serves it and `run` is
+     * never called. Ignored when `invoke` is set.
+     */
+    wrapCall?: (route: ModelRoute, run: () => Promise<LlmResponse>) => Promise<LlmResponse>;
+    signal?: AbortSignal;
+    /** Namespaces decision ids so multiple reason() calls in one execution don't collide. */
+    decisionKey?: string;
+}
+/**
+ * R5 — fetch the bytes behind a media `ref` for the DIRECT (non-`invoke`) path, after the chosen
+ * route's capabilities have been checked and after the cache lookup (the cache is keyed on the
+ * request as written, i.e. on addresses, never on resolved bytes). Without it a ref is refused.
+ *
+ * `resolveContent` and `resolveContext` come TOGETHER (the type makes one without the other an
+ * error): the context is what lets a store authorize the read, and a resolver MUST deny a read whose
+ * `executionId` / `principal` it cannot attribute.
+ */
+export type ReasonOptions = ReasonOptionsBase & ({
+    resolveContent?: undefined;
+    resolveContext?: undefined;
+} | {
+    resolveContent: ContentResolver;
+    resolveContext: Pick<ContentResolveContext, "executionId" | "workflowId" | "stepId" | "principal">;
+});
+export interface ReasoningRuntimeConfig {
+    routes: ModelRoute[];
+    router?: Router;
+    confidence?: ConfidenceSignal;
+    /** Elevate while confidence < threshold and a higher tier is available. Default 0.5. */
+    elevateThreshold?: number;
+    cache?: ReasoningCache;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,WAAW,EACX,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAKvB,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,OAAO,EACjC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAC1B,OAAO,CAAC,CAAC,CAAC,CAAC;AAIhB,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,WAAW,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAK/B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,WAAW,EAAE,CAAC;IAC1B,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IACrC,0HAA0H;IAC1H,MAAM,CAAC,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,mBAAmB,EAAE,CAAC;CAC9B;AAID,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1E;AAGD,MAAM,WAAW,MAAM;IACrB,MAAM,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC;CACjE;AAID,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAC1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAElG,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,4GAA4G;IAC5G,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACxF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAC3C,CACI;IAAE,cAAc,CAAC,EAAE,SAAS,CAAC;IAAC,cAAc,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1D;IACE,cAAc,EAAE,eAAe,CAAC;IAChC,cAAc,EAAE,IAAI,CAClB,qBAAqB,EACrB,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,WAAW,CACtD,CAAC;CACH,CACJ,CAAC;AAEJ,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@loomwork/reasoning",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Reasoning runtime for Loom — model routing, confidence-based elevation, and critique as composable stages, with route decisions logged (P9)",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@loomwork/llm": "^0.1.1",
+    "@loomwork/classify": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "packages/reasoning"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }