canli-validation-mcp 0.4.0 → 0.5.0

package/src/local/standards/paper-evidence/schema.json

@@ -0,0 +1,429 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://canlicapital.com/standards/paper-evidence/v0/schema.json",
+  "title": "canli.paper-evidence.v0",
+  "description": "A record of paper-traded or simulated strategy performance that states what it does not know. The schema exists because the failure mode of a performance claim is not a wrong number, it is a number whose basis, cost assumptions, search history and missing evidence are unstated. Every required field below is one of those.",
+  "type": "object",
+  "required": [
+    "schema",
+    "generated_at",
+    "capital",
+    "identity",
+    "period",
+    "returns",
+    "costs",
+    "selection",
+    "risk",
+    "corrections",
+    "provenance",
+    "claim_maturity"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {
+      "const": "canli.paper-evidence.v0"
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "capital": {
+      "type": "object",
+      "description": "What kind of money produced this record. The single most misreadable fact about any track record, so it is required and enumerated rather than described in prose.",
+      "required": [
+        "kind",
+        "execution"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "enum": [
+            "PAPER",
+            "FUNDED",
+            "SIMULATED",
+            "MIXED"
+          ],
+          "description": "PAPER: orders placed at a broker against a paper account. SIMULATED: no broker involved. FUNDED: real capital at risk. MIXED: any combination, which must be decomposed in `notes`."
+        },
+        "execution": {
+          "enum": [
+            "BROKER_PAPER_FILLS",
+            "LOCAL_SIMULATED_FILLS",
+            "BROKER_LIVE_FILLS",
+            "MIXED"
+          ],
+          "description": "Where the fills came from. A broker paper fill and a locally modelled fill are different evidence and may not be merged silently."
+        },
+        "venue": {
+          "type": "string"
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "identity": {
+      "type": "object",
+      "description": "What this record is about, and whether that thing was frozen before the returns were seen.",
+      "required": [
+        "name",
+        "kind",
+        "preregistered"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "SLEEVE",
+            "BOOK",
+            "CANDIDATE"
+          ]
+        },
+        "preregistered": {
+          "type": "boolean",
+          "description": "Whether the strategy identity was frozen before its out-of-sample returns were opened. False is a legitimate answer and is far more useful than an absent field."
+        },
+        "preregistration_ref": {
+          "type": "string"
+        },
+        "constituents": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "period": {
+      "type": "object",
+      "required": [
+        "first_observation",
+        "last_observation",
+        "observation_count",
+        "frequency"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "first_observation": {
+          "type": "string",
+          "format": "date"
+        },
+        "last_observation": {
+          "type": "string",
+          "format": "date"
+        },
+        "observation_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "frequency": {
+          "enum": [
+            "DAILY",
+            "WEEKLY",
+            "MONTHLY",
+            "HOURLY",
+            "IRREGULAR"
+          ]
+        },
+        "calendar": {
+          "type": "string"
+        }
+      }
+    },
+    "returns": {
+      "type": "object",
+      "description": "Return figures, always net-of-what stated. A return series whose cost treatment is unstated is not a measurement.",
+      "required": [
+        "basis",
+        "cumulative",
+        "series_available"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "GROSS",
+            "NET_OF_MODELLED_COSTS",
+            "NET_OF_REALISED_COSTS"
+          ],
+          "description": "NET_OF_REALISED_COSTS requires broker-observed costs, not a model."
+        },
+        "cumulative": {
+          "type": "number"
+        },
+        "annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sharpe_annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "sharpe_reportable": {
+          "type": "boolean",
+          "description": "Whether the sample supports reporting a Sharpe at all. A short record must set this false and leave sharpe_annualised null rather than publishing a figure the sample cannot carry."
+        },
+        "series_available": {
+          "type": "boolean"
+        },
+        "series_url": {
+          "type": "string"
+        }
+      }
+    },
+    "costs": {
+      "type": "object",
+      "description": "What was charged and what was assumed. Absent cost modelling is itself a disclosure.",
+      "required": [
+        "modelled"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "modelled": {
+          "type": "boolean"
+        },
+        "components": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "SPREAD",
+              "FEES",
+              "IMPACT",
+              "LATENCY",
+              "FINANCING",
+              "BORROW",
+              "FUNDING"
+            ]
+          }
+        },
+        "turnover_annualised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "notes": {
+          "type": "string"
+        },
+        "not_modelled": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Cost categories the publisher does NOT charge. Optional in v0 and a candidate to become required in the next version, because a cost model described only by its inclusions is structurally misleading: a reader cannot distinguish a cost judged immaterial from one nobody considered, since both appear as silence. Unmodelled costs almost always flatter, so this list has a known direction."
+        },
+        "coverage_url": {
+          "type": "string"
+        }
+      }
+    },
+    "selection": {
+      "type": "object",
+      "description": "How much searching produced this result. Without it a Sharpe ratio is uninterpretable, which is the single most common defect in published performance.",
+      "required": [
+        "trials_counted",
+        "trial_count",
+        "deflation_applied"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "trials_counted": {
+          "type": "boolean",
+          "description": "Whether the publisher actually maintains a trial ledger. False is honest; an unstated trial count is not."
+        },
+        "trial_count": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "trial_unit": {
+          "type": "string"
+        },
+        "deflation_applied": {
+          "type": "boolean"
+        },
+        "deflated_sharpe_ratio": {
+          "type": [
+            "number",
+            "null"
+          ],
+          "minimum": 0,
+          "maximum": 1
+        },
+        "deflation_method": {
+          "type": "string"
+        }
+      }
+    },
+    "risk": {
+      "type": "object",
+      "required": [
+        "max_drawdown_realised",
+        "drawdown_basis"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "max_drawdown_realised": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "drawdown_basis": {
+          "enum": [
+            "OBSERVED",
+            "MODEL_ESTIMATED",
+            "NOT_ESTABLISHED"
+          ]
+        },
+        "max_drawdown_model_expected": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "exposure_notes": {
+          "type": "string"
+        }
+      }
+    },
+    "corrections": {
+      "type": "object",
+      "description": "Whether anything in this record has been withdrawn. A record with no correction history and no statement that it has none is silent, not clean.",
+      "required": [
+        "count",
+        "withdrawn_figures"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "withdrawn_figures": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "figure",
+              "withdrawn_on",
+              "reason"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "figure": {
+                "type": "string"
+              },
+              "withdrawn_on": {
+                "type": "string",
+                "format": "date"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "superseded_by": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "log_url": {
+          "type": "string"
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "description": "What a reader can check without trusting the publisher.",
+      "required": [
+        "source_bindings",
+        "independently_verifiable"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "source_bindings": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "sha256"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^(sha256:)?[0-9a-f]{64}$"
+              },
+              "url": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "independently_verifiable": {
+          "type": "boolean"
+        },
+        "verification_url": {
+          "type": "string"
+        },
+        "signed": {
+          "type": "boolean"
+        },
+        "signature_scheme": {
+          "type": "string"
+        }
+      }
+    },
+    "claim_maturity": {
+      "type": "object",
+      "description": "What this record does NOT establish. Required, because the omission of this section is what makes an otherwise accurate record misleading.",
+      "required": [
+        "establishes",
+        "does_not_establish"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "establishes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "does_not_establish": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "At least one entry. Every record fails to establish something, and a publisher who cannot name one has not looked."
+        },
+        "external_review_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "independent_replication_count": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  }
+}

package/src/local.mjs

@@ -0,0 +1,39 @@
+// Private local mode: the validators computed on this machine from src/local, a byte-for-byte
+// mirror of the API's own computation (see scripts/sync-local.mjs). Nothing is sent to
+// canlicapital.com and no receipt is stored, so the result names no receipt id.
+import { LIMITS_TEXT } from "./local/api/_lib/limits.js";
+import { compute as breadth } from "./local/js/validate/breadth.js";
+import { compute as deflatedSharpe } from "./local/js/validate/deflated-sharpe.js";
+import { compute as overfitting } from "./local/js/validate/overfitting.js";
+import { compute as paperEvidence } from "./local/js/validate/paper-evidence.js";
+import { compute as trackRecord } from "./local/js/validate/track-record.js";
+
+export const LOCAL_VALIDATORS = Object.freeze({
+  validate_deflated_sharpe: { endpoint: "validate/deflated-sharpe", compute: deflatedSharpe },
+  validate_overfitting: { endpoint: "validate/overfitting", compute: overfitting },
+  validate_paper_evidence: { endpoint: "validate/paper-evidence", compute: paperEvidence },
+  validate_breadth: { endpoint: "validate/breadth", compute: breadth },
+  validate_track_record: { endpoint: "validate/track-record", compute: trackRecord },
+});
+
+const NOTE = "Computed on this machine in local mode. Nothing was sent to canlicapital.com and no receipt was stored.";
+
+export function computeLocally(tool, body, now = () => new Date()) {
+  const validator = LOCAL_VALIDATORS[tool];
+  if (!validator) throw new Error(`${tool} has no local computation`);
+  const base = {
+    schema: "canli.local.v1",
+    endpoint: validator.endpoint,
+    computed: "locally",
+    generated_at: now().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    note: NOTE,
+    limits: LIMITS_TEXT,
+    receipt: null,
+  };
+  try {
+    return { envelope: { ...base, data: validator.compute(body), error: null }, failed: false };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { envelope: { ...base, data: null, error: { code: "invalid_input", message } }, failed: true };
+  }
+}

package/src/schemas.mjs

@@ -127,14 +127,27 @@ export const getReceiptInput = z
 export const emptyInput = z.object({}).strict();
 
 // company_financial_history reads the public company reference, not the validation API.
-export const companyHistoryInput = z
+// 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"),
+    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(),
   })
   .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(),
+  })
+  .strict()
+  .refine((v) => (v.cik === undefined) !== (v.ticker === undefined), "Send exactly one of cik or ticker");
+
 // The company reference carries its own boundary sentence in every record (claim_boundary),
 // written by scripts/lib/company-reference.mjs. A test pins this copy to that source verbatim.
 export const COMPANY_REFERENCE_BOUNDARY = "Public company accounting reference, not market prices, returns, an investment recommendation, or ALPHAC performance. Validate a separately constructed return series with the validation API; accounting values are not returns.";
@@ -163,7 +176,7 @@ export const REGISTRY_DESCRIPTION_MAX = 100;
 // above) what the tool's result cannot be used to claim, so an agent sees this before it ever
 // 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; skipped when CANLI_KEY is already set. ${LIMITS_SENTENCES.quotas}`,
+  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}`,
@@ -171,5 +184,5 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   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}`,
-  company_financial_history: `SEC-reported financial history for one company from the canlicapital.com company reference (GET /company-data/{cik}.json). 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}`,
+  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}`,
 });