canli-validation-mcp 0.5.0 → 0.7.0

package/src/schemas.mjs

@@ -8,6 +8,53 @@
 // validator semantics these shapes mirror.
 import { z } from "zod";
 
+// One description per input field, shared by every shape that uses the field, so a client reads
+// the same meaning, unit and example wherever the field appears. Agents choose arguments from
+// these; a bare "number" leaves units (fraction or percent, kurtosis or excess kurtosis) to guess.
+export const FIELD_DESCRIPTIONS = Object.freeze({
+  observed_sharpe_annualized: "Annualized Sharpe as observed.",
+  observations: "Number of return observations.",
+  periods_per_year: "Observations per year: 252 daily, 365 daily crypto, 52 weekly, 12 monthly.",
+  skew: "Skewness of returns; 0 if Normal.",
+  non_excess_kurtosis: "Kurtosis, not excess kurtosis; 3 if Normal.",
+  effective_independent_trials: "Independent variants tried before choosing this one.",
+  cross_trial_sharpe_sd_annualized: "Standard deviation of the annualized Sharpe across those trials.",
+  returns: "Periodic returns as fractions (0.01 is 1%), oldest first; replaces the Sharpe, observations, skew and kurtosis fields.",
+  matrix: "Returns as fractions: one row per period, one column per variant.",
+  n_splits: "Even number of blocks, at least 2; default 16.",
+  max_combinations: "Most splits evaluated, up to 2000 (default).",
+  seed: "Sampling seed; default 42.",
+  record: "A canli.paper-evidence.v0 record.",
+  sleeve_sharpe: "Annualized Sharpe of one sleeve.",
+  average_pairwise_correlation: "Average correlation between sleeves, -1 to 1.",
+  sleeves: "Sleeve count, to get that book's Sharpe.",
+  target: "Target book Sharpe, to get the sleeves it needs.",
+  benchmark_sharpe_annualized: "Annualized Sharpe to beat; default 0.",
+  confidence: "Between 0 and 1; default 0.95.",
+  record_observations: "Record length so far, to get its probabilistic Sharpe.",
+  label: "Name for the key.",
+  receipt_id: "Receipt id from a validation result.",
+  receipt_object: "A receipt as get_receipt returns it (its data), to verify without fetching it.",
+  cik: "SEC CIK; send cik or ticker.",
+  ticker: "Ticker such as AAPL; send ticker or cik.",
+  concept: "us-gaap concept such as Assets; omit to list them.",
+  limit: "Most observations, newest first; default 40.",
+  target_sharpe_annualized: "In-sample annualized Sharpe you would take as a discovery; default 1.",
+  backtest_years: "Length of the backtest in years, to get the most independent trials it allows.",
+  bt_trials: "Independent trials (backtests, parameter sets, ideas) tried; gives the minimum backtest length.",
+  hc_observations: "Number of return observations behind the Sharpe ratio.",
+  hc_tests: "Total tests run, this one included; gives the Bonferroni and independent-test haircuts.",
+  autocorrelation: "First-order autocorrelation of the returns, -1 to 1; default 0. Corrects the annualized Sharpe as Lo (2002).",
+  other_sharpes: "Annualized Sharpe ratios of the other tests, over the same observations; adds the Holm and BHY haircuts.",
+  lt_trials: "Independent trials tried; adds the chance that the best of them reached this Sharpe by luck.",
+  skew: "Skewness of the returns; below -0.5 the reading warns that the counts are too generous.",
+  variants: "Optional returns of every variant tried, this one included, as fractions: one row per period, one column per variant. Adds the overfitting check.",
+  returns_file: "Path to a CSV or JSON file of the returns on the machine running this server, instead of returns. Not available on the hosted endpoint.",
+  returns_column: "Header name or 1-based position of the returns column when returns_file has several numeric columns.",
+  variants_file: "Path to a CSV or JSON file of every variant's returns (one numeric column per variant), instead of variants.",
+});
+const d = FIELD_DESCRIPTIONS;
+
 // ---------------------------------------------------------------------------------------------
 // validate_deflated_sharpe: the API accepts exactly one of two input modes, never a mix.
 // Input A is the seven fields of deflated_sharpe_calculator_contract.json.
