canli-validation-mcp 0.10.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/lab.mjs ADDED
@@ -0,0 +1,308 @@
1
+ // mcp/src/lab.mjs
2
+ //
3
+ // The lab: four tools that compute in this process, on stdio and on the hosted endpoint alike,
4
+ // from src/local (mirrored byte for byte from the canlicapital repository by
5
+ // scripts/sync-local.mjs). Nothing is sent to an API and no receipt is stored; files are read only
6
+ // by the server on the user's own machine, and only their numbers (and ISO dates) are used.
7
+ //
8
+ // backtest_strategy a rule-based strategy over every parameter set in a grid, validated with
9
+ // the number of variants actually run
10
+ // summarize_series a long series in about a hundred words an agent can reason over
11
+ // stress_test resampled histories and named scenarios, with a fragility share
12
+ // check_feasibility broker limits, day-trading rules, market impact, crowding and capacity
13
+ //
14
+ // Also here: the code-generation resources (every tool's exact JSON Schemas, the strategy spec,
15
+ // runnable client examples, the API's OpenAPI document) and the lab's guided prompts.
16
+ import { createHash } from "node:crypto";
17
+ import { ResourceTemplate } from "@modelcontextprotocol/server";
18
+ import { z } from "zod";
19
+ import { BACKTEST_LIMITS, BACKTEST_LIMITS_TEXT, FAMILIES, runBacktest } from "./local/js/backtest-core.js";
20
+ import { FEASIBILITY_LIMITS_TEXT, checkFeasibility } from "./local/js/feasibility-core.js";
21
+ import { SUMMARY_LIMITS_TEXT, summarizeSeries } from "./local/js/series-summary-core.js";
22
+ import { STRESS_LIMITS_TEXT, stressTest } from "./local/js/stress-core.js";
23
+ import { LAB_TOOL_DESCRIPTIONS, backtestInput, backtestOutput, feasibilityInput, feasibilityOutput, stressInput, stressOutput, summarizeInput, summaryOutput } from "./lab-schemas.mjs";
24
+ import { readSeriesWithDates } from "./series-file.mjs";
25
+
26
+ export const LAB_TOOLS = Object.freeze(["backtest_strategy", "summarize_series", "stress_test", "check_feasibility"]);
27
+
28
+ // Same shape as every other tool's result: the object as text, and as structured content.
29
+ const labText = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
30
+
31
+ function parse(schema, args, tool) {
32
+ const result = schema.safeParse(args ?? {});
33
+ if (result.success) return result.data;
34
+ throw new Error(`${tool}: ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
35
+ }
36
+
37
+ // The series a tool works on: inline, or from a file on this machine. Exactly one of the two.
38
+ function readInput(session, tool, { inline, file, column, inlineName, fileName }) {
39
+ if ((inline === undefined) === (file === undefined)) throw new Error(`${tool}: send exactly one of ${inlineName} or ${fileName}`);
40
+ if (file === undefined) return { values: inline, dates: undefined, source: {} };
41
+ if (session.hosted) throw new Error(`${tool}: the hosted endpoint cannot read files on your machine; send ${inlineName} as numbers, or run the server locally with npx -y canli-validation-mcp.`);
42
+ const read = readSeriesWithDates(file, column);
43
+ return {
44
+ values: read.values,
45
+ dates: read.dates ?? undefined,
46
+ source: { [fileName]: file, column_position: read.column, ...(read.date_column ? { date_column_position: read.date_column } : {}), ...(read.skipped.length ? { skipped_row_counter_columns: read.skipped } : {}) },
47
+ };
48
+ }
49
+
50
+ // The digest of exactly the numbers a result was computed from, so a result can be tied to its input.
51
+ const digest = (values) => createHash("sha256").update(JSON.stringify(values)).digest("hex");
52
+
53
+ // Labels are echoed into results, so each is cut to a date-and-time length; a label is never a
54
+ // channel for long text.
55
+ const labels = (values) => values?.map((value) => String(value).slice(0, 40));
56
+
57
+ export async function toolBacktestStrategy(session, args) {
58
+ const input = parse(backtestInput, args, "backtest_strategy");
59
+ const { values, dates, source } = readInput(session, "backtest_strategy", { inline: input.prices, file: input.prices_file, column: input.prices_column, inlineName: "prices", fileName: "prices_file" });
60
+ const result = runBacktest({ prices: values, family: input.family, grid: input.grid ?? {}, periods_per_year: input.periods_per_year ?? 252, cost_bps: input.cost_bps ?? 5, allow_short: input.allow_short ?? false, dates: labels(input.dates) ?? dates });
61
+ return labText({ ...result, limits: BACKTEST_LIMITS_TEXT, source: { ...source, prices: values.length, input_sha256: digest(values), computed: "locally, in the MCP server process; no receipt" } });
62
+ }
63
+
64
+ export async function toolSummarizeSeries(session, args) {
65
+ const input = parse(summarizeInput, args, "summarize_series");
66
+ const inline = input.prices ?? input.returns;
67
+ if (input.prices !== undefined && input.returns !== undefined) throw new Error("summarize_series: send prices or returns, not both");
68
+ const { values, dates, source } = readInput(session, "summarize_series", { inline, file: input.series_file, column: input.series_column, inlineName: "prices (or returns)", fileName: "series_file" });
69
+ const kind = input.series_file !== undefined ? (input.series_kind ?? "prices") : input.prices !== undefined ? "prices" : "returns";
70
+ const result = summarizeSeries({ [kind]: values, dates: labels(input.dates) ?? dates, periods_per_year: input.periods_per_year ?? 252, benchmark_returns: input.benchmark_returns, name: input.name?.slice(0, 80) });
71
+ return labText({ ...result, limits: SUMMARY_LIMITS_TEXT, source: { ...source, kind, values: values.length, input_sha256: digest(values) } });
72
+ }
73
+
74
+ export async function toolStressTest(session, args) {
75
+ const input = parse(stressInput, args, "stress_test");
76
+ const { values, source } = readInput(session, "stress_test", { inline: input.returns, file: input.returns_file, column: input.returns_column, inlineName: "returns", fileName: "returns_file" });
77
+ const result = stressTest({ ...input, returns: values });
78
+ return labText({ ...result, limits: STRESS_LIMITS_TEXT, source: { ...source, returns: values.length, input_sha256: digest(values) } });
79
+ }
80
+
81
+ export async function toolCheckFeasibility(session, args) {
82
+ const input = parse(feasibilityInput, args, "check_feasibility");
83
+ return labText({ ...checkFeasibility(input), limits: FEASIBILITY_LIMITS_TEXT });
84
+ }
85
+
86
+ // The lab computes locally and changes nothing anywhere: read-only, closed world, idempotent.
87
+ const LAB_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
88
+
89
+ export function labToolSpecs(session) {
90
+ const spec = (name, title, input, output, handler) => [name, { title, annotations: { title, ...LAB_ANNOTATIONS }, description: LAB_TOOL_DESCRIPTIONS[name], inputSchema: input, outputSchema: output }, (args) => handler(session, args)];
91
+ return [
92
+ spec("backtest_strategy", "Backtest a rule over a parameter grid, validated", backtestInput, backtestOutput, toolBacktestStrategy),
93
+ spec("summarize_series", "Summarize a price or return series", summarizeInput, summaryOutput, toolSummarizeSeries),
94
+ spec("stress_test", "Stress-test a strategy's returns", stressInput, stressOutput, toolStressTest),
95
+ spec("check_feasibility", "Check a plan against broker limits and impact", feasibilityInput, feasibilityOutput, toolCheckFeasibility),
96
+ ];
97
+ }
98
+
99
+ // ---------------------------------------------------------------------------------------------
100
+ // Code-generation resources. An agent writing code against these tools reads the exact schemas
101
+ // and a working call instead of guessing argument names.
102
+ // ---------------------------------------------------------------------------------------------
103
+
104
+ // One small, valid call per tool: the arguments every generated example sends.
105
+ export const EXAMPLE_ARGS = Object.freeze({
106
+ get_key: {},
107
+ validate_deflated_sharpe: { observed_sharpe_annualized: 1.5, observations: 730, periods_per_year: 365, skew: -0.5, non_excess_kurtosis: 5, effective_independent_trials: 229, cross_trial_sharpe_sd_annualized: 0.57 },
108
+ validate_overfitting: { matrix_note: "every variant's returns, one row per period, one column per variant", matrix: [[0.01, 0.012], [-0.004, -0.002], [0.006, 0.001], [0.002, 0.004], [-0.01, -0.008], [0.007, 0.009], [0.003, -0.001], [0.0, 0.002], [0.005, 0.004], [-0.003, -0.005], [0.008, 0.006], [0.001, 0.003], [-0.002, 0.0], [0.004, 0.002], [0.006, 0.007], [-0.006, -0.004]] },
109
+ validate_reality_check: { matrix_file: "variants.csv" },
110
+ validate_paper_evidence: { record_file: "paper_record.json" },
111
+ validate_breadth: { sleeve_sharpe: 0.8, average_pairwise_correlation: 0.2, sleeves: 10 },
112
+ validate_track_record: { observed_sharpe_annualized: 1.2, periods_per_year: 252, skew: -0.3, non_excess_kurtosis: 4 },
113
+ validate_backtest_length: { target_sharpe_annualized: 1, effective_independent_trials: 50 },
114
+ validate_haircut_sharpe: { observed_sharpe_annualized: 1.5, periods_per_year: 252, observations: 1260, tests: 50 },
115
+ validate_luck_trials: { observed_sharpe_annualized: 1.5, periods_per_year: 252, observations: 1260 },
116
+ audit_backtest: { returns_file: "backtest_returns.csv", periods_per_year: 252, effective_independent_trials: 20, cross_trial_sharpe_sd_annualized: 0.5 },
117
+ verify_receipt: { id: "0123456789abcdef01234567" },
118
+ service_status: {},
119
+ company_financial_history: { ticker: "AAPL", concept: "Assets", limit: 8 },
120
+ backtest_strategy: { family: "sma_cross", grid: { fast: [10, 20, 50], slow: [100, 200] }, prices_file: "prices.csv", cost_bps: 5 },
121
+ summarize_series: { series_file: "prices.csv", series_kind: "prices", name: "My asset" },
122
+ stress_test: { returns_file: "strategy_returns.csv", drawdown_limit: 0.2, paths: 1000, seed: 42 },
123
+ check_feasibility: { broker: "alpaca", asset_class: "us_equity", account: "margin", capital_usd: 250000, orders_per_rebalance: 40, rebalances_per_year: 52, turnover_per_year: 8, adv_usd: 20000000, daily_volatility: 0.02, copies: 1, expected_gross_return: 0.12, spread_and_fees_bps: 3 },
124
+ });
125
+
126
+ const usesFile = (args) => Object.keys(args).some((k) => k.endsWith("_file"));
127
+ const cleanArgs = (args) => Object.fromEntries(Object.entries(args).filter(([k]) => !k.endsWith("_note")));
128
+
129
+ export function exampleCode(language, tool) {
130
+ const args = cleanArgs(EXAMPLE_ARGS[tool] ?? {});
131
+ const json = JSON.stringify(args, null, 2);
132
+ const fileNote = usesFile(args) ? "Point the *_file argument at your own CSV; the local server reads it, the hosted endpoint cannot." : "";
133
+ if (language === "python") {
134
+ return [
135
+ "# pip install mcp",
136
+ "# Runs the server on this machine (Node.js 20.10+). CANLI_LOCAL=1 computes everything locally, no key.",
137
+ fileNote ? `# ${fileNote}` : null,
138
+ "import asyncio",
139
+ "from mcp import ClientSession, StdioServerParameters",
140
+ "from mcp.client.stdio import stdio_client",
141
+ "",
142
+ 'SERVER = StdioServerParameters(command="npx", args=["-y", "canli-validation-mcp"], env={"CANLI_LOCAL": "1"})',
143
+ "",
144
+ "async def main():",
145
+ " async with stdio_client(SERVER) as (read, write):",
146
+ " async with ClientSession(read, write) as session:",
147
+ " await session.initialize()",
148
+ ` result = await session.call_tool("${tool}", ${json.replace(/\n/g, "\n ").replace(/\btrue\b/g, "True").replace(/\bfalse\b/g, "False").replace(/\bnull\b/g, "None")})`,
149
+ " print(result.structuredContent)",
150
+ "",
151
+ "asyncio.run(main())",
152
+ "",
153
+ ].filter((line) => line !== null).join("\n");
154
+ }
155
+ if (language === "javascript") {
156
+ return [
157
+ "// npm install @modelcontextprotocol/sdk",
158
+ "// Runs the server on this machine (Node.js 20.10+). CANLI_LOCAL=1 computes everything locally, no key.",
159
+ fileNote ? `// ${fileNote}` : null,
160
+ 'import { Client } from "@modelcontextprotocol/sdk/client/index.js";',
161
+ 'import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";',
162
+ "",
163
+ 'const client = new Client({ name: "example", version: "1.0.0" });',
164
+ 'await client.connect(new StdioClientTransport({ command: "npx", args: ["-y", "canli-validation-mcp"], env: { ...process.env, CANLI_LOCAL: "1" } }));',
165
+ `const result = await client.callTool({ name: "${tool}", arguments: ${json} });`,
166
+ "console.log(result.structuredContent);",
167
+ "await client.close();",
168
+ "",
169
+ ].filter((line) => line !== null).join("\n");
170
+ }
171
+ if (language === "curl") {
172
+ if (usesFile(args)) {
173
+ return `# ${tool} reads a file on your machine, which the hosted endpoint cannot do.\n# Use the python or javascript example, or send the numbers inline (see canli://schemas/${tool}).\n`;
174
+ }
175
+ const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } });
176
+ return [
177
+ "# The hosted endpoint: no install, no key needed for a first call. Tools added since the last",
178
+ "# release appear here once that release is pinned; locally they are available at once.",
179
+ "curl -sS https://canlicapital.com/mcp \\",
180
+ " -H 'content-type: application/json' \\",
181
+ " -H 'accept: application/json, text/event-stream' \\",
182
+ ` -d '${body.replace(/'/g, "'\\''")}'`,
183
+ "",
184
+ ].join("\n");
185
+ }
186
+ throw new Error(`No example language ${language}; choose python, javascript or curl`);
187
+ }
188
+
189
+ export const EXAMPLE_LANGUAGES = Object.freeze(["python", "javascript", "curl"]);
190
+
191
+ // Every strategy family as a machine-readable spec: its parameters, their bounds and its rule.
192
+ export function strategySpec() {
193
+ const param = { type: "array", items: { type: "number" }, minItems: 1, maxItems: 60 };
194
+ return {
195
+ $schema: "https://json-schema.org/draft/2020-12/schema",
196
+ title: "backtest_strategy family and grid",
197
+ description: "Pick a family and give each of its parameters a list of values; every valid combination is run (at most 200), positions are decided at each close from prices up to that close, and trade the next period's return.",
198
+ oneOf: Object.entries(FAMILIES).map(([family, spec]) => ({
199
+ title: family,
200
+ description: spec.describe,
201
+ type: "object",
202
+ required: ["family", ...(spec.params.length ? ["grid"] : [])],
203
+ properties: {
204
+ family: { const: family },
205
+ ...(spec.params.length ? { grid: { type: "object", additionalProperties: false, required: spec.params.filter((p) => p !== "skip"), properties: Object.fromEntries(spec.params.map((p) => [p, param])) } } : {}),
206
+ },
207
+ })),
208
+ limits: { max_prices: BACKTEST_LIMITS.max_prices, max_variants: BACKTEST_LIMITS.max_variants, max_parameter_value: BACKTEST_LIMITS.max_parameter_value },
209
+ };
210
+ }
211
+
212
+ // catalog: { toolName: { description, inputSchema, outputSchema } } for every tool the server can list.
213
+ export function registerCodeResources(server, session, catalog) {
214
+ const names = Object.keys(catalog).sort();
215
+ const complete = (list) => (value) => list.filter((n) => n.startsWith(value ?? ""));
216
+ server.registerResource(
217
+ "tool-schema",
218
+ new ResourceTemplate("canli://schemas/{tool}", { list: undefined, complete: { tool: complete(names) } }),
219
+ { title: "A tool's exact JSON Schemas", description: "Input and output JSON Schema and the description of one tool, for writing code against it.", mimeType: "application/json" },
220
+ (uri, { tool }) => {
221
+ const entry = catalog[tool];
222
+ if (!entry) throw new Error(`No tool ${tool}; tools are ${names.join(", ")}`);
223
+ const body = { tool, description: entry.description, input_schema: z.toJSONSchema(entry.inputSchema, { io: "input" }), output_schema: z.toJSONSchema(entry.outputSchema, { io: "output" }) };
224
+ return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(body, null, 2) }] };
225
+ },
226
+ );
227
+ server.registerResource(
228
+ "example",
229
+ new ResourceTemplate("canli://examples/{language}/{tool}", { list: undefined, complete: { language: complete([...EXAMPLE_LANGUAGES]), tool: complete(names) } }),
230
+ { title: "A working call, in Python, JavaScript or curl", description: "Runnable client code calling one tool with valid example arguments.", mimeType: "text/plain" },
231
+ (uri, { language, tool }) => {
232
+ if (!catalog[tool]) throw new Error(`No tool ${tool}; tools are ${names.join(", ")}`);
233
+ return { contents: [{ uri: uri.href, mimeType: "text/plain", text: exampleCode(language, tool) }] };
234
+ },
235
+ );
236
+ server.registerResource(
237
+ "strategy-spec",
238
+ "canli://strategy-spec",
239
+ { title: "Strategy families and their parameters", description: "JSON Schema of backtest_strategy's families, parameters and rules.", mimeType: "application/json" },
240
+ (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(strategySpec(), null, 2) }] }),
241
+ );
242
+ server.registerResource(
243
+ "openapi",
244
+ "canli://openapi",
245
+ { title: "The validation API's OpenAPI 3.1 document", description: "Generated from the endpoints that exist; fetched from canlicapital.com when read.", mimeType: "application/json" },
246
+ async (uri) => {
247
+ const signal = AbortSignal.timeout(session.timeoutMs);
248
+ let res;
249
+ try {
250
+ res = await session.fetchImpl(`${session.base}/api/v1/openapi`, { headers: { Accept: "application/json" }, signal, redirect: "error" });
251
+ } catch {
252
+ throw new Error(`canli://openapi: could not reach ${session.base}/api/v1/openapi; it is also published at https://canlicapital.com/api/v1/openapi`);
253
+ }
254
+ if (!res.ok) throw new Error(`canli://openapi: ${session.base}/api/v1/openapi returned HTTP ${res.status}`);
255
+ return { contents: [{ uri: uri.href, mimeType: "application/json", text: await res.text() }] };
256
+ },
257
+ );
258
+ }
259
+
260
+ // Guided workflows for the lab. The prompt only writes the instructions; the tools do the work.
261
+ export function registerLabPrompts(server) {
262
+ const prompt = (name, title, description, argsSchema, lines) => server.registerPrompt(name, { title, description, argsSchema }, (args) => ({
263
+ messages: [{ role: "user", content: { type: "text", text: lines(args).filter(Boolean).join("\n") } }],
264
+ }));
265
+ prompt(
266
+ "backtest_and_validate",
267
+ "Backtest a rule and check whether the best variant is luck",
268
+ "Run a strategy family over a parameter grid on your prices, then read the deflated Sharpe and overfitting probability that count every variant run.",
269
+ { prices_file: z.string().describe("Path to a CSV of prices on this machine"), family: z.string().optional().describe("sma_cross, momentum, mean_reversion, breakout or buy_and_hold") },
270
+ ({ prices_file, family }) => [
271
+ `Backtest ${family ?? "a sensible rule for this asset"} on the prices in ${prices_file} with backtest_strategy, over a small grid of parameters (read canli://strategy-spec for each family's parameters).`,
272
+ "Report the best variant's Sharpe, drawdown and turnover next to buy and hold, then the deflated Sharpe and the probability of backtest overfitting, which count every variant the call ran.",
273
+ "Say plainly whether the best variant is distinguishable from luck, and quote the limits sentences the result carries.",
274
+ ],
275
+ );
276
+ prompt(
277
+ "stress_my_strategy",
278
+ "How fragile is this strategy?",
279
+ "Resampled histories and named crash, volatility, repeat and outage scenarios for a strategy's returns.",
280
+ { returns_file: z.string().describe("Path to a CSV of the strategy's returns"), drawdown_limit: z.string().optional().describe("The drawdown you could not live with, such as 0.2") },
281
+ ({ returns_file, drawdown_limit }) => [
282
+ `Run stress_test on ${returns_file}${drawdown_limit ? ` with drawdown_limit ${drawdown_limit}` : ""}.`,
283
+ "Explain the fragility share, the 5th-percentile drawdown and which named scenarios break the limit, and what change (lower leverage, a stop, more diversification) would address each.",
284
+ "Say that these are frequencies under stated rules, not forecasts.",
285
+ ],
286
+ );
287
+ prompt(
288
+ "production_check",
289
+ "Will this plan survive a real broker?",
290
+ "Order-rate and minimum-order limits, 2026 day-trading rules, market impact, crowding and capacity for a trading plan.",
291
+ { plan: z.string().describe("Capital, broker, how many orders per rebalance, how often, turnover, and what it trades") },
292
+ ({ plan }) => [
293
+ `Here is the plan: ${plan}.`,
294
+ "Ask me for any of check_feasibility's required inputs you cannot infer (average daily dollar volume and daily volatility of a typical holding), then run it.",
295
+ "List each blocking or warning finding with the change that fixes it, and say when the broker facts were checked.",
296
+ ],
297
+ );
298
+ prompt(
299
+ "summarize_market_series",
300
+ "Read a long series in a hundred words",
301
+ "Summarize a price or return file instead of reading its rows.",
302
+ { series_file: z.string().describe("Path to a CSV of prices or returns"), kind: z.string().optional().describe("prices or returns; default prices") },
303
+ ({ series_file, kind }) => [
304
+ `Call summarize_series on ${series_file} (series_kind ${kind ?? "prices"}) and reason from its text and fields instead of reading the file's rows.`,
305
+ "Point out anything in the data check (stale prices, jumps) that should be fixed before the series is backtested.",
306
+ ],
307
+ );
308
+ }
@@ -0,0 +1,329 @@
1
+ // =============================================================================
2
+ // audit-core.js
3
+ // -----------------------------------------------------------------------------
4
+ // The parts of audit_backtest computed from the caller's own series rather than by a stored
5
+ // validator:
6
+ //
7
+ // returnShape lag-1 autocorrelation, volatility clustering, skew and tails of the
8
+ // returns, and Lo's (2002) autocorrelation-adjusted Sharpe ratio.
9
+ // sharpeInterval a stationary-bootstrap percentile interval for the annualized Sharpe.
10
+ // searchFromVariants what every variant's returns say about the search: how many were tried,
11
+ // how many independent ones that is (Nyholt 2004; Li and Ji 2005), how far
12
+ // their Sharpe ratios spread, and how correlated they are.
13
+ // nullZooFamily which Null Zoo family the shape resembles, by the rules fixed in
14
+ // config/research/null-zoo-v1-prereg.json before the calibration run.
15
+ // neweyWestT,
16
+ // blockBootstrapT the single-series tests the calibration scores (the same arithmetic as
17
+ // scripts/research/null-zoo/v1/validators.mjs; a test keeps them equal).
18
+ // oosDecay what the in-sample best did out of sample across CSCV splits.
19
+ // fixNext at most five concrete next steps, each naming the check that raised it.
20
+ //
21
+ // Nothing here decides whether a strategy is good. Each number is a description of the series and
22
+ // search exactly as sent.
23
+ // =============================================================================
24
+
25
+ import { autocorrelationFactor } from "./haircut-core.js";
26
+ import { perPeriodMoments } from "./moments-core.js";
27
+ import { makeRandom } from "./selection-risk-core.js";
28
+ import { defaultBlock, stationaryIndices } from "./snooping-core.js";
29
+
30
+ const mean = (xs) => { let s = 0; for (let i = 0; i < xs.length; i++) s += xs[i]; return s / xs.length; };
31
+
32
+ function lagOneCorrelation(xs) {
33
+ const m = mean(xs);
34
+ let c = 0, v = 0;
35
+ for (let i = 0; i < xs.length; i++) { const d = xs[i] - m; v += d * d; if (i > 0) c += d * (xs[i - 1] - m); }
36
+ return v > 0 ? c / v : 0;
37
+ }
38
+
39
+ /** The shape of one return series: what the Null Zoo families vary, plus Lo's adjusted Sharpe. */
40
+ export function returnShape(returns, periodsPerYear) {
41
+ const m = perPeriodMoments(returns);
42
+ const ppy = Number(periodsPerYear);
43
+ const xs = returns.map(Number);
44
+ const lag1 = lagOneCorrelation(xs);
45
+ const lag1Squares = lagOneCorrelation(xs.map((x) => x * x));
46
+ // Lo's factor needs rho strictly inside (-1, 1); a sample can sit on the edge only when it is tiny.
47
+ const rho = Math.max(-0.95, Math.min(0.95, lag1));
48
+ const sharpe = m.sharpe_per_period * Math.sqrt(ppy);
49
+ const factor = autocorrelationFactor(rho, ppy);
50
+ return {
51
+ observations: m.observations,
52
+ sharpe_annualized: sharpe,
53
+ skew: m.skew,
54
+ excess_kurtosis: m.non_excess_kurtosis - 3,
55
+ lag1_autocorrelation: lag1,
56
+ lag1_autocorrelation_of_squares: lag1Squares,
57
+ lo_factor: factor,
58
+ lo_adjusted_sharpe_annualized: sharpe * factor,
59
+ };
60
+ }
61
+
62
+ /**
63
+ * Percentile intervals for the annualized Sharpe from a stationary bootstrap (mean block n^(1/3)),
64
+ * and the share of resamples whose Sharpe is at or below zero.
65
+ */
66
+ export function sharpeInterval(returns, { periodsPerYear, reps = 2000, block, seed = 42, levels = [0.9, 0.95] } = {}) {
67
+ const xs = Float64Array.from(returns, Number);
68
+ const n = xs.length;
69
+ const b = block ?? defaultBlock(n);
70
+ const next = makeRandom(seed);
71
+ const idx = new Int32Array(n);
72
+ const root = Math.sqrt(Number(periodsPerYear));
73
+ const draws = new Float64Array(reps);
74
+ let atOrBelowZero = 0;
75
+ for (let r = 0; r < reps; r++) {
76
+ stationaryIndices(n, b, next, idx);
77
+ let s = 0, q = 0;
78
+ for (let i = 0; i < n; i++) { const v = xs[idx[i]]; s += v; q += v * v; }
79
+ const m = s / n;
80
+ const variance = (q - n * m * m) / (n - 1);
81
+ // A resample with no spread has no Sharpe ratio; it counts on the side its mean falls.
82
+ const sharpe = variance > 0 ? (m / Math.sqrt(variance)) * root : m > 0 ? Infinity : m < 0 ? -Infinity : 0;
83
+ draws[r] = sharpe;
84
+ if (sharpe <= 0) atOrBelowZero++;
85
+ }
86
+ draws.sort();
87
+ const at = (q) => {
88
+ const h = (reps - 1) * q;
89
+ const lo = Math.floor(h);
90
+ const hi = Math.min(lo + 1, reps - 1);
91
+ return draws[lo] + (h - lo) * (draws[hi] - draws[lo]);
92
+ };
93
+ return {
94
+ method: "stationary bootstrap, percentile",
95
+ reps, block: b, seed,
96
+ intervals: Object.fromEntries(levels.map((l) => [String(l), [at((1 - l) / 2), at(1 - (1 - l) / 2)]])),
97
+ share_at_or_below_zero: atOrBelowZero / reps,
98
+ };
99
+ }
100
+
101
+ // Eigenvalues of a symmetric matrix (cyclic Jacobi), for the effective number of trials.
102
+ function symmetricEigenvalues(a, k) {
103
+ const m = Float64Array.from(a);
104
+ for (let sweep = 0; sweep < 100; sweep++) {
105
+ let off = 0;
106
+ for (let i = 0; i < k; i++) for (let j = i + 1; j < k; j++) off += m[i * k + j] ** 2;
107
+ if (off < 1e-24) break;
108
+ for (let p = 0; p < k; p++) {
109
+ for (let q = p + 1; q < k; q++) {
110
+ const apq = m[p * k + q];
111
+ if (Math.abs(apq) < 1e-300) continue;
112
+ const theta = (m[q * k + q] - m[p * k + p]) / (2 * apq);
113
+ const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
114
+ const c = 1 / Math.sqrt(t * t + 1);
115
+ const s = t * c;
116
+ for (let r = 0; r < k; r++) {
117
+ const arp = m[r * k + p], arq = m[r * k + q];
118
+ m[r * k + p] = c * arp - s * arq;
119
+ m[r * k + q] = s * arp + c * arq;
120
+ }
121
+ for (let r = 0; r < k; r++) {
122
+ const apr = m[p * k + r], aqr = m[q * k + r];
123
+ m[p * k + r] = c * apr - s * aqr;
124
+ m[q * k + r] = s * apr + c * aqr;
125
+ }
126
+ }
127
+ }
128
+ }
129
+ return Array.from({ length: k }, (_, i) => m[i * k + i]);
130
+ }
131
+
132
+ /**
133
+ * What a search's variants say about it. `matrix[t][j]` is variant j's return in period t (the shape
134
+ * validate_overfitting takes). Constant variants are counted but left out of the correlations.
135
+ */
136
+ export function searchFromVariants(matrix, periodsPerYear) {
137
+ const periods = matrix.length;
138
+ const k = matrix[0].length;
139
+ const root = Math.sqrt(Number(periodsPerYear));
140
+ const means = new Float64Array(k);
141
+ for (let t = 0; t < periods; t++) for (let j = 0; j < k; j++) means[j] += Number(matrix[t][j]);
142
+ for (let j = 0; j < k; j++) means[j] /= periods;
143
+ const sds = new Float64Array(k);
144
+ for (let t = 0; t < periods; t++) for (let j = 0; j < k; j++) sds[j] += (Number(matrix[t][j]) - means[j]) ** 2;
145
+ for (let j = 0; j < k; j++) sds[j] = Math.sqrt(sds[j] / (periods - 1));
146
+ const live = [];
147
+ for (let j = 0; j < k; j++) if (sds[j] > 0) live.push(j);
148
+ const sharpes = live.map((j) => (means[j] / sds[j]) * root);
149
+ const sharpeMean = sharpes.reduce((a, b) => a + b, 0) / sharpes.length;
150
+ const sharpeSd = sharpes.length > 1 ? Math.sqrt(sharpes.reduce((a, b) => a + (b - sharpeMean) ** 2, 0) / (sharpes.length - 1)) : 0;
151
+ const L = live.length;
152
+ const corr = new Float64Array(L * L);
153
+ const pair = [];
154
+ for (let a = 0; a < L; a++) {
155
+ corr[a * L + a] = 1;
156
+ for (let b = a + 1; b < L; b++) {
157
+ const ja = live[a], jb = live[b];
158
+ let c = 0;
159
+ for (let t = 0; t < periods; t++) c += (Number(matrix[t][ja]) - means[ja]) * (Number(matrix[t][jb]) - means[jb]);
160
+ const r = c / ((periods - 1) * sds[ja] * sds[jb]);
161
+ corr[a * L + b] = corr[b * L + a] = r;
162
+ pair.push(r);
163
+ }
164
+ }
165
+ const pairMean = pair.length ? pair.reduce((a, b) => a + b, 0) / pair.length : 0;
166
+ const pairSd = pair.length > 1 ? Math.sqrt(pair.reduce((a, b) => a + (b - pairMean) ** 2, 0) / (pair.length - 1)) : 0;
167
+ let nyholt = L, liJi = L;
168
+ if (L > 1) {
169
+ const lambdas = symmetricEigenvalues(corr, L);
170
+ const lm = lambdas.reduce((a, b) => a + b, 0) / L;
171
+ const lv = lambdas.reduce((a, b) => a + (b - lm) ** 2, 0) / (L - 1);
172
+ nyholt = 1 + (L - 1) * (1 - lv / L);
173
+ liJi = lambdas.reduce((a, l) => { const x = Math.abs(l); return a + (x >= 1 ? 1 : 0) + (x - Math.floor(x)); }, 0);
174
+ }
175
+ let best = 0;
176
+ for (let i = 1; i < sharpes.length; i++) if (sharpes[i] > sharpes[best]) best = i;
177
+ return {
178
+ variants: k,
179
+ periods,
180
+ constant_variants: k - L,
181
+ best_variant: live.length ? live[best] : null,
182
+ best_sharpe_annualized: live.length ? sharpes[best] : null,
183
+ cross_trial_sharpe_sd_annualized: sharpeSd,
184
+ mean_pairwise_correlation: pairMean,
185
+ sd_pairwise_correlation: pairSd,
186
+ // Rounded up with a tolerance (a sum of eigenvalues equal to 12 can arrive as 12.000000000000014),
187
+ // never more than the variants that vary, and at least 2, the smallest count the DSR accepts.
188
+ effective_trials: { nyholt, li_ji: liJi, used: Math.max(2, Math.min(L, Math.ceil(liJi - 1e-9))), method: "Li and Ji (2005), rounded up, at most the variants sent, at least 2" },
189
+ };
190
+ }
191
+
192
+ /**
193
+ * The Null Zoo family whose measured size an audit quotes for this shape. The rules and their order
194
+ * are the ones pre-registered in config/research/null-zoo-v1-prereg.json; a test keeps them equal.
195
+ */
196
+ export function nullZooFamily(shape, search = null) {
197
+ if (search && search.mean_pairwise_correlation >= 0.3) return search.sd_pairwise_correlation >= 0.15 ? "block_cluster" : "correlated_trials";
198
+ if (Math.abs(shape.lag1_autocorrelation) >= 0.1) return "ar1";
199
+ if (shape.skew <= -0.5) return "skew_negative";
200
+ if (shape.skew >= 0.5) return "skew_positive";
201
+ if (shape.excess_kurtosis >= 2 && shape.lag1_autocorrelation_of_squares >= 0.1) return "garch";
202
+ if (shape.excess_kurtosis >= 2) return "student_t4";
203
+ if (shape.lag1_autocorrelation_of_squares >= 0.1) return "regimes";
204
+ return "iid_normal";
205
+ }
206
+
207
+ /** The t-statistic of a series' mean with a Newey-West (Bartlett, lag floor(4 (T/100)^(2/9))) variance. */
208
+ export function neweyWestT(xs) {
209
+ const n = xs.length;
210
+ const m = mean(xs);
211
+ const lag = Math.floor(4 * Math.pow(n / 100, 2 / 9));
212
+ let lrv = 0;
213
+ for (let i = 0; i < n; i++) { const d = xs[i] - m; lrv += d * d; }
214
+ for (let l = 1; l <= lag; l++) {
215
+ let g = 0;
216
+ for (let i = l; i < n; i++) g += (xs[i] - m) * (xs[i - l] - m);
217
+ lrv += 2 * (1 - l / (lag + 1)) * g;
218
+ }
219
+ lrv /= n;
220
+ return lrv > 0 ? m / Math.sqrt(lrv / n) : 0;
221
+ }
222
+
223
+ /** One-sided p-value of "the mean is above zero" from a stationary-bootstrap t (see the header). */
224
+ export function blockBootstrapT(xs, { reps, block = defaultBlock(xs.length), seed }) {
225
+ const n = xs.length;
226
+ let sum = 0, sq = 0;
227
+ for (let i = 0; i < n; i++) { sum += xs[i]; sq += xs[i] * xs[i]; }
228
+ const m0 = sum / n;
229
+ const sd = Math.sqrt(Math.max((sq - n * m0 * m0) / (n - 1), 0));
230
+ if (!(sd > 0)) return 1;
231
+ const observed = m0 / (sd / Math.sqrt(n));
232
+ const next = makeRandom(seed);
233
+ const idx = new Int32Array(n);
234
+ let hits = 0;
235
+ for (let b = 0; b < reps; b++) {
236
+ stationaryIndices(n, block, next, idx);
237
+ let s = 0, q = 0;
238
+ for (let i = 0; i < n; i++) { const v = xs[idx[i]]; s += v; q += v * v; }
239
+ const m = s / n;
240
+ const v = (q - n * m * m) / (n - 1);
241
+ if (!(v > 0)) { hits++; continue; }
242
+ if ((m - m0) / Math.sqrt(v / n) >= observed) hits++;
243
+ }
244
+ return (hits + 1) / (reps + 1);
245
+ }
246
+
247
+ const quantileSorted = (sorted, q) => {
248
+ const h = (sorted.length - 1) * q;
249
+ const lo = Math.floor(h);
250
+ const hi = Math.min(lo + 1, sorted.length - 1);
251
+ return sorted[lo] + (h - lo) * (sorted[hi] - sorted[lo]);
252
+ };
253
+
254
+ /**
255
+ * Out-of-sample decay from CSCV's in-sample-best pairs ([in-sample Sharpe, out-of-sample Sharpe],
256
+ * per period, as js/pbo-core.js returns them): the distribution of the selected variant's
257
+ * out-of-sample Sharpe, and the least-squares line of out-of-sample on in-sample. With
258
+ * periodsPerYear 1 the Sharpe ratios stay per period, as validate_overfitting reports them.
259
+ */
260
+ export function oosDecay(isOosPairs, periodsPerYear = 1) {
261
+ const root = Math.sqrt(Number(periodsPerYear));
262
+ const pairs = isOosPairs.map(([a, b]) => [a * root, b * root]);
263
+ const oos = pairs.map((p) => p[1]).sort((a, b) => a - b);
264
+ const n = pairs.length;
265
+ const mx = pairs.reduce((a, p) => a + p[0], 0) / n;
266
+ const my = pairs.reduce((a, p) => a + p[1], 0) / n;
267
+ let sxy = 0, sxx = 0, syy = 0;
268
+ for (const [x, y] of pairs) { sxy += (x - mx) * (y - my); sxx += (x - mx) ** 2; syy += (y - my) ** 2; }
269
+ const slope = sxx > 0 ? sxy / sxx : 0;
270
+ return {
271
+ splits: n,
272
+ unit: Number(periodsPerYear) === 1 ? "per period" : "annualized",
273
+ oos_sharpe: {
274
+ median: quantileSorted(oos, 0.5), p10: quantileSorted(oos, 0.1), p90: quantileSorted(oos, 0.9),
275
+ prob_below_zero: oos.filter((v) => v < 0).length / n,
276
+ },
277
+ degradation: { slope, intercept: my - slope * mx, r2: sxx > 0 && syy > 0 ? (sxy * sxy) / (sxx * syy) : 0 },
278
+ };
279
+ }
280
+
281
+ /** A per-period oosDecay result in annualized Sharpe units; the slope, r2 and shares do not change. */
282
+ export function annualizeDecay(decay, periodsPerYear) {
283
+ const root = Math.sqrt(Number(periodsPerYear));
284
+ const o = decay.oos_sharpe;
285
+ return {
286
+ ...decay,
287
+ unit: "annualized",
288
+ oos_sharpe: { median: o.median * root, p10: o.p10 * root, p90: o.p90 * root, prob_below_zero: o.prob_below_zero },
289
+ degradation: { ...decay.degradation, intercept: decay.degradation.intercept * root },
290
+ };
291
+ }
292
+
293
+ // The ids are stable: an agent can act on them, and a changelog can name them.
294
+ export const FIX_IDS = Object.freeze([
295
+ "count_every_variant", "declared_trials_below_counted", "not_distinguishable_from_luck", "interval_includes_zero",
296
+ "autocorrelated_returns", "track_record_too_short", "overfit_selection", "expected_live_sharpe_below_zero",
297
+ "stress_and_capacity_next",
298
+ ]);
299
+
300
+ /**
301
+ * At most five next steps, most decisive first. `context` carries what the audit found; each step
302
+ * is {id, why, next}: the finding with its numbers, and the change or call to make next.
303
+ */
304
+ export function fixNext(context) {
305
+ const steps = [];
306
+ const add = (id, why, next) => steps.push({ id, why, next });
307
+ const { headline, shape, interval, search, declaredTrials, trackRecord, overfitting, decay } = context;
308
+ const f2 = (x) => x.toFixed(2);
309
+ if (headline && headline.p > headline.level) {
310
+ add("not_distinguishable_from_luck", `p ${headline.p.toFixed(3)} > ${headline.level}.`, search ? "Pre-declare a smaller grid (backtest_strategy), then audit again." : "Try fewer variants or add out-of-sample data.");
311
+ }
312
+ if (search && declaredTrials !== undefined && declaredTrials < search.effective_trials.used) {
313
+ add("declared_trials_below_counted", `Declared ${declaredTrials} trials; the variants count as ${search.effective_trials.used}.`, "Already applied: the counted number was used.");
314
+ }
315
+ if (!search) add("count_every_variant", "Only declared trials counted.", "Send every variant's returns (variants_file).");
316
+ if (Math.abs(shape.lag1_autocorrelation) >= 0.1) {
317
+ add("autocorrelated_returns", `Lag-1 autocorrelation ${f2(shape.lag1_autocorrelation)}; Lo-adjusted Sharpe ${f2(shape.lo_adjusted_sharpe_annualized)}.`,
318
+ "Check for stale or smoothed prices (summarize_series); quote the adjusted Sharpe.");
319
+ }
320
+ if (interval && interval.intervals["0.95"][0] <= 0) {
321
+ add("interval_includes_zero", `95% Sharpe interval ${f2(interval.intervals["0.95"][0])} to ${f2(interval.intervals["0.95"][1])}.`, "Needs a longer history (validate_backtest_length).");
322
+ }
323
+ if (overfitting && overfitting.pbo >= 0.5) add("overfit_selection", `Overfitting probability ${f2(overfitting.pbo)}.`, "Shrink the grid or fix the selection rule in advance.");
324
+ if (decay && decay.oos_sharpe.median <= 0) add("expected_live_sharpe_below_zero", `Median out-of-sample Sharpe of the pick ${f2(decay.oos_sharpe.median)}.`, "Expect no live edge from this selection.");
325
+ if (trackRecord && trackRecord.short) add("track_record_too_short", trackRecord.finding, "Keep it running before scaling (validate_track_record).");
326
+ // Nothing to fix and luck rejected: the next hurdles are bad markets and a real broker.
327
+ if (!steps.length && headline && headline.p <= headline.level) add("stress_and_capacity_next", `p ${headline.p.toFixed(3)} <= ${headline.level}.`, "Run stress_test and check_feasibility before trading it.");
328
+ return steps.slice(0, 5);
329
+ }