@kernel.chat/kbot 4.0.1 → 4.1.0

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

package/dist/futures/forecast/projection.js

@@ -0,0 +1,177 @@
+// futures/forecast/projection — project Signal arrays forward in time.
+// Pure functions, no IO. Three model families (linear, exponential, flat)
+// + a `bestProjection` selector that picks the highest r² with bias toward
+// flat when neither model fits well.
+import { HORIZON_MS } from './types.js';
+/**
+ * Least-squares fit of y = a + b*x. Returns intercept, slope, r², and
+ * residual stddev (sqrt of mean squared residual). Assumes points.length >= 2.
+ */
+function leastSquares(xs, ys) {
+    const n = xs.length;
+    let sumX = 0;
+    let sumY = 0;
+    for (let i = 0; i < n; i++) {
+        sumX += xs[i];
+        sumY += ys[i];
+    }
+    const meanX = sumX / n;
+    const meanY = sumY / n;
+    let num = 0;
+    let den = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - meanX;
+        num += dx * (ys[i] - meanY);
+        den += dx * dx;
+    }
+    const slope = den === 0 ? 0 : num / den;
+    const intercept = meanY - slope * meanX;
+    // r²: 1 - SS_res / SS_tot
+    let ssRes = 0;
+    let ssTot = 0;
+    for (let i = 0; i < n; i++) {
+        const yhat = intercept + slope * xs[i];
+        const resid = ys[i] - yhat;
+        ssRes += resid * resid;
+        ssTot += (ys[i] - meanY) ** 2;
+    }
+    const r2 = ssTot === 0 ? (ssRes === 0 ? 1 : 0) : 1 - ssRes / ssTot;
+    const residualStd = Math.sqrt(ssRes / Math.max(1, n - 1));
+    return { intercept, slope, r2, residualStd };
+}
+/** Sort signal values ascending by timestamp; drops empty signals safely. */
+function sortedValues(signal) {
+    return [...signal.values].sort((a, b) => a.ts - b.ts);
+}
+/** Map r² + sample size to a 0..1 confidence score. */
+function confidenceFrom(r2, n) {
+    if (n < 2)
+        return 0;
+    // Linearly bonus more samples up to 12; r² floor at 0 (negatives clamp).
+    const sizeFactor = Math.min(1, n / 12);
+    const r2Clamped = Math.max(0, Math.min(1, r2));
+    return Math.max(0, Math.min(1, r2Clamped * 0.7 + sizeFactor * 0.3));
+}
+function flatForecast(signal, horizon, method = 'flat-mean') {
+    const pts = sortedValues(signal);
+    const mean = pts.length === 0 ? 0 : pts.reduce((s, p) => s + p.value, 0) / pts.length;
+    let std = 0;
+    if (pts.length > 1) {
+        const sq = pts.reduce((s, p) => s + (p.value - mean) ** 2, 0);
+        std = Math.sqrt(sq / (pts.length - 1));
+    }
+    const trend = { kind: 'flat', slope: 0, r2: 0 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: mean,
+        lowerBound: mean - 2 * std,
+        upperBound: mean + 2 * std,
+        confidence: pts.length >= 3 ? 0.4 : 0.1,
+        method,
+    };
+}
+/**
+ * Linear projection: value ~ a + b*t. Bounds = point ± 2 * residual stddev.
+ * Falls back to flat for fewer than 2 distinct timestamps.
+ */
+export function linearProjection(signal, horizon) {
+    const pts = sortedValues(signal);
+    if (pts.length < 2)
+        return flatForecast(signal, horizon, 'flat-too-few');
+    const xs = pts.map((p) => p.ts);
+    const ys = pts.map((p) => p.value);
+    const fit = leastSquares(xs, ys);
+    const lastTs = xs[xs.length - 1];
+    const targetTs = lastTs + HORIZON_MS[horizon];
+    const point = fit.intercept + fit.slope * targetTs;
+    const trend = { kind: 'linear', slope: fit.slope, r2: fit.r2 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: point,
+        lowerBound: point - 2 * fit.residualStd,
+        upperBound: point + 2 * fit.residualStd,
+        confidence: confidenceFrom(fit.r2, pts.length),
+        method: 'linear-lsq',
+    };
+}
+/**
+ * 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 function exponentialProjection(signal, horizon) {
+    const pts = sortedValues(signal).filter((p) => p.value > 0);
+    if (pts.length < 2)
+        return flatForecast(signal, horizon, 'flat-nonpositive');
+    const xs = pts.map((p) => p.ts);
+    const ys = pts.map((p) => Math.log(p.value));
+    const fit = leastSquares(xs, ys);
+    const lastTs = xs[xs.length - 1];
+    const targetTs = lastTs + HORIZON_MS[horizon];
+    const logPoint = fit.intercept + fit.slope * targetTs;
+    const point = Math.exp(logPoint);
+    // Bounds in log space, then exp back (asymmetric in raw space — correct).
+    const lower = Math.exp(logPoint - 2 * fit.residualStd);
+    const upper = Math.exp(logPoint + 2 * fit.residualStd);
+    const trend = { kind: 'exponential', slope: fit.slope, r2: fit.r2 };
+    return {
+        signal: signal.name,
+        horizon,
+        trend,
+        pointEstimate: point,
+        lowerBound: lower,
+        upperBound: upper,
+        confidence: confidenceFrom(fit.r2, pts.length),
+        method: 'exp-loglin',
+    };
+}
+/** Public flat projection (callers may prefer to force this). */
+export function flatProjection(signal, horizon) {
+    return flatForecast(signal, horizon);
+}
+/**
+ * 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 function bestProjection(signal, horizon) {
+    const pts = sortedValues(signal);
+    if (pts.length < 2)
+        return flatProjection(signal, horizon);
+    const lin = linearProjection(signal, horizon);
+    // Exponential only meaningful when all values positive.
+    const allPositive = pts.every((p) => p.value > 0);
+    const exp = allPositive ? exponentialProjection(signal, horizon) : null;
+    const linR2 = lin.trend.r2;
+    const expR2 = exp ? exp.trend.r2 : -Infinity;
+    if (linR2 < 0.4 && expR2 < 0.4) {
+        return flatProjection(signal, horizon);
+    }
+    if (exp && expR2 > linR2)
+        return exp;
+    return lin;
+}
+/**
+ * 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 function clampHorizon(h, history) {
+    if (history <= 0)
+        return false;
+    return HORIZON_MS[h] <= history * 3;
+}
+/** Helper for tests/synthesize: compute the timespan of a Signal in ms. */
+export function signalHistory(signal) {
+    if (signal.values.length < 2)
+        return 0;
+    const sorted = sortedValues(signal);
+    return sorted[sorted.length - 1].ts - sorted[0].ts;
+}
+//# sourceMappingURL=projection.js.map

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

@@ -0,0 +1,19 @@
+import type { Forecast, Horizon, Signal } from './types.js';
+/**
+ * Project every signal forward at the given horizon. Skips signals whose
+ * history is too short for the horizon (clampHorizon = false). Returns
+ * forecasts sorted by absolute slope descending so the most-moving signals
+ * surface first.
+ */
+export declare function synthesizeForecasts(signals: Signal[], horizon: Horizon): Forecast[];
+/**
+ * Markdown one-liner for a forecast.
+ * Example: `📈 npm downloads → 14.2k (in 30 days, linear, r²=0.78, ±890)`
+ */
+export declare function formatForecast(f: Forecast): string;
+/**
+ * Take a list of forecasts and produce a short paragraph naming the top-3
+ * by absolute slope. If empty, returns a polite no-data sentence.
+ */
+export declare function narrative(forecasts: Forecast[]): string;
+//# sourceMappingURL=synthesize.d.ts.map