@@ -16,22 +63,22 @@ import { z } from "zod";
 
 export const deflatedSharpeContractInputs = z
   .object({
-    observed_sharpe_annualized: z.number().min(-10).max(10),
-    observations: z.number().int().min(2).max(1000000),
-    periods_per_year: z.number().min(1).max(10000),
-    skew: z.number().min(-20).max(20),
-    non_excess_kurtosis: z.number().min(1).max(100),
-    effective_independent_trials: z.number().int().min(2).max(10000000),
-    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10),
+    observed_sharpe_annualized: z.number().min(-10).max(10).describe(d.observed_sharpe_annualized),
+    observations: z.number().int().min(2).max(1000000).describe(d.observations),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    skew: z.number().min(-20).max(20).describe(d.skew),
+    non_excess_kurtosis: z.number().min(1).max(100).describe(d.non_excess_kurtosis),
+    effective_independent_trials: z.number().int().min(2).max(10000000).describe(d.effective_independent_trials),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).describe(d.cross_trial_sharpe_sd_annualized),
   })
   .strict();
 
 export const deflatedSharpeReturnSeriesInputs = z
   .object({
-    returns: z.array(z.number()).min(2).max(20000),
-    periods_per_year: z.number().min(1).max(10000),
-    effective_independent_trials: z.number().int().min(2).max(10000000),
-    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10),
+    returns: z.array(z.number()).min(2).max(20000).describe(d.returns),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    effective_independent_trials: z.number().int().min(2).max(10000000).describe(d.effective_independent_trials),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).describe(d.cross_trial_sharpe_sd_annualized),
   })
   .strict();
 
@@ -44,14 +91,14 @@ export const deflatedSharpeInput = z.union([deflatedSharpeContractInputs, deflat
 // per-field type checking) while the strict oneOf rule above is enforced in the tool handler.
 export const deflatedSharpeToolShape = z
   .object({
-    observed_sharpe_annualized: z.number().min(-10).max(10).optional(),
-    observations: z.number().int().min(2).max(1000000).optional(),
-    periods_per_year: z.number().min(1).max(10000).optional(),
-    skew: z.number().min(-20).max(20).optional(),
-    non_excess_kurtosis: z.number().min(1).max(100).optional(),
-    effective_independent_trials: z.number().int().min(2).max(10000000).optional(),
-    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).optional(),
-    returns: z.array(z.number()).min(2).max(20000).optional(),
+    observed_sharpe_annualized: z.number().min(-10).max(10).optional().describe(d.observed_sharpe_annualized),
+    observations: z.number().int().min(2).max(1000000).optional().describe(d.observations),
+    periods_per_year: z.number().min(1).max(10000).optional().describe(d.periods_per_year),
+    skew: z.number().min(-20).max(20).optional().describe(d.skew),
+    non_excess_kurtosis: z.number().min(1).max(100).optional().describe(d.non_excess_kurtosis),
+    effective_independent_trials: z.number().int().min(2).max(10000000).optional().describe(d.effective_independent_trials),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).optional().describe(d.cross_trial_sharpe_sd_annualized),
+    returns: z.array(z.number()).min(2).max(20000).optional().describe(d.returns),
   })
   .strict();
 
@@ -61,10 +108,10 @@ export const deflatedSharpeToolShape = z
 
 export const overfittingInput = z
   .object({
-    matrix: z.array(z.array(z.number())).min(2).max(20000),
-    n_splits: z.number().int().positive().optional(),
-    max_combinations: z.number().int().positive().max(2000).optional(),
-    seed: z.number().optional(),
+    matrix: z.array(z.array(z.number())).min(2).max(20000).describe(d.matrix),
+    n_splits: z.number().int().positive().optional().describe(d.n_splits),
+    max_combinations: z.number().int().positive().max(2000).optional().describe(d.max_combinations),
+    seed: z.number().optional().describe(d.seed),
   })
   .strict();
 
@@ -75,7 +122,7 @@ export const overfittingInput = z
 
 export const paperEvidenceInput = z
   .object({
-    record: z.record(z.string(), z.unknown()),
+    record: z.record(z.string(), z.unknown()).describe(d.record),
   })
   .strict();
 
