maryslab
by JeetuSK0808
README.md
<div align="center">
<img src="docs/assets/logo.svg" width="110" alt="Mary's Lab: an outlined eye whose iris is the only color" />
# Mary's Lab
**A computational color science laboratory.**
She knows everything about color. She has never seen it.
[](https://github.com/JeetuSK0808/maryslab/actions/workflows/mcp-ci.yml)
[](https://github.com/JeetuSK0808/maryslab/actions/workflows/core-ci.yml)
[](https://github.com/JeetuSK0808/maryslab/actions/workflows/wasm-ci.yml)
[](https://github.com/JeetuSK0808/maryslab/actions/workflows/data-ci.yml)
[](LICENSE)
**[maryslab-nu.vercel.app](https://maryslab-nu.vercel.app)** ·
**[run the conformance suite in your browser](https://maryslab-nu.vercel.app/verify/)**
</div>
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](https://maryslab-nu.vercel.app/verify/).
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:
| Instrument | What it does that nothing else does |
|---|---|
| `certify_illuminant_robustness` | Guaranteed lower bound on palette discriminability over an entire convex family of illuminants, not a spot check |
| `design_spectral_palette` | Designs reflectance *spectra* (not colors) whose separation survives observers and illuminants jointly |
| `design_discrimination_test` | Computes optimal color-vision test stimuli; plates have been built by trial and error for a century |
| `synthesize_adversarial_illuminant` | Finds the physically realizable light that breaks a palette; the attack to the certificate's defense |
| `audit_colormap_topology` | Persistent-homology certificate of the features a colormap invents or destroys, per observer, CVD included |
| `sample_metamers` + `map_metamer_stratification` | Walks the convex metamer set and maps where its combinatorial structure changes across color space |
| `audit_spectrum_provenance` | Measurement forensics: is this spectrum measured, or interpolated and passed off as measured? |
| `generate_metamer_benchmark` | Physically realizable confusion pairs: identical under one light, split under another |
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.
<div align="center">
<img src="docs/assets/metamer-atlas.svg" width="30%" alt="Many metameric reflectance curves collapsing to a single color swatch" />
<img src="docs/assets/design-discrimination-test.svg" width="30%" alt="Ishihara-style dot field generated from engine-computed confusable pair" />
<img src="docs/assets/audit-colormap-topology.svg" width="30%" alt="Lightness profiles and colormap strips for viridis and jet" />
<br/>
<sub>Every figure in this repo and on the site is generated by the instruments themselves. No stock art.</sub>
</div>
## Quick start
```bash
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](docs/mcp-tools.md).
## Architecture
```mermaid
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](docs/PRD.md) §5 for the ideas we cut because the math did not
hold.
## Repository map
| Path | What | Verify with |
|---|---|---|
| `mcp/` | MCP server + TS reference engine | `cd mcp && npm test` |
| `core/` | C++20 engine, C ABI in `include/mary/mary.h` | `cmake --preset release && ctest --preset release` |
| `data/` | Spectral ingestion pipeline, quality gates Q1-Q6 | `cd data && uv run pytest` |
| `web/` | The lab's website (Astro) | `cd web && npm run build` |
| `bindings/` | node N-API, WASM, Python scaffolds | builds in CI |
| `papers/` | 14 technical reports + the runner that produces every figure | `node papers/build/experiments.mjs && node papers/build/render.mjs` |
| `docs/` | PRD, architecture, tool reference, ABI rules | start at `docs/PRD.md` |
## Contributing
The highest-value contribution is a dataset source adapter with a verified
license (see [docs/dataset.md](docs/dataset.md)). Ground rules in
[CONTRIBUTING.md](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`.