canli-validation-mcp 0.10.0 → 0.11.0

package/README.md

@@ -71,6 +71,16 @@ repository for the full design.
 
 ## Tools
 
+Unreleased source adds local journal binding to `validate_paper_evidence`: run
+`CANLI_LOCAL=1 node mcp/src/server.mjs` from the repository, and send exactly one of `record`
+or `record_file`, plus `journal_file` to check source hashes, signatures and recomputed claims.
+`record_file` accepts a standard record, a `{record,signature}` envelope, or the full execution
+export bundle; companion metrics/observations are checked for full bundles. Signed records
+need the detached signature. `bindings.all_match` must be true for source validation to pass.
+Without a journal, the result explicitly reports structure-only conformance. Files and
+signatures are refused in hosted/remote mode and never uploaded. Local results have no Canli
+receipt. The current npm/hosted release retains the existing record-only API.
+
 | Tool | Calls | Key required |
 |---|---|---|
 | `get_key` | `POST /api/v1/keys` | no |
@@ -127,6 +137,49 @@ original SEC response and the record's own boundary sentence: these are accounti
 reported to the SEC, not market prices, returns or a recommendation. Companies and concepts
 outside the current release return an error with the available concepts listed.
 
+## The lab: backtest, summarize, stress, check feasibility
+
+Four tools compute in the server process itself, on your machine or on the hosted endpoint, with
+nothing sent to the API and no receipt stored. Each result names the SHA-256 of exactly the numbers
+it was computed from, and states what it does not establish.
+
+- **`backtest_strategy`** runs a rule over every parameter set in a grid, on your prices:
+  `sma_cross` (fast, slow), `momentum` (lookback, skip), `mean_reversion` (window, entry_z),
+  `breakout` (lookback) or `buy_and_hold`, long-only or with `allow_short`, after a cost per unit
+  of turnover. The position held over each period is decided from closes up to the one before it,
+  so no rule can see the future (a test changes later prices and checks that no earlier position
+  moves). It then validates the best variant with the number of variants **this call ran**, not a
+  number someone declared: the deflated Sharpe ratio across the grid's measured Sharpe dispersion,
+  the CSCV probability of backtest overfitting on every variant's returns, the probabilistic Sharpe
+  and the minimum track record, next to buy and hold over the same window. At most 200 variants and
+  20,000 prices per call. No code is ever run: a strategy is a family plus numbers.
+- **`summarize_series`** reads a long price or return series and states it in about a hundred words,
+  plus a field for every figure: growth, volatility, Sharpe and drift t-statistic, the worst
+  drawdown with its dates and recovery, trend, the volatility regime (terciles of its own 21-period
+  volatility), tails, jumps (beyond six robust standard deviations), autocorrelation, stale data and,
+  with a benchmark, correlation and beta. A five-year daily series is about 1,260 numbers; the
+  summary is a paragraph.
+- **`stress_test`** resamples a strategy's returns with a stationary block bootstrap (seeded, so a run
+  reproduces exactly) and reports how often the drawdown limit breaks and the Sharpe turns negative,
+  then applies four named scenarios with their rules stated: a crash at the equity high (default the
+  larger of 20% and three times the worst period), volatility multiplied, the worst stretch lived
+  twice, and positions stuck for several periods after the worst one. The fragility share is the part
+  of resampled histories that break the drawdown limit or lose money on a risk-adjusted basis.
+  Generative models are not used: trained on one series they memorize it or invent dynamics nobody
+  can check.
+- **`check_feasibility`** checks a plan against a real broker before it trades: the broker's published
+  order-rate limit against the rebalance's burst of orders (Alpaca 200 a minute, Interactive Brokers
+  about 50 a second), the minimum order (Alpaca 1 USD notional), US day-trading rules as they stand
+  in 2026 (FINRA retired the pattern day trader rule and its 25,000 USD minimum on 4 June 2026; firms
+  may phase in its replacement until 20 October 2027), T+1 settlement in cash accounts, each order's
+  share of daily volume, square-root market impact (coefficient Y, default 1) with every copy of the
+  same strategy counted, and the capital at which costs and impact eat the expected gross return.
+  Every broker fact carries the date it was checked and its source.
+
+On your own machine, `prices_file`, `series_file` and `returns_file` take a CSV or JSON path instead
+of the numbers. Only numbers are read, plus an ISO date column when the file has one, so results can
+name the day a drawdown began.
+
 ## Auditing a backtest in one call
 
 `audit_backtest` takes one strategy's return series, the number of variants tried and their Sharpe
@@ -147,11 +200,18 @@ took three audit questions from 4 of 9 to 8 of 9 answered correctly on gpt-5.4-m
 
 ## Prompts, resources and structured results
 