@@ -85,10 +132,10 @@ export const paperEvidenceInput = z
 
 export const breadthInput = z
   .object({
-    sleeve_sharpe: z.number().positive(),
-    average_pairwise_correlation: z.number().min(-1).max(1),
-    sleeves: z.number().int().min(1).max(500).optional(),
-    target: z.number().positive().optional(),
+    sleeve_sharpe: z.number().positive().describe(d.sleeve_sharpe),
+    average_pairwise_correlation: z.number().min(-1).max(1).describe(d.average_pairwise_correlation),
+    sleeves: z.number().int().min(1).max(500).optional().describe(d.sleeves),
+    target: z.number().positive().optional().describe(d.target),
   })
   .strict();
 
@@ -98,52 +145,131 @@ export const breadthInput = z
 
 export const trackRecordInput = z
   .object({
-    observed_sharpe_annualized: z.number().min(-10).max(10),
-    periods_per_year: z.number().min(1).max(10000),
-    skew: z.number().min(-20).max(20),
-    non_excess_kurtosis: z.number().min(1).max(100),
-    benchmark_sharpe_annualized: z.number().min(-10).max(10).optional(),
-    confidence: z.number().gt(0).lt(1).optional(),
-    observations: z.number().int().min(2).max(1000000).optional(),
+    observed_sharpe_annualized: z.number().min(-10).max(10).describe(d.observed_sharpe_annualized),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    skew: z.number().min(-20).max(20).describe(d.skew),
+    non_excess_kurtosis: z.number().min(1).max(100).describe(d.non_excess_kurtosis),
+    benchmark_sharpe_annualized: z.number().min(-10).max(10).optional().describe(d.benchmark_sharpe_annualized),
+    confidence: z.number().gt(0).lt(1).optional().describe(d.confidence),
+    observations: z.number().int().min(2).max(1000000).optional().describe(d.record_observations),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// validate_backtest_length
+// ---------------------------------------------------------------------------------------------
+
+export const backtestLengthInput = z
+  .object({
+    effective_independent_trials: z.number().int().min(2).max(1000000000).optional().describe(d.bt_trials),
+    backtest_years: z.number().gt(0).max(1000).optional().describe(d.backtest_years),
+    target_sharpe_annualized: z.number().gt(0).max(10).optional().describe(d.target_sharpe_annualized),
   })
   .strict();
 
+// ---------------------------------------------------------------------------------------------
+// validate_haircut_sharpe
+// ---------------------------------------------------------------------------------------------
+
+export const haircutSharpeInput = z
+  .object({
+    observed_sharpe_annualized: z.number().gt(0).max(10).describe(d.observed_sharpe_annualized),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    observations: z.number().int().min(3).max(1000000).describe(d.hc_observations),
+    tests: z.number().int().min(1).max(100000000).optional().describe(d.hc_tests),
+    autocorrelation: z.number().gt(-1).lt(1).optional().describe(d.autocorrelation),
+    other_sharpe_ratios_annualized: z.array(z.number().min(-10).max(10)).min(1).max(10000).optional().describe(d.other_sharpes),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// validate_luck_trials
+// ---------------------------------------------------------------------------------------------
+
+export const luckTrialsInput = z
+  .object({
+    observed_sharpe_annualized: z.number().min(-20).max(20).describe(d.observed_sharpe_annualized),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    observations: z.number().int().min(3).max(1000000).describe(d.hc_observations),
+    effective_independent_trials: z.number().int().min(1).max(1000000000).optional().describe(d.lt_trials),
+    skew: z.number().min(-100).max(100).optional().describe(d.skew),
+    autocorrelation: z.number().gt(-1).lt(1).optional().describe(d.autocorrelation),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------------------------
+// audit_backtest: the deflated Sharpe, track record and (with variants) overfitting checks on one
+// return series in one call. Each check runs through its own validator, unchanged.
+// ---------------------------------------------------------------------------------------------
+
+export const auditBacktestToolShape = z
+  .object({
+    returns: z.array(z.number()).min(2).max(20000).optional().describe(d.returns),
+    returns_file: z.string().min(1).max(4096).optional().describe(d.returns_file),
+    returns_column: z.union([z.string().min(1).max(200), z.number().int().min(1)]).optional().describe(d.returns_column),
+    periods_per_year: z.number().min(1).max(10000).describe(d.periods_per_year),
+    effective_independent_trials: z.number().int().min(2).max(10000000).describe(d.effective_independent_trials),
+    cross_trial_sharpe_sd_annualized: z.number().min(0).max(10).describe(d.cross_trial_sharpe_sd_annualized),
+    benchmark_sharpe_annualized: z.number().min(-10).max(10).optional().describe(d.benchmark_sharpe_annualized),
+    confidence: z.number().gt(0).lt(1).optional().describe(d.confidence),
+    variants: z.array(z.array(z.number())).min(2).max(20000).optional().describe(d.variants),
+    variants_file: z.string().min(1).max(4096).optional().describe(d.variants_file),
+    n_splits: z.number().int().positive().optional().describe(d.n_splits),
+  })
+  .strict();
+
+// The handler's rule on top of the advertised shape: the returns come from exactly one place, the
+// variants from at most one, and a column is named only for a file.
+export const auditBacktestInput = auditBacktestToolShape
+  .refine((v) => (v.returns === undefined) !== (v.returns_file === undefined), "Send exactly one of returns or returns_file")
+  .refine((v) => v.variants === undefined || v.variants_file === undefined, "Send variants or variants_file, not both")
+  .refine((v) => v.returns_column === undefined || v.returns_file !== undefined, "returns_column applies only to returns_file");
+
 // ---------------------------------------------------------------------------------------------
 // get_key / get_receipt
 // ---------------------------------------------------------------------------------------------
 
 export const getKeyInput = z
   .object({
-    label: z.string().max(64).optional(),
+    label: z.string().max(64).optional().describe(d.label),
   })
   .strict();
 
 export const getReceiptInput = z
   .object({
-    id: z.string().regex(/^[0-9a-f]{24}$/, "A receipt id is 24 hex characters"),
+    id: z.string().regex(/^[0-9a-f]{24}$/, "A receipt id is 24 hex characters").describe(d.receipt_id),
   })
   .strict();
 
 export const emptyInput = z.object({}).strict();
 
+// verify_receipt: a receipt id to fetch, or a receipt already fetched (get_receipt's data), to check
+// offline. Advertised flat; the handler enforces exactly one.
+export const verifyReceiptToolShape = z
+  .object({
+    id: z.string().regex(/^[0-9a-f]{24}$/, "A receipt id is 24 hex characters").optional().describe(d.receipt_id),
+    receipt: z.record(z.string(), z.unknown()).optional().describe(d.receipt_object),
+  })
+  .strict();
+
 // company_financial_history reads the public company reference, not the validation API.
 // Advertised to clients as a flat object (a refinement has no useful JSON Schema); the handler
 // enforces the exactly-one-of rule with companyHistoryInput.
 export const companyHistoryToolShape = z
   .object({
-    cik: z.string().regex(/^\d{1,10}$/, "A CIK is 1 to 10 digits").optional(),
-    ticker: z.string().regex(/^[A-Za-z0-9.\-]{1,10}$/, "A ticker is 1 to 10 letters, digits, dots or hyphens").optional(),
-    concept: z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,99}$/, "A concept is a us-gaap tag such as Revenues or Assets").optional(),
-    limit: z.number().int().min(1).max(200).optional(),
+    cik: z.string().regex(/^\d{1,10}$/, "A CIK is 1 to 10 digits").optional().describe(d.cik),
+    ticker: z.string().regex(/^[A-Za-z0-9.\-]{1,10}$/, "A ticker is 1 to 10 letters, digits, dots or hyphens").optional().describe(d.ticker),
+    concept: z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,99}$/, "A concept is a us-gaap tag such as Revenues or Assets").optional().describe(d.concept),
+    limit: z.number().int().min(1).max(200).optional().describe(d.limit),
   })
   .strict();
 
 export const companyHistoryInput = z
   .object({
-    cik: z.string().regex(/^\d{1,10}$/, "A CIK is 1 to 10 digits").optional(),
-    ticker: z.string().regex(/^[A-Za-z0-9.\-]{1,10}$/, "A ticker is 1 to 10 letters, digits, dots or hyphens").optional(),
-    concept: z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,99}$/, "A concept is a us-gaap tag such as Revenues or Assets").optional(),
-    limit: z.number().int().min(1).max(200).optional(),
+    cik: z.string().regex(/^\d{1,10}$/, "A CIK is 1 to 10 digits").optional().describe(d.cik),
+    ticker: z.string().regex(/^[A-Za-z0-9.\-]{1,10}$/, "A ticker is 1 to 10 letters, digits, dots or hyphens").optional().describe(d.ticker),
+    concept: z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,99}$/, "A concept is a us-gaap tag such as Revenues or Assets").optional().describe(d.concept),
+    limit: z.number().int().min(1).max(200).optional().describe(d.limit),
   })
   .strict()
   .refine((v) => (v.cik === undefined) !== (v.ticker === undefined), "Send exactly one of cik or ticker");
