@kernel.chat/kbot 4.0.0 → 4.1.0

package/README.md

@@ -36,6 +36,12 @@ Most terminal AI agents lock you into one provider, one model, one way of workin
 - **Programmatic SDK** — use kbot as a library in your own apps.
 - **MCP server built in** — plug kbot into Claude Code, Cursor, VS Code, Zed, or Neovim as a tool provider.
 
+## Benchmarks
+
+Methodology-explicit comparison vs other CLI agents → [BENCHMARKS.md](./BENCHMARKS.md). TL;DR: kbot beats Aider (4.4×) and OpenCode (5.7×) on cold start; loses to Claude Code, Codex, and jcode on raw boot but wins on cost-per-task (BYOK + Ollama fallback), vertical depth (Ableton/security/computer-use/channels), and offline availability (~70% of representative tasks).
+
+Using jcode? Wire kbot in as an MCP backend → [templates/jcode-integration.md](./templates/jcode-integration.md).
+
 ## Use with Claude Code / Cursor / Zed
 
 kbot is designed to compound with your existing AI editor, not replace it. One command wires everything up — MCP server config + a Claude Code skill that pre-authorizes the integration so safety filters don't refuse legitimate kbot calls.

package/dist/cache-warmth.d.ts

@@ -0,0 +1,25 @@
+/** Anthropic prompt cache TTL — 5 minutes */
+export declare const CACHE_TTL_MS: number;
+/** Hash a system prompt to a short stable key */
+export declare function hashPrompt(text: string): string;
+/** Reset in-memory cache (test hook) */
+export declare function _resetCacheWarmthCache(): void;
+/** Record a successful API call's timestamp */
+export declare function recordCacheCall(model: string, promptHash: string, now?: number): void;
+export interface CacheWarmthCheck {
+    warm: boolean;
+    ageMs?: number;
+    estimatedExtraCostUSD?: number;
+    message?: string;
+}
+/**
+ * Check whether the prompt cache is still warm for (model, promptHash).
+ * Returns warm=true if no prior call OR within TTL. Returns warm=false
+ * with a chalk.yellow message when cold AND we haven't warned for this
+ * specific cold-event yet.
+ *
+ * @param costPerMTokInput USD per million input tokens (from auth.ts)
+ * @param promptTokenEstimate rough token count (e.g. text.length / 4)
+ */
+export declare function checkCacheWarmth(model: string, promptHash: string, costPerMTokInput: number, promptTokenEstimate: number, now?: number): CacheWarmthCheck;
+//# sourceMappingURL=cache-warmth.d.ts.map

package/dist/cache-warmth.js