-Clients that show MCP prompts offer two guided workflows: `validate_backtest` (deflated Sharpe, then
-overfitting, then the track record needed, reported with what each number does not establish) and
-`track_record_needed`. Two resources can be read: `canli://limits`, the boundary sentences every
-result carries, and `canli://sources`, the papers behind each validator and how each is checked
-against them. Every tool result carries its envelope both as text and as `structuredContent`.
+Clients that show MCP prompts offer six guided workflows: `validate_backtest` (deflated Sharpe, then
+overfitting, then the track record needed, reported with what each number does not establish),
+`track_record_needed`, `backtest_and_validate`, `stress_my_strategy`, `production_check` and
+`summarize_market_series`. Resources: `canli://limits`, the boundary sentences every result carries;
+`canli://sources`, the papers behind each validator and how each is checked against them;
+`canli://strategy-spec`, the JSON Schema of every strategy family and its parameters; and
+`canli://openapi`, the API's OpenAPI 3.1 document. Two resource templates are for writing code
+against the tools: `canli://schemas/{tool}` returns a tool's exact input and output JSON Schema, and
+`canli://examples/{language}/{tool}` a working call in `python`, `javascript` or `curl` (both
+variables complete). A test compiles every generated Python and JavaScript example and checks that
+every example's arguments are valid input. Every tool result carries its envelope both as text and
+as `structuredContent`.
 
 ## Compact context (0.3.0)
 
@@ -183,7 +243,7 @@ an array of objects.
 | `CANLI_API_BASE` | `https://canlicapital.com` | Where the API lives. Point it at a preview deployment for testing. |
 | `CANLI_KEY` | unset | A key already issued from `POST /api/v1/keys`. When set, `get_key` sends no request and reports the key is already configured; every other tool sends it as `Authorization: Bearer <key>`. |
 | `CANLI_FULL_ENVELOPE` | unset | `1` or `true` returns each validation's full API envelope instead of the compact result (below). |
-| `CANLI_TOOLSETS` | all | Which tools to list: a comma-separated choice of `validate`, `receipts`, `company` and `status`, or `all`. An unknown name is refused at startup. See "Toolsets" below. |
+| `CANLI_TOOLSETS` | all | Which tools to list: a comma-separated choice of `validate`, `receipts`, `company`, `status` and `lab`, or `all`. An unknown name is refused at startup. See "Toolsets" below. |
 | `CANLI_LOCAL` | unset | `1` or `true` runs the eight validators on this machine (private local mode, below): no key, no network, no receipt. |
 
 If `CANLI_KEY` is not set and local mode is off, call `get_key` once per session before the validators. The key it
@@ -338,7 +398,7 @@ On a breadth result this is about half the text. Set `CANLI_FULL_ENVELOPE=1` to
 ## Toolsets (tokens)
 
 A client sends the model the whole tool list on every turn, and it is most of each turn's prompt:
-a validation result is a few hundred tokens, the list of all fifteen tools several thousand. A
+a validation result is a few hundred tokens, the list of all nineteen tools several thousand. A
 client that needs one kind of tool can list only that kind, with `CANLI_TOOLSETS` (stdio) or
 `?toolsets=` (hosted endpoint). The default is every tool.
 