@@ -161,7 +287,7 @@ export const COMPANY_REFERENCE_BOUNDARY = "Public company accounting reference,
 export const LIMITS_SENTENCES = Object.freeze({
   scope: "This verdict is about the series exactly as submitted. The service never saw the data source, its costs, survivorship, or any lookahead in how the series was built.",
   notAdmission: "A deflated Sharpe or overfitting probability above or below any threshold is not admission to anything and is not a forecast.",
-  unsigned: "The receipt is content-hashed and reproducible from the open-source core it names. It is not signed.",
+  unsigned: "The receipt is content-hashed, reproducible from the open-source core it names, and signed with Ed25519 by a key published at https://canlicapital.com/.well-known/canli-receipt-keys.json.",
   quotas: "Quotas: 1000 validations per key per UTC day, 5 keys per client per UTC day, 1048576 bytes per validation request, 1024 bytes per key revocation request, 20000 observations per series, 200 variants per matrix.",
 });
 
@@ -177,12 +303,17 @@ export const REGISTRY_DESCRIPTION_MAX = 100;
 // calls the tool, not only inside the returned envelope.
 export const TOOL_DESCRIPTIONS = Object.freeze({
   get_key: `Issue a free canlicapital.com validation key (POST /api/v1/keys) and hold it in memory for this session. Only needed before a validation when neither CANLI_KEY nor local mode is set; the read tools (get_receipt, service_status, company_financial_history) never need a key. ${LIMITS_SENTENCES.quotas}`,
-  validate_deflated_sharpe: `Probabilistic and deflated Sharpe from the seven contract inputs, or from a return series plus the trials and dispersion behind it, never both. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_overfitting: `Probability of backtest overfitting by CSCV over the returns of every variant tried. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_paper_evidence: `Conformance of a performance record against the canli.paper-evidence.v0 standard. ${LIMITS_SENTENCES.scope}`,
-  validate_track_record: `Minimum track record length for an observed Sharpe to clear a benchmark Sharpe (default 0) at a confidence level (default 0.95), and, when observations is sent, the probabilistic Sharpe of that record against the benchmark. ${LIMITS_SENTENCES.notAdmission}`,
-  validate_breadth: `Book Sharpe ceiling from per-sleeve quality and average pairwise correlation, and the sleeves a target needs. ${LIMITS_SENTENCES.scope}`,
-  get_receipt: `Fetch a stored verdict by its content-hash id (GET /api/v1/receipts/{id}), immutable and cacheable. ${LIMITS_SENTENCES.unsigned}`,
-  service_status: `Service, store and quota constants for the validation API (GET /api/v1/validate/status); no key required. ${LIMITS_SENTENCES.scope}`,
+  validate_deflated_sharpe: `Whether a Sharpe survives the number of variants tried: probabilistic and deflated Sharpe (0 to 1) and the Sharpe luck alone would reach. Send the seven statistics or a return series, not both. ${LIMITS_SENTENCES.notAdmission}`,
+  audit_backtest: `Audit one strategy's return series in one call: deflated Sharpe, the minimum track record length for its Sharpe to beat the benchmark, and, with every variant's returns, the probability of backtest overfitting. Point returns_file at the backtest's CSV or JSON rather than copying long series into the call. Each check is the matching validate_ tool's result with its own receipt, side by side; the audit does not grade the strategy. Uses one validation per check. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_overfitting: `Probability (0 to 1) that picking the best of several backtested variants was overfitting, by CSCV over every variant's returns. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_paper_evidence: `Whether a paper or simulated performance record meets canli.paper-evidence.v0, with each failure's JSON pointer. ${LIMITS_SENTENCES.scope}`,
+  validate_backtest_length: `Minimum backtest length, in years, before the best of N independent trials is not expected to reach a target Sharpe by luck, and with backtest_years, the most independent trials those years allow. Send effective_independent_trials, backtest_years, or both. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_luck_trials: `How many skill-less strategies a search would have had to try for its best to reach this Sharpe by luck, and, with a trial count, the chance that it did. Calibrated by Monte Carlo. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_haircut_sharpe: `Haircut Sharpe ratio for multiple testing (Harvey and Liu, 2015): the Sharpe a single test would have needed once the number of tests is counted, by Bonferroni and for independent tests, and with the other tests' Sharpe ratios by Holm and BHY. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_track_record: `Minimum track record length, in observations and years, for an observed Sharpe to beat a benchmark at a confidence level, and with observations, the record's probabilistic Sharpe so far. ${LIMITS_SENTENCES.notAdmission}`,
+  validate_breadth: `Highest book Sharpe reachable by adding sleeves of this quality and correlation, the Sharpe at a sleeve count, and the sleeves a target needs. ${LIMITS_SENTENCES.scope}`,
+  verify_receipt: `Check a validation receipt's Ed25519 signature offline against the canlicapital.com public key bundled in this package, that its output hashes to its output_sha256, and that its content hashes to its id. Send an id to fetch the receipt first, or a receipt already fetched. ${LIMITS_SENTENCES.unsigned}`,
+  get_receipt: `Fetch a stored verdict by receipt id (GET /api/v1/receipts/{id}) to re-check an earlier result. No key. ${LIMITS_SENTENCES.unsigned}`,
+  service_status: `Whether the validation API is up, with quota constants (GET /api/v1/validate/status); check after a timeout before resubmitting. No key. ${LIMITS_SENTENCES.scope}`,
   company_financial_history: `SEC-reported financial history for one company from the canlicapital.com company reference (GET /company-data/{cik}.json), by cik or by ticker (resolved through GET /api/v1/company-tickers.json, companies in the release only). Without a concept it lists the available histories; with one it returns observations, newest first, each with its filing accession, form, filed date and unit, plus the SHA-256 of the original SEC response. No key required. ${COMPANY_REFERENCE_BOUNDARY}`,
 });