@@ -0,0 +1,131 @@
+// kbot Cache Warmth — Anthropic prompt cache TTL warning
+//
+// Anthropic's prompt cache has a 5-minute TTL. If the next API call lands
+// after the cache expired, the user pays full input-token price instead
+// of the cached price. This module tracks per-(model, prompt-hash) call
+// timestamps and warns once per cold event.
+//
+// State persists at ~/.kbot/cache-warmth.json (atomic tmp+rename writes).
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import chalk from 'chalk';
+/** Anthropic prompt cache TTL — 5 minutes */
+export const CACHE_TTL_MS = 5 * 60 * 1000;
+/** State file location — overridable via KBOT_CACHE_WARMTH_PATH (test hook) */
+function statePath() {
+    return process.env.KBOT_CACHE_WARMTH_PATH || join(homedir(), '.kbot', 'cache-warmth.json');
+}
+/** Hash a system prompt to a short stable key */
+export function hashPrompt(text) {
+    return createHash('md5').update(text).digest('hex').slice(0, 16);
+}
+let cached;
+function emptyState() {
+    return { lastCall: {}, warnedColdEvents: {} };
+}
+function loadState() {
+    if (cached)
+        return cached;
+    try {
+        const path = statePath();
+        if (!existsSync(path)) {
+            cached = emptyState();
+            return cached;
+        }
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        cached = {
+            lastCall: parsed.lastCall || {},
+            warnedColdEvents: parsed.warnedColdEvents || {},
+        };
+        return cached;
+    }
+    catch {
+        cached = emptyState();
+        return cached;
+    }
+}
+function saveState(state) {
+    try {
+        const path = statePath();
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(state), 'utf8');
+        renameSync(tmp, path);
+    }
+    catch {
+        // Non-fatal — state is best-effort
+    }
+}
+/** Reset in-memory cache (test hook) */
+export function _resetCacheWarmthCache() {
+    cached = undefined;
+}
+/** Build the composite key */
+function key(model, promptHash) {
+    return `${model}::${promptHash}`;
+}
+/** Record a successful API call's timestamp */
+export function recordCacheCall(model, promptHash, now = Date.now()) {
+    const state = loadState();
+    state.lastCall[key(model, promptHash)] = now;
+    saveState(state);
+}
+/** Format ms as "Nm Ss" */
+function formatAge(ms) {
+    const totalSec = Math.floor(ms / 1000);
+    const m = Math.floor(totalSec / 60);
+    const s = totalSec % 60;
+    return `${m}m ${s}s`;
+}
+/**
+ * Check whether the prompt cache is still warm for (model, promptHash).
+ * Returns warm=true if no prior call OR within TTL. Returns warm=false
+ * with a chalk.yellow message when cold AND we haven't warned for this
+ * specific cold-event yet.
+ *
+ * @param costPerMTokInput USD per million input tokens (from auth.ts)
+ * @param promptTokenEstimate rough token count (e.g. text.length / 4)
+ */
+export function checkCacheWarmth(model, promptHash, costPerMTokInput, promptTokenEstimate, now = Date.now()) {
+    if (process.env.KBOT_CACHE_WARMTH_WARN === 'off') {
+        return { warm: true };
+    }
+    const state = loadState();
+    const k = key(model, promptHash);
+    const last = state.lastCall[k];
+    // First call ever for this (model, prompt) — cache wasn't expected to exist
+    if (!last)
+        return { warm: true };
+    const ageMs = now - last;
+    if (ageMs <= CACHE_TTL_MS) {
+        return { warm: true, ageMs };
+    }
+    // Cold — but only warn once per cold-event (keyed on the prior lastCall ts)
+    const warned = state.warnedColdEvents[k] || [];
+    if (warned.includes(last)) {
+        return { warm: false, ageMs };
+    }
+    // Cost estimate: cached reads are ~10% of full input price; the cold
+    // call pays roughly 90% extra vs. the warm path it would have hit.
+    // We report the full input cost as the "extra" — a conservative upper
+    // bound that matches what the user actually pays for these tokens.
+    const extraUSD = (costPerMTokInput * promptTokenEstimate) / 1_000_000;
+    // Persist that we've warned so subsequent calls in the same cold-event
+    // (e.g. a tool loop) don't re-warn until a fresh warm window opens.
+    warned.push(last);
+    // Keep the list bounded
+    if (warned.length > 32)
+        warned.splice(0, warned.length - 32);
+    state.warnedColdEvents[k] = warned;
+    saveState(state);
+    const message = chalk.yellow(`[kbot] Anthropic prompt cache likely cold — last call was ${formatAge(ageMs)} ago (TTL is 5m). ` +
+        `This call will pay full input price (~$${extraUSD.toFixed(2)} more). ` +
+        `Run kbot doctor cache for tips.`);
+    return { warm: false, ageMs, estimatedExtraCostUSD: extraUSD, message };
+}
+//# sourceMappingURL=cache-warmth.js.map

package/dist/futures/debate/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public surface for the debate module.
+ */
+export type { DebateInput, AsymmetricRoles, DebateRound, Verdict, LLMClient, DebateOpts, TrainingExample, } from './types.js';
+export { runDebate, formatPrompt, parseVerdict } from './runner.js';
+export { synthesizeTrainingData, writeJsonl, loadJsonl, defaultJsonlPath, } from './synthesis.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/debate/index.js