@@ -348,17 +408,19 @@ client that needs one kind of tool can list only that kind, with `CANLI_TOOLSETS
 | `receipts` | `get_receipt`, `verify_receipt` |
 | `company` | `company_financial_history` |
 | `status` | `service_status` |
+| `lab` | `backtest_strategy`, `summarize_series`, `stress_test`, `check_feasibility` |
 
 Measured with `bench/tool_list_tokens.py` (tokenizer: tiktoken `o200k_base`; other models'
 tokenizers give different absolute counts), in the shape an OpenAI-style client sends the list:
 
 | CANLI_TOOLSETS | tools | tokens per turn | of all |
 |---|---|---|---|
-| `all` | 15 | 4,194 | 100% |
-| `validate` | 11 | 3,526 | 84% |
-| `receipts` | 2 | 312 | 7% |
-| `company` | 1 | 273 | 7% |
-| `status` | 1 | 89 | 2% |
+| `all` | 19 | 5,946 | 100% |
+| `validate` | 11 | 3,685 | 62% |
+| `receipts` | 2 | 312 | 5% |
+| `company` | 1 | 273 | 5% |
+| `status` | 1 | 89 | 1% |
+| `lab` | 4 | 1,595 | 27% |
 
 Providers cache a tool list that is identical from turn to turn and bill the cached part at a
 fraction of the price (`test/tool-list-stable.test.mjs` keeps each list byte-stable); a smaller list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-validation-mcp",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Check whether a backtest is real: deflated Sharpe, CSCV probability of backtest overfitting, minimum track record and backtest length, haircut Sharpe and luck-equivalent trials, as an MCP server. Local mode, hosted endpoint, signed receipts.",
   "keywords": [
     "mcp",
@@ -15,7 +15,10 @@
     "overfitting",
     "quantitative-finance",
     "quant",
-    "trading"
+    "trading",
+    "backtest-engine",
+    "stress-test",
+    "market-impact"
   ],
   "private": false,
   "type": "module",

package/src/journal-evidence.mjs

@@ -0,0 +1,35 @@
+import { resolve } from 'node:path';
+import { computeLocally } from './local.mjs';
+import { MAX_JOURNAL_BYTES, readBoundedFile, readRecordFile } from './local/js/journal-files.js';
+import { journalBindings } from './local/js/trade-journal-export-core.js';
+
+export function validateLocalJournalEvidence(input) {
+  let record = input.record, signature = input.signature, bundle;
+  if (input.record_file) {
+    const file = readRecordFile(resolve(input.record_file));
+    if (file && typeof file === 'object' && Object.hasOwn(file, 'record')) {
+      record = file.record;
+      // A {record,signature} envelope is also accepted. Full exports advertise their
+      // financial companion fields and those must be recomputed, not ignored.
+      if (Object.keys(file).some(k => !['record', 'signature'].includes(k))) bundle = file;
+      if (signature !== undefined && file.signature !== undefined) throw new Error('send a detached signature inline or in the record file, not both');
+      signature ??= file.signature;
+    } else record = file;
+    if (!record || typeof record !== 'object' || Array.isArray(record) || record.schema !== 'canli.paper-evidence.v0') throw new Error('record file must contain a canli.paper-evidence.v0 record or export bundle');
+  }
+  const result = computeLocally('validate_paper_evidence', { record });
+  if (result.failed) return result;
+  const data = result.envelope.data;
+  const unchecked = { checked: false, all_match: null, reason: 'No source journal checked; conformance covers structure and field relationships only.' };
+  // Conformance first prevents malformed record members from reaching the financial verifier.
+  const bindings = input.journal_file && data.valid
+    ? journalBindings(record, readBoundedFile(resolve(input.journal_file), { maxBytes: MAX_JOURNAL_BYTES }), signature, bundle)
+    : input.journal_file ? { checked: false, all_match: false, reason: 'Source verification requires a conforming record.' } : unchecked;
+  data.bindings = bindings;
+  data.conformance_valid = data.valid;
+  if (input.journal_file) {
+    data.valid = data.valid && bindings.all_match === true;
+    data.plain_reading = data.valid ? 'The record conforms and its reconstructable claims match the supplied signed journal and selected range. Key possession is self-attestation; broker authenticity, completeness and trusted time are not established.' : 'Conformance or source-bound recomputation failed; this record has not passed journal verification.';
+  } else data.plain_reading += ' No source journal or record signature was checked.';
+  return result;
+}

package/src/lab-schemas.mjs

@@ -0,0 +1,122 @@
+// mcp/src/lab-schemas.mjs
+//
+// Input and output schemas for the lab tools (src/lab.mjs): backtest_strategy, summarize_series,
+// stress_test and check_feasibility. Like the validators' descriptions, each tool description
+// carries one sentence of its own result's boundary language verbatim (test/lab.test.mjs checks
+// it against the sentences the computation attaches), so an agent reads what the result cannot be
+// used to claim before it ever calls the tool. Descriptions stay terse: the tool list is re-sent to
+// the model on every turn.
+import { z } from "zod";
+import { BACKTEST_LIMITS_TEXT, FAMILIES } from "./local/js/backtest-core.js";
+import { FEASIBILITY_LIMITS_TEXT } from "./local/js/feasibility-core.js";
+import { SUMMARY_LIMITS_TEXT } from "./local/js/series-summary-core.js";
+import { STRESS_LIMITS_TEXT } from "./local/js/stress-core.js";
+
+export const LAB_BOUNDARY = Object.freeze({
+  backtest_strategy: BACKTEST_LIMITS_TEXT[3],
+  summarize_series: SUMMARY_LIMITS_TEXT[2],
+  stress_test: STRESS_LIMITS_TEXT[2],
+  check_feasibility: FEASIBILITY_LIMITS_TEXT[0],
+});
+
+export const LAB_TOOL_DESCRIPTIONS = Object.freeze({
+  backtest_strategy: `Backtest a rule on your prices over a whole parameter grid, then validate the best with the count of variants actually run: deflated Sharpe, overfitting probability, minimum track record, vs buy and hold, after costs. ${LAB_BOUNDARY.backtest_strategy}`,
+  summarize_series: `A long price or return series in about 100 words plus fields: growth, risk, dated drawdowns, trend, volatility regime, tails, jumps, stale data. Use instead of reading raw bars. ${LAB_BOUNDARY.summarize_series}`,
+  stress_test: `Stress a strategy's returns: bootstrap histories (how often the drawdown limit breaks or Sharpe turns negative) and named crash, volatility, repeat and stuck-position scenarios, with a fragility share. ${LAB_BOUNDARY.stress_test}`,
+  check_feasibility: `Check a trading plan before it trades: broker order-rate and minimum-order limits, 2026 US day-trading rules, square-root market impact with crowding, and the capital where costs eat the return. ${LAB_BOUNDARY.check_feasibility}`,
+});
+
+const FAMILY_NAMES = Object.keys(FAMILIES);
+// Lengths, counts and magnitudes are checked by the computation itself (src/local/js/*-core.js),
+// with messages that say what to send instead; the advertised schema keeps types, enums and the
+// bounds that tell a model what a value means (fractions, signs), because every bound here is
+// re-sent to the model on every turn.
+const series = () => z.array(z.number());
+const file = (what) => z.string().describe(`CSV or JSON of ${what} on this machine; local server only.`);
+const column = z.union([z.string(), z.number().int()]).describe("Column name or 1-based position.");
+const periods = z.number().describe("252 daily (default), 365 crypto, 52 weekly, 12 monthly.");
+const dates = z.array(z.string()).describe("Optional ISO dates, one per value.");
+
+export const backtestInput = z
+  .object({
+    family: z.enum(FAMILY_NAMES).describe("sma_cross (fast, slow), momentum (lookback, skip), mean_reversion (window, entry_z), breakout (lookback), buy_and_hold."),
+    grid: z.record(z.string(), z.union([z.number(), z.array(z.number())])).optional()
+      .describe('Values per parameter, e.g. {"fast":[10,20],"slow":[50,200]}; every valid combination runs (max 200).'),
+    prices: series().optional().describe("Prices, oldest first."),
+    prices_file: file("prices").optional(),
+    prices_column: column.optional(),
+    dates: dates.optional(),
+    periods_per_year: periods.optional(),
+    cost_bps: z.number().min(0).optional().describe("Cost per unit of turnover, bps; default 5."),
+    allow_short: z.boolean().optional().describe("Short instead of flat; default false."),
+  })
+  .strict();
+
+export const summarizeInput = z
+  .object({
+    prices: series().optional().describe("Prices, oldest first; or returns, or series_file."),
+    returns: z.array(z.number()).optional().describe("Returns as fractions, oldest first."),
+    series_file: file("prices or returns").optional(),
+    series_column: column.optional(),
+    series_kind: z.enum(["prices", "returns"]).optional().describe("series_file holds; default prices."),
+    dates: dates.optional(),
+    periods_per_year: periods.optional(),
+    benchmark_returns: z.array(z.number()).optional().describe("Same-period benchmark returns; adds beta."),
+    name: z.string().optional().describe("Label for the text."),
+  })
+  .strict();
+
+export const stressInput = z
+  .object({
+    returns: z.array(z.number()).optional().describe("Strategy returns as fractions, oldest first."),
+    returns_file: file("returns").optional(),
+    returns_column: column.optional(),
+    periods_per_year: periods.optional(),
+    paths: z.number().int().optional().describe("Default 1000."),
+    block: z.number().optional().describe("Mean block length; default cube root of n."),
+    seed: z.number().int().optional().describe("Default 42; reproduces exactly."),
+    drawdown_limit: z.number().gt(0).lt(1).optional().describe("Fraction; default 0.2."),
+    crash: z.number().gt(-1).lt(0).optional().describe("Crash size, negative; default min(-0.2, 3x worst period)."),
+    volatility_multiplier: z.number().optional().describe("Default 2."),
+    outage_periods: z.number().int().optional().describe("Stuck periods after the worst; default 5."),
+  })
+  .strict();
+
+export const feasibilityInput = z
+  .object({
+    broker: z.enum(["alpaca", "ibkr", "other"]).optional().describe("Default other."),
+    asset_class: z.enum(["us_equity", "crypto", "futures", "fx", "options"]).optional(),
+    account: z.enum(["cash", "margin"]).optional(),
+    capital_usd: z.number(),
+    orders_per_rebalance: z.number().int(),
+    rebalances_per_year: z.number(),
+    turnover_per_year: z.number().min(0).describe("Buys plus sells a year / capital."),
+    adv_usd: z.number().describe("Daily dollar volume of a typical holding."),
+    daily_volatility: z.number().max(1).describe("Of a typical holding, e.g. 0.02."),
+    copies: z.number().int().optional().describe("Agents trading the same signal at once; default 1."),
+    expected_gross_return: z.number().min(-1).optional().describe("Annual, before costs; adds capacity."),
+    spread_and_fees_bps: z.number().min(0).optional().describe("Per trade; default 0."),
+    impact_coefficient: z.number().optional().describe("Square-root law Y; default 1."),
+    minutes_per_rebalance: z.number().optional().describe("Default 1."),
+    orders_per_minute_limit: z.number().optional().describe("If the broker's is not on file."),
+  })
+  .strict();
+
+const loose = z.looseObject({}).optional();
+const sentences = z.array(z.string()).optional();
+
+export const backtestOutput = z
+  .looseObject({ variants: loose, selected: loose, buy_and_hold: loose, validation: loose, plain_reading: z.string().optional(), limits: sentences, source: loose })
+  .describe("selected holds the best variant's parameters and metrics; validation the deflated Sharpe, overfitting probability and minimum track record counting every variant run; plain_reading states them.");
+
+export const summaryOutput = z
+  .looseObject({ text: z.string().optional(), growth: loose, risk: loose, drawdown: loose, trend: loose, volatility: z.looseObject({}).nullable().optional(), tails: loose, jumps: loose, limits: sentences, source: loose })
+  .describe("text is the summary to read; the other fields hold each figure by the rule named in it.");
+
+export const stressOutput = z
+  .looseObject({ baseline: loose, resampled: loose, scenarios: z.array(z.unknown()).optional(), fragility: loose, plain_reading: z.string().optional(), limits: sentences, source: loose })
+  .describe("resampled holds bootstrap percentiles and breach frequencies; scenarios each named stress and its rule; fragility the share of histories breaking the limit or losing.");
+
+export const feasibilityOutput = z
+  .looseObject({ verdict: z.string().optional(), checks: z.array(z.unknown()).optional(), to_change: z.array(z.string()).optional(), sources: loose, plain_reading: z.string().optional(), limits: sentences })
+  .describe("verdict summarizes the checks; each check has a status (ok, warning, blocking, unknown), its finding and numbers; to_change lists what to fix.");