package/src/series-file.mjs

@@ -0,0 +1,124 @@
+// mcp/src/series-file.mjs
+//
+// Reads a return series, or a matrix of variant returns, from a file on the machine the server runs
+// on, so an agent can point a tool at its backtest output instead of copying hundreds of numbers
+// into the call (the agent benchmark measured transcription errors on long pasted series).
+//
+// Only numbers leave this module. Error messages name rows and columns by position, never by a
+// cell's content or a header's text, so a path pointed at the wrong file cannot echo that file back
+// into the conversation. The hosted endpoint never reads files (see toolAuditBacktest).
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const MAX_SERIES_FILE_BYTES = 5 * 1024 * 1024;
+
+// One open file descriptor for the check and the read, so the file checked is the file read: a
+// path swapped between a separate stat and read could otherwise pass the size and type checks as
+// one file and be read as another. The read stops one byte past the cap, whatever the file grows to.
+function readText(path) {
+  let fd;
+  try {
+    fd = openSync(resolve(path), "r");
+  } catch {
+    throw new Error(`${path}: no such file`);
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error(`${path}: not a regular file`);
+    if (stat.size > MAX_SERIES_FILE_BYTES) throw new Error(`${path}: larger than ${MAX_SERIES_FILE_BYTES} bytes`);
+    const buffer = Buffer.alloc(MAX_SERIES_FILE_BYTES + 1);
+    let length = 0;
+    for (;;) {
+      const read = readSync(fd, buffer, length, buffer.length - length, null);
+      if (read === 0) break;
+      length += read;
+      if (length > MAX_SERIES_FILE_BYTES) throw new Error(`${path}: larger than ${MAX_SERIES_FILE_BYTES} bytes`);
+    }
+    return buffer.toString("utf8", 0, length);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+const isNumber = (cell) => cell.trim() !== "" && Number.isFinite(Number(cell.trim()));
+
+// A JSON array (of numbers, or of arrays of numbers), or delimited text: comma, semicolon or tab
+// separated, one row per line, with an optional header row naming the columns.
+function parseTable(text, path) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("[")) {
+    let value;
+    try {
+      value = JSON.parse(trimmed);
+    } catch {
+      throw new Error(`${path}: starts like JSON but does not parse as JSON`);
+    }
+    if (!Array.isArray(value)) throw new Error(`${path}: JSON must be an array`);
+    const rows = value.map((row) => (Array.isArray(row) ? row : [row]));
+    rows.forEach((row, i) => row.forEach((cell, j) => {
+      if (typeof cell !== "number" || !Number.isFinite(cell)) throw new Error(`${path}: JSON item ${i + 1}, position ${j + 1} is not a finite number`);
+    }));
+    return { header: null, rows };
+  }
+  const lines = trimmed.split(/\r?\n/).filter((line) => line.trim() !== "");
+  if (!lines.length) throw new Error(`${path}: empty`);
+  const delimiter = [",", ";", "\t"].find((d) => lines[0].includes(d)) ?? ",";
+  const split = (line) => line.split(delimiter).map((cell) => cell.trim());
+  const first = split(lines[0]);
+  const header = first.some((cell) => !isNumber(cell)) ? first : null;
+  const body = header ? lines.slice(1) : lines;
+  const width = (header ?? first).length;
+  const rows = body.map((line, i) => {
+    const cells = split(line);
+    if (cells.length !== width) throw new Error(`${path}: row ${i + 1 + (header ? 1 : 0)} has ${cells.length} cells, expected ${width}`);
+    return cells;
+  });
+  return { header, rows };
+}
+
+// A row counter, such as the unnamed index pandas writes first: an empty header, or whole numbers
+// that step by exactly one. No return series looks like that, so it is skipped, and the caller
+// reports the skip rather than hiding it.
+function isRowCounter(name, values) {
+  if (name === "") return true;
+  return values.length >= 3 && values.every((v, i) => Number.isInteger(v) && (i === 0 || v - values[i - 1] === 1));
+}
+
+// Numeric columns only: a date or label column is dropped, never parsed; a row counter is skipped.
+function numericColumns({ header, rows }) {
+  const width = rows[0]?.length ?? 0;
+  const columns = [];
+  const skipped = [];
+  for (let j = 0; j < width; j += 1) {
+    if (rows.every((row) => typeof row[j] === "number" || isNumber(String(row[j])))) {
+      const values = rows.map((row) => Number(row[j]));
+      if (isRowCounter(header ? header[j] : null, values)) skipped.push(j + 1);
+      else columns.push({ index: j, name: header ? header[j] : String(j + 1), values });
+    }
+  }
+  return { columns, skipped };
+}
+
+// One series. With several numeric columns, `column` (a header name or a 1-based index) picks it.
+// Returns the values and the positions of any row-counter columns skipped.
+export function readSeriesFile(path, column) {
+  const table = parseTable(readText(path), path);
+  if (!table.rows.length) throw new Error(`${path}: no data rows`);
+  const { columns, skipped } = numericColumns(table);
+  if (!columns.length) throw new Error(`${path}: no column holds only numbers`);
+  if (column === undefined) {
+    if (columns.length > 1) throw new Error(`${path}: ${columns.length} numeric columns (positions ${columns.map((c) => c.index + 1).join(", ")}); pick one with returns_column, by header name or position`);
+    return { values: columns[0].values, skipped };
+  }
+  const picked = columns.find((c) => c.name === String(column)) ?? columns.find((c) => String(c.index + 1) === String(column));
+  if (!picked) throw new Error(`${path}: returns_column matches no numeric column; numeric columns are at positions ${columns.map((c) => c.index + 1).join(", ")}`);
+  return { values: picked.values, skipped };
+}
+
+// Every numeric column is one variant; rows are periods.
+export function readMatrixFile(path) {
+  const table = parseTable(readText(path), path);
+  const { columns, skipped } = numericColumns(table);
+  if (columns.length < 2) throw new Error(`${path}: needs at least 2 numeric columns, one per variant`);
+  return { matrix: table.rows.map((_, i) => columns.map((c) => c.values[i])), skipped };
+}