@@ -0,0 +1,6 @@
+/**
+ * Public surface for the debate module.
+ */
+export { runDebate, formatPrompt, parseVerdict } from './runner.js';
+export { synthesizeTrainingData, writeJsonl, loadJsonl, defaultJsonlPath, } from './synthesis.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/debate/runner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Debate runner — orchestrates a 4-round asymmetric debate.
+ *
+ * Algorithm:
+ *   1. allow-advocate opens
+ *   2. block-advocate rebuts
+ *   3. allow-advocate counter-rebuts (if maxRounds >= 3)
+ *   4. block-advocate final (if maxRounds >= 4)
+ *   5. judge synthesizes a Verdict
+ *
+ * The LLM client is injected via opts.client. This module never imports
+ * a provider SDK. Tests use a deterministic stub.
+ */
+import type { AsymmetricRoles, DebateInput, DebateOpts, DebateRound, Verdict } from './types.js';
+/**
+ * Compose the role-specific prompt with the debate history.
+ * Exported so tests and synthesis can verify prompt shape.
+ */
+export declare function formatPrompt(input: DebateInput, role: AsymmetricRoles, history: DebateRound[]): string;
+/**
+ * Parse the judge's free-form text into a structured verdict body.
+ * Falls back to undecided/0 when fields are missing or malformed.
+ */
+export declare function parseVerdict(judgeText: string): {
+    label: Verdict['label'];
+    confidence: number;
+    rationale: string;
+};
+/**
+ * Run the debate end-to-end and return a Verdict.
+ * Order is fixed: allow → block → allow → block → judge.
+ */
+export declare function runDebate(input: DebateInput, opts: DebateOpts): Promise<Verdict>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/futures/debate/runner.js