package/src/lab.mjs

@@ -0,0 +1,309 @@
+// mcp/src/lab.mjs
+//
+// The lab: four tools that compute in this process, on stdio and on the hosted endpoint alike,
+// from src/local (mirrored byte for byte from the canlicapital repository by
+// scripts/sync-local.mjs). Nothing is sent to an API and no receipt is stored; files are read only
+// by the server on the user's own machine, and only their numbers (and ISO dates) are used.
+//
+//   backtest_strategy   a rule-based strategy over every parameter set in a grid, validated with
+//                       the number of variants actually run
+//   summarize_series    a long series in about a hundred words an agent can reason over
+//   stress_test         resampled histories and named scenarios, with a fragility share
+//   check_feasibility   broker limits, day-trading rules, market impact, crowding and capacity
+//
+// Also here: the code-generation resources (every tool's exact JSON Schemas, the strategy spec,
+// runnable client examples, the API's OpenAPI document) and the lab's guided prompts.
+import { createHash } from "node:crypto";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { BACKTEST_LIMITS, BACKTEST_LIMITS_TEXT, FAMILIES, runBacktest } from "./local/js/backtest-core.js";
+import { FEASIBILITY_LIMITS_TEXT, checkFeasibility } from "./local/js/feasibility-core.js";
+import { SUMMARY_LIMITS_TEXT, summarizeSeries } from "./local/js/series-summary-core.js";
+import { STRESS_LIMITS_TEXT, stressTest } from "./local/js/stress-core.js";
+import { LAB_TOOL_DESCRIPTIONS, backtestInput, backtestOutput, feasibilityInput, feasibilityOutput, stressInput, stressOutput, summarizeInput, summaryOutput } from "./lab-schemas.mjs";
+import { readSeriesWithDates } from "./series-file.mjs";
+
+export const LAB_TOOLS = Object.freeze(["backtest_strategy", "summarize_series", "stress_test", "check_feasibility"]);
+
+// Same shape as every other tool's result: the object as text, and as structured content.
+const labText = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }], structuredContent: value });
+
+function parse(schema, args, tool) {
+  const result = schema.safeParse(args ?? {});
+  if (result.success) return result.data;
+  throw new Error(`${tool}: ${result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+}
+
+// The series a tool works on: inline, or from a file on this machine. Exactly one of the two.
+function readInput(session, tool, { inline, file, column, inlineName, fileName }) {
+  if ((inline === undefined) === (file === undefined)) throw new Error(`${tool}: send exactly one of ${inlineName} or ${fileName}`);
+  if (file === undefined) return { values: inline, dates: undefined, source: {} };
+  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.`);
+  const read = readSeriesWithDates(file, column);
+  return {
+    values: read.values,
+    dates: read.dates ?? undefined,
+    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 } : {}) },
+  };
+}
+
+// The digest of exactly the numbers a result was computed from, so a result can be tied to its input.
+const digest = (values) => createHash("sha256").update(JSON.stringify(values)).digest("hex");
+
+// Labels are echoed into results, so each is cut to a date-and-time length; a label is never a
+// channel for long text.
+const labels = (values) => values?.map((value) => String(value).slice(0, 40));
+
+export async function toolBacktestStrategy(session, args) {
+  const input = parse(backtestInput, args, "backtest_strategy");
+  const { values, dates, source } = readInput(session, "backtest_strategy", { inline: input.prices, file: input.prices_file, column: input.prices_column, inlineName: "prices", fileName: "prices_file" });
+  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 });
+  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" } });
+}
+
+export async function toolSummarizeSeries(session, args) {
+  const input = parse(summarizeInput, args, "summarize_series");
+  const inline = input.prices ?? input.returns;
+  if (input.prices !== undefined && input.returns !== undefined) throw new Error("summarize_series: send prices or returns, not both");
+  const { values, dates, source } = readInput(session, "summarize_series", { inline, file: input.series_file, column: input.series_column, inlineName: "prices (or returns)", fileName: "series_file" });
+  const kind = input.series_file !== undefined ? (input.series_kind ?? "prices") : input.prices !== undefined ? "prices" : "returns";
+  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) });
+  return labText({ ...result, limits: SUMMARY_LIMITS_TEXT, source: { ...source, kind, values: values.length, input_sha256: digest(values) } });
+}
+
+export async function toolStressTest(session, args) {
+  const input = parse(stressInput, args, "stress_test");
+  const { values, source } = readInput(session, "stress_test", { inline: input.returns, file: input.returns_file, column: input.returns_column, inlineName: "returns", fileName: "returns_file" });
+  const result = stressTest({ ...input, returns: values });
+  return labText({ ...result, limits: STRESS_LIMITS_TEXT, source: { ...source, returns: values.length, input_sha256: digest(values) } });
+}
+
+export async function toolCheckFeasibility(session, args) {
+  const input = parse(feasibilityInput, args, "check_feasibility");
+  return labText({ ...checkFeasibility(input), limits: FEASIBILITY_LIMITS_TEXT });
+}
+
+// The lab computes locally and changes nothing anywhere: read-only, closed world, idempotent.
+const LAB_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+
+export function labToolSpecs(session) {
+  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)];
+  return [
+    spec("backtest_strategy", "Backtest a rule over a parameter grid, validated", backtestInput, backtestOutput, toolBacktestStrategy),
+    spec("summarize_series", "Summarize a price or return series", summarizeInput, summaryOutput, toolSummarizeSeries),
+    spec("stress_test", "Stress-test a strategy's returns", stressInput, stressOutput, toolStressTest),
+    spec("check_feasibility", "Check a plan against broker limits and impact", feasibilityInput, feasibilityOutput, toolCheckFeasibility),
+  ];
+}
+
+// ---------------------------------------------------------------------------------------------
+// Code-generation resources. An agent writing code against these tools reads the exact schemas
+// and a working call instead of guessing argument names.
+// ---------------------------------------------------------------------------------------------
+
+// One small, valid call per tool: the arguments every generated example sends.
+export const EXAMPLE_ARGS = Object.freeze({
+  get_key: {},
+  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 },
+  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]] },
+  validate_reality_check: { matrix_file: "variants.csv" },
+  validate_paper_evidence: { record_file: "paper_record.json" },
+  validate_breadth: { sleeve_sharpe: 0.8, average_pairwise_correlation: 0.2, sleeves: 10 },
+  validate_track_record: { observed_sharpe_annualized: 1.2, periods_per_year: 252, skew: -0.3, non_excess_kurtosis: 4 },
+  validate_backtest_length: { target_sharpe_annualized: 1, effective_independent_trials: 50 },
+  validate_haircut_sharpe: { observed_sharpe_annualized: 1.5, periods_per_year: 252, observations: 1260, tests: 50 },
+  validate_luck_trials: { observed_sharpe_annualized: 1.5, periods_per_year: 252, observations: 1260 },
+  audit_backtest: { returns_file: "backtest_returns.csv", periods_per_year: 252, effective_independent_trials: 20, cross_trial_sharpe_sd_annualized: 0.5 },
+  get_receipt: { id: "0123456789abcdef01234567" },
+  verify_receipt: { id: "0123456789abcdef01234567" },
+  service_status: {},
+  company_financial_history: { ticker: "AAPL", concept: "Assets", limit: 8 },
+  backtest_strategy: { family: "sma_cross", grid: { fast: [10, 20, 50], slow: [100, 200] }, prices_file: "prices.csv", cost_bps: 5 },
+  summarize_series: { series_file: "prices.csv", series_kind: "prices", name: "My asset" },
+  stress_test: { returns_file: "strategy_returns.csv", drawdown_limit: 0.2, paths: 1000, seed: 42 },
+  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 },
+});
+
+const usesFile = (args) => Object.keys(args).some((k) => k.endsWith("_file"));
+const cleanArgs = (args) => Object.fromEntries(Object.entries(args).filter(([k]) => !k.endsWith("_note")));
+
+export function exampleCode(language, tool) {
+  const args = cleanArgs(EXAMPLE_ARGS[tool] ?? {});
+  const json = JSON.stringify(args, null, 2);
+  const fileNote = usesFile(args) ? "Point the *_file argument at your own CSV; the local server reads it, the hosted endpoint cannot." : "";
+  if (language === "python") {
+    return [
+      "# pip install mcp",
+      "# Runs the server on this machine (Node.js 20.10+). CANLI_LOCAL=1 computes everything locally, no key.",
+      fileNote ? `# ${fileNote}` : null,
+      "import asyncio",
+      "from mcp import ClientSession, StdioServerParameters",
+      "from mcp.client.stdio import stdio_client",
+      "",
+      'SERVER = StdioServerParameters(command="npx", args=["-y", "canli-validation-mcp"], env={"CANLI_LOCAL": "1"})',
+      "",
+      "async def main():",
+      "    async with stdio_client(SERVER) as (read, write):",
+      "        async with ClientSession(read, write) as session:",
+      "            await session.initialize()",
+      `            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")})`,
+      "            print(result.structuredContent)",
+      "",
+      "asyncio.run(main())",
+      "",
+    ].filter((line) => line !== null).join("\n");
+  }
+  if (language === "javascript") {
+    return [
+      "// npm install @modelcontextprotocol/sdk",
+      "// Runs the server on this machine (Node.js 20.10+). CANLI_LOCAL=1 computes everything locally, no key.",
+      fileNote ? `// ${fileNote}` : null,
+      'import { Client } from "@modelcontextprotocol/sdk/client/index.js";',
+      'import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";',
+      "",
+      'const client = new Client({ name: "example", version: "1.0.0" });',
+      'await client.connect(new StdioClientTransport({ command: "npx", args: ["-y", "canli-validation-mcp"], env: { ...process.env, CANLI_LOCAL: "1" } }));',
+      `const result = await client.callTool({ name: "${tool}", arguments: ${json} });`,
+      "console.log(result.structuredContent);",
+      "await client.close();",
+      "",
+    ].filter((line) => line !== null).join("\n");
+  }
+  if (language === "curl") {
+    if (usesFile(args)) {
+      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`;
+    }
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } });
+    return [
+      "# The hosted endpoint: no install, no key needed for a first call. Tools added since the last",
+      "# release appear here once that release is pinned; locally they are available at once.",
+      "curl -sS https://canlicapital.com/mcp \\",
+      "  -H 'content-type: application/json' \\",
+      "  -H 'accept: application/json, text/event-stream' \\",
+      `  -d '${body.replace(/'/g, "'\\''")}'`,
+      "",
+    ].join("\n");
+  }
+  throw new Error(`No example language ${language}; choose python, javascript or curl`);
+}
+
+export const EXAMPLE_LANGUAGES = Object.freeze(["python", "javascript", "curl"]);
+
+// Every strategy family as a machine-readable spec: its parameters, their bounds and its rule.
+export function strategySpec() {
+  const param = { type: "array", items: { type: "number" }, minItems: 1, maxItems: 60 };
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "backtest_strategy family and grid",
+    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.",
+    oneOf: Object.entries(FAMILIES).map(([family, spec]) => ({
+      title: family,
+      description: spec.describe,
+      type: "object",
+      required: ["family", ...(spec.params.length ? ["grid"] : [])],
+      properties: {
+        family: { const: family },
+        ...(spec.params.length ? { grid: { type: "object", additionalProperties: false, required: spec.params.filter((p) => p !== "skip"), properties: Object.fromEntries(spec.params.map((p) => [p, param])) } } : {}),
+      },
+    })),
+    limits: { max_prices: BACKTEST_LIMITS.max_prices, max_variants: BACKTEST_LIMITS.max_variants, max_parameter_value: BACKTEST_LIMITS.max_parameter_value },
+  };
+}
+
+// catalog: { toolName: { description, inputSchema, outputSchema } } for every tool the server can list.
+export function registerCodeResources(server, session, catalog) {
+  const names = Object.keys(catalog).sort();
+  const complete = (list) => (value) => list.filter((n) => n.startsWith(value ?? ""));
+  server.registerResource(
+    "tool-schema",
+    new ResourceTemplate("canli://schemas/{tool}", { list: undefined, complete: { tool: complete(names) } }),
+    { 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" },
+    (uri, { tool }) => {
+      const entry = catalog[tool];
+      if (!entry) throw new Error(`No tool ${tool}; tools are ${names.join(", ")}`);
+      const body = { tool, description: entry.description, input_schema: z.toJSONSchema(entry.inputSchema, { io: "input" }), output_schema: z.toJSONSchema(entry.outputSchema, { io: "output" }) };
+      return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(body, null, 2) }] };
+    },
+  );
+  server.registerResource(
+    "example",
+    new ResourceTemplate("canli://examples/{language}/{tool}", { list: undefined, complete: { language: complete([...EXAMPLE_LANGUAGES]), tool: complete(names) } }),
+    { title: "A working call, in Python, JavaScript or curl", description: "Runnable client code calling one tool with valid example arguments.", mimeType: "text/plain" },
+    (uri, { language, tool }) => {
+      if (!catalog[tool]) throw new Error(`No tool ${tool}; tools are ${names.join(", ")}`);
+      return { contents: [{ uri: uri.href, mimeType: "text/plain", text: exampleCode(language, tool) }] };
+    },
+  );
+  server.registerResource(
+    "strategy-spec",
+    "canli://strategy-spec",
+    { title: "Strategy families and their parameters", description: "JSON Schema of backtest_strategy's families, parameters and rules.", mimeType: "application/json" },
+    (uri) => ({ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(strategySpec(), null, 2) }] }),
+  );
+  server.registerResource(
+    "openapi",
+    "canli://openapi",
+    { 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" },
+    async (uri) => {
+      const signal = AbortSignal.timeout(session.timeoutMs);
+      let res;
+      try {
+        res = await session.fetchImpl(`${session.base}/api/v1/openapi`, { headers: { Accept: "application/json" }, signal, redirect: "error" });
+      } catch {
+        throw new Error(`canli://openapi: could not reach ${session.base}/api/v1/openapi; it is also published at https://canlicapital.com/api/v1/openapi`);
+      }
+      if (!res.ok) throw new Error(`canli://openapi: ${session.base}/api/v1/openapi returned HTTP ${res.status}`);
+      return { contents: [{ uri: uri.href, mimeType: "application/json", text: await res.text() }] };
+    },
+  );
+}
+
+// Guided workflows for the lab. The prompt only writes the instructions; the tools do the work.
+export function registerLabPrompts(server) {
+  const prompt = (name, title, description, argsSchema, lines) => server.registerPrompt(name, { title, description, argsSchema }, (args) => ({
+    messages: [{ role: "user", content: { type: "text", text: lines(args).filter(Boolean).join("\n") } }],
+  }));
+  prompt(
+    "backtest_and_validate",
+    "Backtest a rule and check whether the best variant is luck",
+    "Run a strategy family over a parameter grid on your prices, then read the deflated Sharpe and overfitting probability that count every variant run.",
+    { 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") },
+    ({ prices_file, family }) => [
+      `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).`,
+      "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.",
+      "Say plainly whether the best variant is distinguishable from luck, and quote the limits sentences the result carries.",
+    ],
+  );
+  prompt(
+    "stress_my_strategy",
+    "How fragile is this strategy?",
+    "Resampled histories and named crash, volatility, repeat and outage scenarios for a strategy's returns.",
+    { 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") },
+    ({ returns_file, drawdown_limit }) => [
+      `Run stress_test on ${returns_file}${drawdown_limit ? ` with drawdown_limit ${drawdown_limit}` : ""}.`,
+      "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.",
+      "Say that these are frequencies under stated rules, not forecasts.",
+    ],
+  );
+  prompt(
+    "production_check",
+    "Will this plan survive a real broker?",
+    "Order-rate and minimum-order limits, 2026 day-trading rules, market impact, crowding and capacity for a trading plan.",
+    { plan: z.string().describe("Capital, broker, how many orders per rebalance, how often, turnover, and what it trades") },
+    ({ plan }) => [
+      `Here is the plan: ${plan}.`,
+      "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.",
+      "List each blocking or warning finding with the change that fixes it, and say when the broker facts were checked.",
+    ],
+  );
+  prompt(
+    "summarize_market_series",
+    "Read a long series in a hundred words",
+    "Summarize a price or return file instead of reading its rows.",
+    { series_file: z.string().describe("Path to a CSV of prices or returns"), kind: z.string().optional().describe("prices or returns; default prices") },
+    ({ series_file, kind }) => [
+      `Call summarize_series on ${series_file} (series_kind ${kind ?? "prices"}) and reason from its text and fields instead of reading the file's rows.`,
+      "Point out anything in the data check (stale prices, jumps) that should be fixed before the series is backtested.",
+    ],
+  );
+}