@easyeyes/threshold-engine

Dated, immutable releases of the EasyEyes threshold compiler, exposed through the frozen engine.compile() contract (ADR 0001, byte-exact copy in contract/engine-compile.ts).

Release #1 is a behavior-neutral snapshot of current production: given the same experiment table and resources, its compiled output is byte-identical to what the production compiler (threshold preprocess/*, driven by the threshold-scientist shell) commits to an experiment repo.

Staging publishes use the @easyeyes-stage scope; the production release is published once under @easyeyes after verification.

Usage

const engine = await import(
  "https://cdn.jsdelivr.net/npm/@easyeyes-stage/[email protected]"
);
engine.contractVersion; // 1 — shell must refuse versions above what it knows
const { files, manifest } = await engine.compile(table, resources, options);

• table — { path, content }, the experiment .csv/.xlsx as opaque bytes.
• resources.files — resource files, kind = path prefix ("fonts/…", "phrases/…", …). resources.fetch/list cover mid-compile lookups.
• options.mode — "web" (default) or "node".
• options.data.glossary / options.data.phrases — required: the release-pinned parameter glossary and i18n phrases (today the shell fetches these from the Netlify functions and passes them through).
• options.data.compilerUpdateDate — optional; the shell-fetched Netlify deploy date baked into CompatibilityRequirements.txt (the engine cannot know it; production fetches it at publish time).

files is the compiled-data file set (root table, conditions/*, CompatibilityRequirements.txt, Duration.txt, js/experimentLanguage.js, typekit.json when Adobe fonts are used). manifest carries requests (resources to copy into the repo), diagnostics (author errors/warnings; any kind: "error" blocks publishing), and experiment (engine-computed configuration the shell reads).

Deliberately not emitted by compile() (shell-side, post-compile): recruitmentServiceConfig.csv and ProlificStudyId.txt are written at study creation with shell-held credentials; the runtime bundle files are copied by the shell. Prolific participant-group validation also stays shell-side (ADR 0001) — the shell appends those diagnostics itself.

Building and verifying

npm install
npm run verify   # build + contract copy check + node parity + browser test
npm run check:types  # public surface typechecks against the frozen contract

• npm run parity — drives the production compiler (bundled unmodified as a "parity oracle") and this package side by side over every table in ../examples/tables/, comparing the compiled file set byte-for-byte plus diagnostics and experiment config. Requires ../tests/__cache__/ glossary.json and phrases.json (fetched from the live Netlify functions on first use).
• npm run parity:browser — serves a scratch page, dynamically imports the built bundle in headless Chrome, asserts the import itself makes no network requests, and runs a web-mode compile.

Publishing

npm run verify
npm pack             # inspect the tarball
npm publish --access public

Versions are calendar dates as semver (2026.7.7). Published versions are immutable: never unpublish; a bad release is superseded by the next date and npm deprecated.