Mary's Lab

A computational color science laboratory. She knows everything about color. She has never seen it.

maryslab-nu.vercel.app · run the conformance suite in your browser

Named for Frank Jackson's thought experiment: Mary, the scientist who knows every physical fact about color but has only ever seen black and white. This lab works the way Mary does. Color arrives as spectra, matrices, and proofs, and the instruments built here do things the field's tooling has not done before.

What lives here

39 MCP tools any AI agent can call, over three engines that must agree: a TypeScript reference engine, a C++20 core behind a stable C ABI, and a WebAssembly build of that core — held together by 401 shared golden vectors and a metamorphic relation suite that runs against all of them. You can run those vectors yourself, in your browser.

The interesting tools are the ones without precedent as software. Every existing color tool is forward and point-wise: spectrum in, number out. These work the other three directions:

Plus a correctness suite (crosscheck_color_implementations, generate_conformance_vectors) that metamorphically tests any color library against algebraic identities. It found a real bug in this repo's own engine on its first run.

Related MCP server: BWVI

Quick start

git clone https://github.com/JeetuSK0808/maryslab
cd maryslab && npm install
cd mcp && npm test && npm run build
claude mcp add maryslab -- node "$(pwd)/dist/server.js"

Then ask your agent to certify a palette, design a spectrum, or audit a colormap. Full tool reference: docs/mcp-tools.md.

Architecture

flowchart LR
    A[AI agents\nClaude Code, any MCP client] -->|MCP stdio| B[mcp/\nTypeScript server\n39 tools, zod schemas]
    B --> C[TS reference engine\nmcp/src/engine]
    B -.->|when built| D[core/\nC++20 engine\nstable C ABI]
    C <-->|401 golden vectors\n+ metamorphic relations| D
    D -->|emscripten| G[bindings/wasm\nbrowser engine]
    C <-->|same 401 vectors| G
    E[data/\ningestion, quality gates] --> B
    F[web/\nAstro site] --> G

The engines are not allowed to drift. core/tests/golden/vectors/conformance.csv is generated from the TypeScript engine, checked by the C++ test suite, and checked again by the WebAssembly build (bindings/wasm/test/parity.mjs, gated in wasm-ci) — 401/401 in all three, at the float32 tolerance floor the C ABI's storage implies. The same metamorphic relations (round trips, metric axioms, white-point preservation, spectral linearity) run against both native engines.

194 TS tests, 94 native tests, 27 data tests, all green. The native suite also runs clean under ASan+UBSan (halt_on_error=1). Measured statement coverage on the MCP package is 93.11%. A schema-driven fuzzer (mcp/test/fuzz/fuzz.mjs, ~15k generated inputs across six seeds) finds no undeclared throws and no non-finite outputs, and fails the run if any tool executes zero valid inputs — nine tools were once silently starved while the summary still read "0 findings". The N-API addon is built against the core and parity-tested in CI (bindings-ci); the MCP server itself serves the reference engine (engine_backend: reference-ts in every response).

The honesty rules

This lab's differentiator is that caveats travel with results.

• CVD compensation remaps for discriminability. It never claims to restore what dichromacy removed.

• Isotope matches and forensic scores are decision support, never authoritative identification. The forensics tool states in its own output that it was calibrated on synthetic negatives.

• Infeasible constraints fail loudly with the achieved bound, never silently relaxed.

• Certificates report when their own grid is too coarse to certify anything (grid_sufficient: false) instead of printing a hollow zero.

• Fourteen technical reports (TR-01 – TR-14) are released as preprints: not peer-reviewed and not posted to a repository. Seven now carry a section evaluated against snapshot usgs-splib07a-1 — 1,752 public-domain USGS reflectance spectra — and the rest are synthetic-only; each report says which of its numbers are which. The measured results frequently contradict the synthetic ones and are published anyway: the provenance detector of TR-13 cannot separate real published spectra from an analytic model, TR-12's classifier falls from 5/5 to 0.66, and TR-01 certifies 0 of 40 measured palettes. Nothing here cites a publication that does not exist. See docs/PRD.md §5 for the ideas we cut because the math did not hold.

Repository map

Contributing

The highest-value contribution is a dataset source adapter with a verified license (see docs/dataset.md). Ground rules in CONTRIBUTING.md: conventional commits, coverage stays at 80 percent, golden vectors change only through a golden-update PR, and scientific claims cite their sources.

License

Code: Apache-2.0. Dataset records carry per-source licenses, tracked in data/catalogs/sources.yaml.