@@ -0,0 +1,140 @@
+/**
+ * Debate runner — orchestrates a 4-round asymmetric debate.
+ *
+ * Algorithm:
+ *   1. allow-advocate opens
+ *   2. block-advocate rebuts
+ *   3. allow-advocate counter-rebuts (if maxRounds >= 3)
+ *   4. block-advocate final (if maxRounds >= 4)
+ *   5. judge synthesizes a Verdict
+ *
+ * The LLM client is injected via opts.client. This module never imports
+ * a provider SDK. Tests use a deterministic stub.
+ */
+const DEFAULT_MAX_ROUNDS = 4;
+/**
+ * Compose the role-specific prompt with the debate history.
+ * Exported so tests and synthesis can verify prompt shape.
+ */
+export function formatPrompt(input, role, history) {
+    const ctx = input.context ? `\nContext:\n${input.context}\n` : '';
+    const cat = input.categoryHint ? `\nCategory hint: ${input.categoryHint}\n` : '';
+    const transcript = history.length === 0
+        ? '(no prior arguments)'
+        : history
+            .map((r, i) => `[Round ${i + 1} — ${r.role}]\n${r.argument}`)
+            .join('\n\n');
+    if (role === 'allow-advocate') {
+        return [
+            `You are the ALLOW-ADVOCATE in an asymmetric debate.`,
+            `Argue why the candidate input below is SAFE TO ALLOW.`,
+            `Be specific, cite reasons grounded in the candidate's content.`,
+            ctx,
+            cat,
+            `Candidate:\n${input.candidate}`,
+            ``,
+            `Debate so far:\n${transcript}`,
+            ``,
+            `Write your argument. Do not include a verdict — that is the judge's role.`,
+        ].join('\n');
+    }
+    if (role === 'block-advocate') {
+        return [
+            `You are the BLOCK-ADVOCATE in an asymmetric debate.`,
+            `Argue why the candidate input below MUST BE BLOCKED.`,
+            `Be specific, cite concrete harms or policy violations.`,
+            ctx,
+            cat,
+            `Candidate:\n${input.candidate}`,
+            ``,
+            `Debate so far:\n${transcript}`,
+            ``,
+            `Write your argument. Do not include a verdict — that is the judge's role.`,
+        ].join('\n');
+    }
+    // judge
+    return [
+        `You are the JUDGE in an asymmetric debate.`,
+        `Read both advocates' arguments and produce a verdict.`,
+        `Output exactly two lines, then a brief rationale:`,
+        `LABEL: allow | block | undecided`,
+        `CONFIDENCE: 0.00 - 1.00`,
+        `RATIONALE: <one or two sentences>`,
+        ctx,
+        cat,
+        `Candidate:\n${input.candidate}`,
+        ``,
+        `Full transcript:\n${transcript}`,
+    ].join('\n');
+}
+/**
+ * Parse the judge's free-form text into a structured verdict body.
+ * Falls back to undecided/0 when fields are missing or malformed.
+ */
+export function parseVerdict(judgeText) {
+    const labelMatch = judgeText.match(/LABEL:\s*(allow|block|undecided)/i);
+    const confMatch = judgeText.match(/CONFIDENCE:\s*([0-9]*\.?[0-9]+)/i);
+    const ratMatch = judgeText.match(/RATIONALE:\s*([\s\S]*?)(?:\n\n|$)/i);
+    const rawLabel = labelMatch?.[1]?.toLowerCase();
+    const label = rawLabel === 'allow' || rawLabel === 'block' || rawLabel === 'undecided'
+        ? rawLabel
+        : 'undecided';
+    let confidence = 0;
+    if (confMatch?.[1]) {
+        const n = Number(confMatch[1]);
+        if (Number.isFinite(n)) {
+            confidence = Math.max(0, Math.min(1, n));
+        }
+    }
+    if (label === 'undecided' && !labelMatch) {
+        // unparseable — keep confidence at 0 regardless of what we found
+        confidence = 0;
+    }
+    const rationale = ratMatch?.[1]?.trim() || (labelMatch ? '' : 'unparseable judge output');
+    return { label, confidence, rationale };
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Run the debate end-to-end and return a Verdict.
+ * Order is fixed: allow → block → allow → block → judge.
+ */
+export async function runDebate(input, opts) {
+    const maxRounds = opts.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    if (maxRounds < 2) {
+        throw new Error(`runDebate: maxRounds must be >= 2 (got ${maxRounds})`);
+    }
+    const rounds = [];
+    // Round 1 — allow opens
+    const r1Prompt = formatPrompt(input, 'allow-advocate', rounds);
+    const r1 = await opts.client.respond(r1Prompt, 'allow-advocate');
+    rounds.push({ role: 'allow-advocate', argument: r1, ts: nowIso() });
+    // Round 2 — block rebuts
+    const r2Prompt = formatPrompt(input, 'block-advocate', rounds);
+    const r2 = await opts.client.respond(r2Prompt, 'block-advocate');
+    rounds.push({ role: 'block-advocate', argument: r2, ts: nowIso() });
+    // Round 3 — allow counter-rebuts
+    if (maxRounds >= 3) {
+        const r3Prompt = formatPrompt(input, 'allow-advocate', rounds);
+        const r3 = await opts.client.respond(r3Prompt, 'allow-advocate');
+        rounds.push({ role: 'allow-advocate', argument: r3, ts: nowIso() });
+    }
+    // Round 4 — block final
+    if (maxRounds >= 4) {
+        const r4Prompt = formatPrompt(input, 'block-advocate', rounds);
+        const r4 = await opts.client.respond(r4Prompt, 'block-advocate');
+        rounds.push({ role: 'block-advocate', argument: r4, ts: nowIso() });
+    }
+    // Judge — synthesizes
+    const judgePrompt = formatPrompt(input, 'judge', rounds);
+    const judgeText = await opts.client.respond(judgePrompt, 'judge');
+    const parsed = parseVerdict(judgeText);
+    return {
+        label: parsed.label,
+        confidence: parsed.confidence,
+        rationale: parsed.rationale,
+        rounds,
+    };
+}
+//# sourceMappingURL=runner.js.map

package/dist/futures/debate/synthesis.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Synthesis — fan a list of debate inputs through the runner and
+ * persist the verdicts as JSONL training data for the critic.
+ */
+import type { DebateInput, DebateOpts, TrainingExample } from './types.js';
+/**
+ * Default JSONL path: ~/.kbot/futures/debate/<YYYY-MM-DD>.jsonl
+ */
+export declare function defaultJsonlPath(date?: Date): string;
+/**
+ * Run a debate per input and return the resulting training examples.
+ * Failures are surfaced — the caller decides whether to retry or skip.
+ */
+export declare function synthesizeTrainingData(inputs: DebateInput[], opts: DebateOpts): Promise<TrainingExample[]>;
+/**
+ * Atomic JSONL write. Creates parent dirs, writes to a tmp file,
+ * then renames into place to avoid partial-write corruption.
+ */
+export declare function writeJsonl(examples: TrainingExample[], filePath: string): void;
+/**
+ * Read JSONL and parse line-by-line. Malformed lines are skipped
+ * (callers can audit by counting input vs output).
+ */
+export declare function loadJsonl(filePath: string): TrainingExample[];
+//# sourceMappingURL=synthesis.d.ts.map

package/dist/futures/debate/synthesis.js

@@ -0,0 +1,81 @@
+/**
+ * Synthesis — fan a list of debate inputs through the runner and
+ * persist the verdicts as JSONL training data for the critic.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { runDebate } from './runner.js';
+/**
+ * Default JSONL path: ~/.kbot/futures/debate/<YYYY-MM-DD>.jsonl
+ */
+export function defaultJsonlPath(date = new Date()) {
+    const yyyy = date.getUTCFullYear();
+    const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(date.getUTCDate()).padStart(2, '0');
+    return path.join(os.homedir(), '.kbot', 'futures', 'debate', `${yyyy}-${mm}-${dd}.jsonl`);
+}
+/**
+ * Run a debate per input and return the resulting training examples.
+ * Failures are surfaced — the caller decides whether to retry or skip.
+ */
+export async function synthesizeTrainingData(inputs, opts) {
+    const examples = [];
+    for (const input of inputs) {
+        const verdict = await runDebate(input, opts);
+        examples.push({
+            input,
+            label: verdict.label,
+            confidence: verdict.confidence,
+            rationale: verdict.rationale,
+            rounds: verdict.rounds,
+        });
+    }
+    return examples;
+}
+/**
+ * Atomic JSONL write. Creates parent dirs, writes to a tmp file,
+ * then renames into place to avoid partial-write corruption.
+ */
+export function writeJsonl(examples, filePath) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const body = examples.map((ex) => JSON.stringify(ex)).join('\n') + (examples.length ? '\n' : '');
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, body, 'utf8');
+    fs.renameSync(tmp, filePath);
+}
+/**
+ * Read JSONL and parse line-by-line. Malformed lines are skipped
+ * (callers can audit by counting input vs output).
+ */
+export function loadJsonl(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            // minimal shape check — skip if required fields are missing
+            if (obj &&
+                typeof obj === 'object' &&
+                obj.input &&
+                typeof obj.input.candidate === 'string' &&
+                Array.isArray(obj.rounds) &&
+                typeof obj.label === 'string' &&
+                typeof obj.confidence === 'number' &&
+                typeof obj.rationale === 'string') {
+                out.push(obj);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=synthesis.js.map

package/dist/futures/debate/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Asymmetric debate types — BARRED-style guardrail synthesis.
+ *
+ * Two LLMs argue opposite sides of a candidate input
+ * ("safe to allow" vs "must block"); a third LLM judges.
+ * Output is JSONL training data for the critic.
+ *
+ * Source: "BARRED: Custom Policy Guardrails via Asymmetric Debate"
+ * (Plurai, arXiv 2604.25203). See V5_FUTURES_PLAN.md.
+ */
+/**
+ * The thing under debate. `candidate` is the input being evaluated;
+ * `context` is optional surrounding context (system state, prior turns);
+ * `categoryHint` lets the caller tag the example for downstream filtering.
+ */
+export interface DebateInput {
+    candidate: string;
+    context?: string;
+    categoryHint?: string;
+}
+/**
+ * Three asymmetric roles: two advocates (one for allow, one for block),
+ * and a single judge that synthesizes the verdict.
+ */
+export type AsymmetricRoles = 'allow-advocate' | 'block-advocate' | 'judge';
+/**
+ * One round of the debate. Multiple rounds form the transcript.
+ */
+export interface DebateRound {
+    role: AsymmetricRoles;
+    argument: string;
+    ts: string;
+}
+/**
+ * Final verdict from the judge, plus the full transcript that produced it.
+ * `confidence` is in [0, 1]; `undecided` is used when the judge output
+ * is unparseable or the judge explicitly declines.
+ */
+export interface Verdict {
+    label: 'allow' | 'block' | 'undecided';
+    confidence: number;
+    rationale: string;
+    rounds: DebateRound[];
+}
+/**
+ * Injectable LLM client. The runner only ever calls `respond`;
+ * tests pass a deterministic stub. Production wiring lives elsewhere
+ * so this module never imports a provider SDK.
+ */
+export interface LLMClient {
+    respond(prompt: string, role: AsymmetricRoles): Promise<string>;
+}
+/**
+ * Runner options. `maxRounds` defaults to 4 (allow→block→allow→block);
+ * `seed` is forwarded to the client for callers that support it.
+ */
+export interface DebateOpts {
+    maxRounds?: number;
+    client: LLMClient;
+    seed?: number;
+}
+/**
+ * Persisted training example. One per debate run.
+ */
+export interface TrainingExample {
+    input: DebateInput;
+    label: Verdict['label'];
+    confidence: number;
+    rationale: string;
+    rounds: DebateRound[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/futures/debate/types.js

@@ -0,0 +1,12 @@
+/**
+ * Asymmetric debate types — BARRED-style guardrail synthesis.
+ *
+ * Two LLMs argue opposite sides of a candidate input
+ * ("safe to allow" vs "must block"); a third LLM judges.
+ * Output is JSONL training data for the critic.
+ *
+ * Source: "BARRED: Custom Policy Guardrails via Asymmetric Debate"
+ * (Plurai, arXiv 2604.25203). See V5_FUTURES_PLAN.md.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/futures/forecast/index.d.ts

@@ -0,0 +1,5 @@
+export type { Signal, Trend, Horizon, Forecast } from './types.js';
+export { HORIZON_MS } from './types.js';
+export { linearProjection, exponentialProjection, flatProjection, bestProjection, clampHorizon, signalHistory, } from './projection.js';
+export { synthesizeForecasts, formatForecast, narrative } from './synthesize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/futures/forecast/index.js

@@ -0,0 +1,5 @@
+// futures/forecast — public surface.
+export { HORIZON_MS } from './types.js';
+export { linearProjection, exponentialProjection, flatProjection, bestProjection, clampHorizon, signalHistory, } from './projection.js';
+export { synthesizeForecasts, formatForecast, narrative } from './synthesize.js';
+//# sourceMappingURL=index.js.map

package/dist/futures/forecast/projection.d.ts

@@ -0,0 +1,31 @@
+import { type Forecast, type Horizon, type Signal } from './types.js';
+/**
+ * Linear projection: value ~ a + b*t. Bounds = point ± 2 * residual stddev.
+ * Falls back to flat for fewer than 2 distinct timestamps.
+ */
+export declare function linearProjection(signal: Signal, horizon: Horizon): Forecast;
+/**
+ * Exponential projection: log-transform, fit linear, exp back.
+ * Drops non-positive values (log undefined). Falls back to flat if too few
+ * positive points remain.
+ */
+export declare function exponentialProjection(signal: Signal, horizon: Horizon): Forecast;
+/** Public flat projection (callers may prefer to force this). */
+export declare function flatProjection(signal: Signal, horizon: Horizon): Forecast;
+/**
+ * Pick the model with the best r². If both linear and exponential fit
+ * poorly (r² < 0.4 in both), return flat — low-variance signals shouldn't
+ * generate over-confident projections.
+ */
+export declare function bestProjection(signal: Signal, horizon: Horizon): Forecast;
+/**
+ * Guard against projecting absurdly far past available history.
+ * Returns true if the horizon is acceptable given the timespan covered.
+ * Rule: horizon must not exceed history span * 3.
+ *
+ * `history` is the timespan in ms from earliest to latest observation.
+ */
+export declare function clampHorizon(h: Horizon, history: number): boolean;
+/** Helper for tests/synthesize: compute the timespan of a Signal in ms. */
+export declare function signalHistory(signal: Signal): number;
+//# sourceMappingURL=projection.d.ts.map