tinydecide 0.1.0 → 0.1.2

package/README.md

@@ -16,21 +16,21 @@ const classify = shadow('support', (text) => api.classify(text));
 await classify('my card was charged twice'); // the same answer your API gives
 ```
 
-That is the whole integration. On day one every call still goes to your API. After 2,000 answers TinyDecide compiles a small local model and certifies how far to trust it. From then on, calls it is sure about are answered in about 10 µs, and the rest still go to your API.
+On day one every call still goes to your API. After 2,000 answers TinyDecide compiles a small local model and certifies how far to trust it. From then on, calls it is sure about are answered in about 10 µs, and the rest still go to your API.
 
 ```sh
-npx tinydecide try    # 15 seconds, no API key: watch it learn, take over, and catch an API change
+npx tinydecide try    # 15 seconds, no API key: TinyDecide learns a simulated API, which then changes
 ```
 
 Wrapping an LLM classifier is the common case. [`examples/llm-classifier.js`](examples/llm-classifier.js) does it for any OpenAI-compatible endpoint, defaulting to an open-weights model.
 
 ## What you can count on
 
-1. **Your API stays the reference.** Local answers agree with your API at least 98% of the time overall, certified at 95% confidence on traffic like the traffic it learned from. You set the target.
+1. **Your API stays the reference.** Across all calls, the answers you get agree with your API at least 98% of the time, counting your API's own answers as agreeing. This is certified at 95% confidence on traffic like the traffic it learned from. You set the target. With `compile: { guarantee: 'local' }`, the local answers alone meet it too.
 2. **A call never fails because of TinyDecide.** If anything inside it throws (the model, the disk, your custom hooks), the call goes to your API.
 3. **API changes are caught.** A small random sample of local answers is re-checked against your API, and calls your API answers anyway are checked for free. When your API's answers move, every call goes back to it until a model trained on the new answers certifies. Replaying 221,636 real recorded calls produced no false alarms.
 4. **Restarts resume.** In Node, a named decision keeps its answers, model and state in `.tinydecide/<name>/`.
-5. **Your server never stalls.** Compiles run in a worker thread; the worst pause on the event loop during one is about 3 ms.
+5. **Training runs off the main thread.** Compiles train in a worker thread. Two steps still pause the main thread: reading the answer log at the start of each compile, and trimming the log once every 25,000 answers. On an M3 Pro each takes about 45 ms with 100,000 short answers, and about 0.6 s when inputs are 2,000 characters long.
 6. **It says when it is not worth it.** Some decisions are beyond a word-level model. TinyDecide tells you and keeps calling your API.
 
 No dependencies. Node 22+, Bun, browsers, workers and edge runtimes; 12 KB gzipped in a browser bundle.
@@ -60,9 +60,9 @@ It recompiles each time the answers double, and at least every 20,000 answers. I
 - a string: `'billing'`
 - an object with `label`, `choice`, `decision` or `answer`, plus optional `probs` (a label → probability map, or an array in `labels` order). Probabilities help: the model learns from how sure your API was.
 
-Local answers come back in the same shape: a string for a string, or an object with the label under the same key, plus `probs` and `confidence` if your API returns them. Other fields of your API's response are not reproduced. For anything else, pass `choice: (response) => ({ choice, probs })` to read it and `respond: (decision) => …` to build local answers.
+Local answers come back in the same shape: a string for a string, or an object with the label under the same key, plus `probs` and `confidence` if your API returns them. Other fields of your API's response are not reproduced. For anything else, pass `choice: (response) => label` (or `{ choice, probs }`) to read it and `respond: (decision) => …` to build local answers.
 
-The input can be a string, `{ a, b }` for a pair, or an object with `text` (or `state`, or `input`); other fields are ignored by the model but logged with the answer.
+The input can be a string, `{ a, b }` for a pair, or an object with a string `state`, `text`, `input`, `content` or `message`. The model reads the first of those it finds, or every field when there is none. The whole input is logged with the answer.
 
 ## Options
 
@@ -81,17 +81,17 @@ shadow('support', api, {
 | `delta` | `0.05` | 1 − confidence of the certificate |
 | `audit` | `0.02` | Share of calls your API also answers in the background, to check agreement live |
 | `group` | none | Keeps related calls in one split, so the certificate covers new conversations, not just new messages |
-| `labels` | inferred | Fixes the label set and order. Needed when your API returns indexes or probability arrays |
+| `labels` | inferred | Fixes the label set and order. Needed when your API returns probability arrays; also names index labels |
 | `fallback` | `false` | Answer locally when your API throws |
 | `log` | `true` | One line per lifecycle event. `false`, or a function to route it |
-| `onEvent` | none | Every event as an object: `start`, `compile`, `install`, `guard`, `discard`, `audit`, `unreadable`, `error` |
+| `onEvent` | none | Every event as an object: `start`, `compile:start`, `compile`, `install`, `guard`, `discard`, `audit`, `unreadable`, `error` |
 | `dir` | `.tinydecide` | Node: where named decisions live. Also `$TINYDECIDE_DIR` |
 | `store` | file in Node, memory elsewhere | Where answers, the model and its state live (see below) |
 | `model` | none | Start from a compiled model |
 | `autoCompile` | `{ min: 2000, growth: 2, maxEvery: 20000, window: 50000 }` | `false` compiles only on `decide.compile()` |
 | `choice`, `respond` | built in | Read custom responses, build custom local answers |
 
-Misspelled or out-of-range options throw at startup with a message that says what to write instead.
+Misspelled options, and out-of-range `target`, `delta` or `audit`, throw at startup with a message that says what to write instead.
 
 The function you get back also has:
 
@@ -109,18 +109,19 @@ In Node, `shadow('support', api)` keeps one folder:
 .tinydecide/
   .gitignore        written once: the folder holds raw inputs, so git ignores it
   support/
-    answers.jsonl   your API's recent answers, compacted to the newest 100,000
+    answers.jsonl   your API's recent answers, trimmed to the newest 100,000
     model.tdm       the installed model, and report.json, its compile report
     state.json      only while guarded, so a restart stays guarded
+    lock            the pid of the process using the folder
 ```
 
-Model and state writes are atomic, and a line cut off by a crash is skipped. Use one process per folder.
+Model and state writes are atomic, and a line cut off by a crash is skipped. The lock keeps each folder to one process. If the folder can't be opened (it is read-only, or another process holds it), answers stay in memory and one line is logged.
 
-To keep answers elsewhere, pass a `store`: an object with `append(record)`, `load()` and `size`, plus optional `loadModel`, `saveModel`, `loadState`, `saveState` and `close` (any of them may be async). `memoryStore()` and `fileStore(dir)` are the built-in ones.
+To keep answers elsewhere, pass a `store`: an object with `append(record)` and `load()`, plus optional `size`, `loadModel`, `saveModel`, `loadState`, `saveState` and `close` (any of them may be async). `memoryStore()` and `fileStore(dir)` are the built-in ones.
 
 ## Deploying
 
-**One long-running server.** Nothing to do. Answers and models persist in `.tinydecide/`.
+**One long-running server process.** Nothing to do. Answers and models persist in `.tinydecide/`. If a process manager runs several copies (`pm2 -i`, Node cluster), the first one keeps the folder and the others keep their answers in memory.
 
 **Several instances, or serverless.** Each instance can learn on its own, but they learn faster together. Send answers to one place with a custom `store`, compile on a schedule, and ship the model:
 
@@ -198,7 +199,7 @@ Both are in [`bench/results/guard-2026-10-24.md`](bench/results/guard-2026-10-24
 ## Command line
 
 ```
-tinydecide try                  watch a simulated API graduate, change, and recover
+tinydecide try                  a 15 s simulation: learn a simulated API, which then changes
 tinydecide status [dir]         what each decision is doing
 tinydecide compile <answers>    compile from a .jsonl log or a decision folder
 tinydecide inspect <model.tdm>  labels and certificate
@@ -226,7 +227,7 @@ Answer logs are one JSON object per line: `{"input": "…", "choice": "billing"}
 
 - **Features.** Text is normalized (NFKC, lowercase). Features are word unigrams and bigrams, number shapes, and character 2–4 grams within words, hashed to 32 bits. Han and kana characters are their own tokens. Pairs get side-aware and overlap features.
 - **Model.** Words and characters are pooled separately and summed into a linear head, fastText-style, trained with SGD on your API's soft labels and stored as int8 with one scale per row.
-- **Cutoff.** The score is the margin between the top two logits. A temperature is fitted only so the reported confidence is honest.
+- **Cutoff.** The score is the margin between the top two logits. A fitted temperature makes the reported confidence match how often your API agrees. It does not change the cutoff.
 - **Size and speed.** 0.2–6 MB per decision, most under 3 MB. On an M3 Pro, a call takes 8–30 µs for short texts, 45–70 µs for pairs, and about 200 µs for news articles a few thousand characters long.
 
 ## Limits
@@ -235,17 +236,20 @@ Answer logs are one JSON object per line: `{"input": "…", "choice": "billing"}
 2. **Detection takes calls.** A change confined to one label of ten was caught after a median of about 1,200 calls. A higher `audit` rate catches changes sooner and saves less.
 3. **The answer log holds raw inputs.** Keep `.tinydecide/` private, redact inputs before they reach `shadow`, or use your own `store`.
 4. **One input, one label.** Multi-label and free-text outputs are out of scope.
+5. **Long inputs need memory to compile.** Features take about 22 KB per training row at 2,000 characters, about 0.7 GB at the default 50,000-answer window. Lower `autoCompile.window` for long texts on small machines.
 
 ## Development
 
 ```sh
-npm test               # 39 tests, about 15 s
+npm test               # 49 tests, about 15 s
 npm run test:bun       # the same tests under Bun
 npm run typecheck      # the public types, with tsc
 npm run bench:guard    # how fast the guard catches an API change, over 10 runs
 ```
 
-No dependencies, by design. Issues and pull requests are welcome; please run the tests first. Security reports go through [SECURITY.md](SECURITY.md).
+Issues and pull requests are welcome; please run the tests first. Security reports go through [SECURITY.md](SECURITY.md).
+
+To release: bump `version` in package.json, add a CHANGELOG entry, and push a `vX.Y.Z` tag. CI runs the tests and stages the version on npm, and it goes public once a maintainer approves it with 2FA.
 
 ## License
 

package/bin/tinydecide.js

@@ -8,7 +8,7 @@ import { compile, loadModel, memoryStore, readJsonl, saveModel, shadow } from '.
 const HELP = `tinydecide: wrap your decision API; answer the calls it can locally, with agreement certified
 
 usage
-  tinydecide try                 watch it learn, take over, and recover from an API change (15 s, no keys)
+  tinydecide try                 a 15 s simulation, no keys: learn a simulated API, which then changes
   tinydecide status [dir]        what each decision in .tinydecide/ is doing
   tinydecide compile <answers>   compile a model from a .jsonl log, or a decision folder
                      [--out model.tdm] [--target 0.98] [--delta 0.05] [--guarantee overall|local]
@@ -53,7 +53,7 @@ async function cmdTry(f) {
   const sim = supportApi({ seed: +(f.seed ?? 1) });
   const out = process.stdout;
   const width = Math.min(out.columns || 100, 110);
-  // before the change · between the change and the guard · after recovering
+  // before the change · between the change and the guard · after the guard
   const phase = [{ local: 0, right: 0, calls: 0 }, { local: 0, right: 0, calls: 0 }, { local: 0, right: 0, calls: 0 }];
   let i = 0, p = 0, status = '', last = null;
   const recent = new Uint8Array(500), agree = new Uint8Array(500);
@@ -79,7 +79,7 @@ async function cmdTry(f) {
   const say = (line) => { clear(); out.write(`${dim(int(i).padStart(8))}  ${wrap(line, 10)}\n`); draw(); };
 
   out.write(`\n  ${bold('tinydecide try')}\n\n`);
-  out.write(`  ${wrap(`A simulated support-ticket classifier stands in for your API: ${sim.labels.length} labels, ${API_MS} ms and $0.40 per 1,000 calls (assumed). TinyDecide wraps it with one line. Watch it learn, take over, and handle the API changing under it.`, 2)}\n\n`);
+  out.write(`  ${wrap(`A simulated support-ticket classifier stands in for your API: ${sim.labels.length} labels, ${API_MS} ms and $0.40 per 1,000 calls (assumed). TinyDecide wraps it. Partway through, the API changes how it labels some messages.`, 2)}\n\n`);
 
   const decide = shadow('support', sim.api, {
     store: memoryStore(),
@@ -119,7 +119,7 @@ async function cmdTry(f) {
   // Overall agreement, as certified: your API's own answers count as agreeing.
   const rate = (x) => (x.calls ? pct(1 - (x.local - x.right) / x.calls) : '—');
   out.write(`\n  ${bold('Done.')} ${int(CALLS)} calls, ${int(local)} answered locally ${dim(`(${pct(local / CALLS, 0)})`)}.\n\n`);
-  row('agreement', `${rate(phase[0])} before the change, ${rate(phase[2])} after recovering ${dim('(overall, as certified; checked on every call, which only a simulation can do)')}`);
+  row('agreement', `${rate(phase[0])} before the change, ${rate(phase[2])} after the guard ${dim('(overall, as certified; checked on every call, which only a simulation can do)')}`);
   if (p === 2) row('the change', `caught after ${int(phase[1].calls)} calls; ${int(phase[1].local - phase[1].right)} local answers were wrong in that window`);
   row('API calls saved', `${int(s.apiCallsSaved)} ${dim(`$${(s.apiCallsSaved * PRICE).toFixed(2)} and ${(s.apiCallsSaved * API_MS / 60_000).toFixed(0)} min of waiting, at the assumed price and latency`)}`);
   if (last) row('time per answer', `${last.latencyUs} µs locally, vs ${API_MS} ms from your API`);
@@ -245,7 +245,7 @@ try {
   else if (cmd === 'compile') await cmdCompile(rest[0], flags);
   else if (cmd === 'inspect') cmdInspect(rest[0]);
   else if (cmd === 'decide') await cmdDecide(rest[0], rest.slice(1));
-  else if (!cmd || cmd === 'help' || flags.help || flags.h) console.log(HELP);
+  else if (!cmd || cmd === 'help' || cmd === '-h' || flags.help) console.log(HELP);
   else throw new Error(`unknown command "${cmd}". Run tinydecide help.`);
 } catch (err) {
   console.error(`tinydecide: ${err.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tinydecide",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Wrap your decision API. TinyDecide learns from its answers and takes over the calls it can answer locally, in microseconds, with agreement certified.",
   "keywords": [
     "classification",
@@ -51,7 +51,7 @@
   "scripts": {
     "test": "node --test \"test/*.test.js\"",
     "test:bun": "bun test ./test/",
-    "typecheck": "tsc -p test/tsconfig.json",
+    "typecheck": "npx -y -p typescript@5.9.3 tsc -p test/tsconfig.json",
     "bench:guard": "node bench/guard-drift.js change 10",
     "prepublishOnly": "npm test"
   }

package/src/compile.js

@@ -1,4 +1,4 @@
-// compile(): your API's answers in, a certified local model and an honest report out.
+// compile(): trains a local model on your API's answers and certifies a cutoff.
 //
 //   1. Split rows into train / calib / test by group (or by normalized text), so repeats never leak.
 //   2. Train on train, quantize to int8. Every later number is measured on the int8 model you ship.
@@ -9,7 +9,7 @@
 import { Featurizer, inputKey } from './features.js';
 import { hashString } from './hash.js';
 import { Model, quantize, softmax, topTwo } from './model.js';
-import { certify, minCalibration, wilson } from './stats.js';
+import { certify, localStart, minCalibration, wilson } from './stats.js';
 import { RECIPE, abortError, tick, train } from './train.js';
 
 export const DEFAULTS = Object.freeze({ target: 0.98, delta: 0.05, guarantee: 'overall', calib: 0.25, test: 0.1, seed: 1, audit: 0.02 });
@@ -17,17 +17,20 @@ export const DEFAULTS = Object.freeze({ target: 0.98, delta: 0.05, guarantee: 'o
 // Cutoffs on the logit margin. Fixed in advance, as Learn-Then-Test requires.
 const GRID = [0, ...Array.from({ length: 600 }, (_, i) => 0.01 * 6000 ** (i / 599))];
 const WHAT_IF = [0.9, 0.95, 0.97, 0.98, 0.99, 0.995];
-const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
 
 /**
- * @param {Iterable<object>} records  { input, choice?, probs?, group? } — see README for accepted shapes
+ * @param {Iterable<object>} records  { input, choice?, probs?, group? }; see README for accepted shapes
  * @param {object} [opts]
  * @returns {Promise<{ model: Model, report: object }>}
  */
 export async function compile(records, opts = {}) {
   const o = { ...DEFAULTS, ...opts };
+  for (const k of ['target', 'delta']) {
+    if (!(typeof o[k] === 'number' && o[k] > 0 && o[k] < 1)) throw new RangeError(`${k} must be a number between 0 and 1; got ${o[k]}`);
+  }
+  if (o.guarantee !== 'overall' && o.guarantee !== 'local') throw new RangeError(`guarantee must be "overall" or "local"; got ${o.guarantee}`);
   const alpha = 1 - o.target;
-  const t0 = now();
+  const t0 = performance.now();
   const onProgress = o.onProgress ?? (() => {});
   const pause = async () => { await tick(); if (o.signal?.aborted) throw abortError(); };
 
@@ -53,7 +56,7 @@ export async function compile(records, opts = {}) {
     if (trainRows.length % 2000 === 0) await pause();
   }
   const params = await train(trainRows, K, { ...pick(o, Object.keys(RECIPE)), seed: o.seed, onProgress, yieldMs: o.yieldMs, signal: o.signal });
-  const trainMs = now() - t0;
+  const trainMs = performance.now() - t0;
 
   await pause();
   const draft = quantize({ labels, ...params });
@@ -73,10 +76,8 @@ export async function compile(records, opts = {}) {
   };
   const calShare = cal.n ? cert.local / cal.n : 0;
   const calLocalAgree = cert.local ? 1 - cert.errors / cert.local : null;
-  // How often the model's guess matches the API on calls it defers. shadow() watches this live:
-  // deferred calls get the API's answer anyway, so a drop here is a free early sign of drift.
-  // Per label the model leans toward, how its confidence on deferred calls compares with how often
-  // the API actually agreed: shadow() expects that ratio live. Shrunk toward 1 when rows are few.
+  // Agreement on deferred calibration rows, overall and per guessed label (as a ratio to the model's
+  // confidence, shrunk toward 1 when rows are few). shadow() checks both live.
   let dn = 0, dAgree = 0;
   const seen = new Float64Array(K), expected = new Float64Array(K);
   for (let i = 0; i < cal.n; i++) {
@@ -101,7 +102,7 @@ export async function compile(records, opts = {}) {
   const latencyUs = timeDecide(model, (split.test.length ? split.test : split.calib).slice(0, 400));
 
   const share = test ? test.share : calShare;
-  const minCal = minCalibration(alpha, o.delta);
+  const minCal = o.guarantee === 'local' ? localStart(alpha, o.delta) : minCalibration(alpha, o.delta);
   const verdict =
     cal.n < minCal ? 'need-more-data' : calShare >= 0.25 ? 'ship' : calShare >= 0.05 ? 'marginal' : 'not-worth-it';
   const report = {
@@ -118,7 +119,7 @@ export async function compile(records, opts = {}) {
     temperature: T,
     bytes: model.toBytes().byteLength,
     latencyUs,
-    ms: { train: Math.round(trainMs), total: Math.round(now() - t0) },
+    ms: { train: Math.round(trainMs), total: Math.round(performance.now() - t0) },
   };
   model.meta.verdict = verdict;
   onProgress({ phase: 'done', done: 1 });
@@ -240,10 +241,10 @@ function evaluate(model, rows, params) {
 function timeDecide(model, rows) {
   if (!rows.length) return null;
   for (const r of rows) model.decide(r.input);
-  const t = now();
+  const t = performance.now();
   let reps = 0;
-  while (now() - t < 50) { for (const r of rows) model.decide(r.input); reps++; }
-  return Math.round(((now() - t) * 1000) / (reps * rows.length) * 10) / 10;
+  while (performance.now() - t < 50) { for (const r of rows) model.decide(r.input); reps++; }
+  return Math.round(((performance.now() - t) * 1000) / (reps * rows.length) * 10) / 10;
 }
 
 function summarize({ verdict, o, calShare, cal, minCal, whatIf }) {

package/src/features.js

@@ -93,12 +93,12 @@ export class Featurizer {
   }
 
   #side(toks, salt) {
-    const uni = new Set();
+    const uni = salt ? new Set() : null; // only pairs compare their sides
     let prev = 0;
     for (let i = 0; i < toks.length; i++) {
       const t = toks[i];
       const h = hashString(t, SEED.word);
-      uni.add(h);
+      uni?.add(h);
       this.w.push(salt ? fmix(h ^ salt) : h);
       if (i > 0) this.w.push(fmix((Math.imul(prev, 0x9e3779b1) ^ h ^ SEED.bigram ^ salt) >>> 0));
       prev = h;

package/src/log.js

@@ -1,5 +1,4 @@
-// One plain-English line per lifecycle event, so the moment a decision graduates, falls back to your
-// API, or recovers is visible in your logs. Nothing is logged per call.
+// One log line per lifecycle event (start, compile, guard, error), never per call.
 
 const pct = (x) => `${Math.round(x * 100)}%`;
 const int = (x) => x.toLocaleString('en-US');

package/src/node.js

@@ -1,15 +1,17 @@
 // The Node entry. Same API as the browser build, plus:
 //   - shadow('name', api) keeps answers, the model and its state in .tinydecide/name/, so a restart
 //     resumes where it left off
-//   - compiles run in a worker thread, so they never pause your server's event loop
+//   - compiles train in a worker thread, off your server's event loop
 
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, writeSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { Worker } from 'node:worker_threads';
 import { gunzipSync } from 'node:zlib';
 import { compile } from './compile.js';
+import { logger } from './log.js';
 import { Model } from './model.js';
-import { NAME, shadow as core } from './shadow.js';
+import { NAME, shadow as core, validate } from './shadow.js';
+import { memoryStore } from './store.js';
 import { abortError } from './train.js';
 
 export * from './index.js';
@@ -22,23 +24,36 @@ export function shadow(name, api, options) {
   if (typeof name === 'function') return core(name, { compiler: compileInWorker, ...api });
   const { dir = process.env.TINYDECIDE_DIR || '.tinydecide', ...rest } = options ?? {};
   if (typeof name !== 'string' || !NAME.test(name)) return core(name, api, rest); // core explains the error
-  return core(name, api, { compiler: compileInWorker, store: rest.store ?? fileStore(join(dir, name)), ...rest });
+  validate(name, api, rest); // before anything touches the disk
+  let store = rest.store;
+  if (!store) {
+    try {
+      store = fileStore(join(dir, name));
+    } catch (err) {
+      // A folder that can't be written, or that another process holds, must not stop the app.
+      store = memoryStore();
+      logger(name, rest.log ?? true)({ type: 'error', where: `opening ${join(dir, name)}`, error: `${err.message}. Answers stay in memory.` });
+    }
+  }
+  return core(name, api, { compiler: compileInWorker, ...rest, store });
 }
 
 /**
  * Keeps one decision in a folder:
- *   answers.jsonl  your API's recent answers (compacted to the newest `limit`)
+ *   answers.jsonl  your API's recent answers (trimmed to the newest `limit`)
  *   model.tdm      the installed model, and report.json, its compile report
  *   state.json     present only while guarded
- * One process per folder. Writes of the model and state are atomic.
+ *   lock           the pid of the process using the folder; a second store on it throws
+ * Writes of the model and state are atomic.
  */
 export function fileStore(dir, { limit = 100_000 } = {}) {
   const root = dirname(dir);
   const fresh = !existsSync(root);
-  mkdirSync(dir, { recursive: true });
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
   // The log holds raw inputs, so keep the whole folder out of git unless someone opts in.
   if (fresh) safeWrite(join(root, '.gitignore'), '# created by tinydecide: answers.jsonl holds raw inputs\n*\n');
-  const path = { answers: join(dir, 'answers.jsonl'), model: join(dir, 'model.tdm'), report: join(dir, 'report.json'), state: join(dir, 'state.json') };
+  const path = { answers: join(dir, 'answers.jsonl'), model: join(dir, 'model.tdm'), report: join(dir, 'report.json'), state: join(dir, 'state.json'), lock: resolve(dir, 'lock') };
+  takeLock(path.lock);
   let fd = -1, size = 0;
 
   function open() {
@@ -49,22 +64,32 @@ export function fileStore(dir, { limit = 100_000 } = {}) {
       // A crash mid-write can leave a partial last line; end it so the next answer starts clean.
       if (buf.length && buf[buf.length - 1] !== 10) writeFileSync(path.answers, '\n', { flag: 'a' });
     }
-    fd = openSync(path.answers, 'a');
+    fd = openSync(path.answers, 'a', 0o600);
   }
   open();
 
+  /** Keeps the newest `limit` lines. Scans bytes for newlines, so nothing is parsed. */
+  function trim() {
+    const buf = readFileSync(path.answers);
+    let at = buf.length - 1; // the newline that ends the last line
+    for (let k = 0; k < limit && at > 0; k++) at = buf.lastIndexOf(10, at - 1);
+    closeSync(fd); // first: Windows will not rename over a file that is still open
+    fd = -1;
+    try {
+      atomicWrite(path.answers, buf.subarray(at + 1));
+    } finally {
+      open();
+      size = Math.min(size, limit); // after a failure, wait another quarter of `limit` before retrying
+    }
+  }
+
   return {
     dir,
-    append(record) { writeSync(fd, JSON.stringify(record) + '\n'); size++; },
-    load() {
-      const rows = readJsonl(path.answers);
-      if (rows.length <= limit * 1.25) return rows.slice(-limit);
-      const keep = rows.slice(-limit);
-      closeSync(fd); // first: Windows will not rename over a file that is still open
-      atomicWrite(path.answers, keep.map((r) => JSON.stringify(r)).join('\n') + '\n');
-      open();
-      return keep;
+    append(record) {
+      writeSync(fd, JSON.stringify(record) + '\n');
+      if (++size > limit * 1.25) trim();
     },
+    load: () => readJsonl(path.answers).slice(-limit),
     get size() { return size; },
     loadModel: () => (existsSync(path.model) ? Model.fromBytes(readFileSync(path.model)) : null),
     saveModel(model, report) {
@@ -79,10 +104,40 @@ export function fileStore(dir, { limit = 100_000 } = {}) {
       if (state) atomicWrite(path.state, JSON.stringify(state) + '\n');
       else rmSync(path.state, { force: true });
     },
-    close() { if (fd >= 0) { closeSync(fd); fd = -1; } },
+    close() {
+      if (fd < 0) return;
+      closeSync(fd);
+      fd = -1;
+      rmSync(path.lock, { force: true });
+      held.delete(path.lock);
+    },
   };
 }
 
+const held = new Set(); // lock files this process holds
+
+/** One process per folder: a second writer would lose answers when the log is trimmed. */
+function takeLock(path) {
+  if (held.has(path)) throw new Error(`${dirname(path)} is already open in this process`);
+  try {
+    writeFileSync(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+    const pid = Number(readFileSync(path, 'utf8'));
+    // Our own pid here means an earlier run left it, as when a container restarts with the same pid.
+    if (pid && pid !== process.pid && alive(pid)) {
+      throw new Error(`${dirname(path)} is in use by process ${pid}. Use one process per folder, or delete ${path} if that process is not using it`);
+    }
+    rmSync(path, { force: true }); // stale: the process that wrote it is gone
+    writeFileSync(path, String(process.pid), { flag: 'wx', mode: 0o600 });
+  }
+  held.add(path);
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (err) { return err.code === 'EPERM'; }
+}
+
 let workerBroken = false;
 
 /** compile() in a worker thread. Falls back to the calling thread if workers are unavailable. */
@@ -146,7 +201,7 @@ export function saveModel(path, model) {
 
 function atomicWrite(path, data) {
   const tmp = `${path}.${process.pid}.tmp`;
-  writeFileSync(tmp, data);
+  writeFileSync(tmp, data, { mode: 0o600 });
   renameSync(tmp, path);
 }
 

package/src/shadow.js

@@ -16,10 +16,10 @@
 //             alarms over a model's life when agreement sits exactly at target, fewer above it
 //   deferred  on deferred calls (answered by your API anyway, so free to check), the model's guess
 //             matches your API far less often than it did on calibration, overall or for one label
-//             against the model's own calibrated confidence — the fastest sign the API changed
+//             against the model's own calibrated confidence. It usually trips before the audit check.
 //
-// One rule above all: TinyDecide never makes a call fail that would have succeeded without it.
-// If anything inside it throws, the call goes to your API.
+// TinyDecide never makes a call fail that would have succeeded without it: if anything inside it
+// throws, the call goes to your API.
 
 import { compile } from './compile.js';
 import { logger } from './log.js';
@@ -39,7 +39,6 @@ const LABEL_SLACK = 0.1; // room for the model's confidence being somewhat off o
 const LABEL_KEYS = ['choice', 'label', 'decision', 'answer'];
 const PROBS_KEYS = ['probs', 'probabilities'];
 const OPTIONS = ['target', 'delta', 'audit', 'labels', 'model', 'store', 'choice', 'respond', 'group', 'fallback', 'log', 'onEvent', 'autoCompile', 'compile', 'compiler', 'random'];
-const now = () => globalThis.performance?.now() ?? Date.now();
 
 /**
  * @param {string} [name]  names the decision in logs; in Node it also names its folder in .tinydecide/
@@ -56,6 +55,7 @@ export function shadow(name, api, options) {
     onEvent: () => {}, compile: {}, compiler: compile, random: Math.random,
     ...options,
   };
+  o.labels ??= o.model?.labels; // a model you pass in fixes the label order
   const auto = o.autoCompile === false ? null : { min: 2000, growth: 2, maxEvery: 20_000, window: 50_000, ...o.autoCompile };
   const store = o.store ?? memoryStore();
   const say = logger(name, o.log);
@@ -187,10 +187,10 @@ export function shadow(name, api, options) {
 
   async function detailed(input) {
     n.calls++;
-    const t0 = now();
+    const t0 = performance.now();
     const sample = mode !== 'local' || o.random() < o.audit;
     let d = null;
-    // Until one response from your API has been seen, its shape is unknown, so it answers.
+    // Until your API has given one readable response, its shape is unknown, so it answers.
     if (mode === 'local' && model && (shape || o.respond)) {
       d = safely('the local model', () => model.decide(input, { probs: wantsProbs() }));
       if (d === NOPE) d = null;
@@ -199,7 +199,7 @@ export function shadow(name, api, options) {
         if (value !== NOPE) {
           n.local++;
           if (sample) audit(input, d.choice);
-          return { value, source: 'local', choice: d.choice, confidence: d.confidence, ms: now() - t0 };
+          return { value, source: 'local', choice: d.choice, confidence: d.confidence, ms: performance.now() - t0 };
         }
       }
     }
@@ -212,13 +212,13 @@ export function shadow(name, api, options) {
       const value = d && d !== NOPE ? safely('respond', () => answer(d)) : NOPE;
       if (value === NOPE) throw err;
       n.fallback++;
-      return { value, source: 'fallback', choice: d.choice, confidence: d.confidence, ms: now() - t0 };
+      return { value, source: 'fallback', choice: d.choice, confidence: d.confidence, ms: performance.now() - t0 };
     }
     n.api++;
     const choice = record(input, resp, sample);
     if (mode === 'local' && d && choice != null) observeDeferred(d.choice, d.confidence, d.choice === choice);
     if (sample && mode === 'local') observe(true);
-    return { value: resp, source: 'api', choice, confidence: null, ms: now() - t0 };
+    return { value: resp, source: 'api', choice, confidence: null, ms: performance.now() - t0 };
   }
 
   function audit(input, localChoice) {
@@ -230,18 +230,19 @@ export function shadow(name, api, options) {
       if (!agree) n.auditDisagree++;
       emit({ type: 'audit', agree, local: localChoice, api: choice });
       if (mode === 'local') observe(agree);
-    }, () => {}); // your API failing is your app's business; the audit is simply skipped
+    }, () => {}); // a failed audit is skipped
   }
 
   /** Logs one answer from your API. Returns the label, or null when none could be read. */
   function record(input, resp, sample) {
-    shape ??= shapeOf(resp);
-    const read = safely('choice', () => o.choice(resp, model?.labels ?? o.labels));
-    const choice = read === NOPE ? null : read?.choice;
+    // Index labels and probs arrays map only through labels you gave; a model's sorted labels are not your API's order.
+    const read = safely('choice', () => o.choice(resp, o.labels));
+    const choice = read === NOPE ? null : typeof read === 'string' ? read : read?.choice;
     if (choice == null) {
       if (!unreadable) { unreadable = true; emit({ type: 'unreadable', preview: preview(resp) }); }
       return null;
     }
+    shape ??= shapeOf(resp); // learned from a response whose label could be read
     // A label nobody has seen yet joins the label set, so the next compile can learn it.
     if (o.labels && !o.labels.includes(choice)) o.labels = [...o.labels, choice];
     if (model && !model.labels.includes(choice)) trip('schema', { label: choice });
@@ -265,7 +266,8 @@ export function shadow(name, api, options) {
   function answer(d) {
     if (o.respond) return o.respond(d, shape);
     if (!shape || shape.kind === 'string') return d.choice;
-    const out = { [shape.key]: shape.numeric ? d.index : d.choice };
+    if (shape.probsArray && !o.labels) throw new Error('your API returns probs as an array, so pass labels: [...] in that order to answer locally');
+    const out = { [shape.key]: shape.numeric ? (o.labels ? d.index : Number(d.choice)) : d.choice };
     if (shape.probsKey && d.probs) out[shape.probsKey] = shape.probsArray ? model.labels.map((l) => d.probs[l]) : d.probs;
     if (shape.confidence) out.confidence = d.confidence;
     return out;
@@ -294,18 +296,20 @@ export function shadow(name, api, options) {
       rows = rows.slice(-(auto?.window ?? 50_000));
       emit({ type: 'compile:start', rows: rows.length });
       n.compiles++;
+      // Keep the labels the model knows: one missing from this window is rare, not new.
+      const labels = o.labels ?? (model ? [...new Set([...model.labels, ...rows.map((r) => r.choice).filter((c) => typeof c === 'string')])] : undefined);
       const ctrl = (running = new AbortController());
       let result = null;
       try {
         result = await o.compiler(rows, {
-          target: o.target, delta: o.delta, audit: o.audit, labels: o.labels, ...o.compile, signal: ctrl.signal, background,
+          ...o.compile, target: o.target, delta: o.delta, audit: o.audit, labels, signal: ctrl.signal, background,
         });
       } catch (err) {
         if (err?.name !== 'AbortError') throw err;
       } finally {
         running = null;
-        // Set even when the compile fails, so a failing compile is not retried on every call.
-        if (epoch === started) basis = rows.length;
+        // Set even when the compile fails, and to at least 1, so a failing compile waits for more answers.
+        if (epoch === started) basis = Math.max(rows.length, 1);
       }
       if (!result || epoch !== started || closed) {
         // The guard tripped while this compile ran, so its rows straddle the change. Never install it.
@@ -348,7 +352,7 @@ export function shadow(name, api, options) {
     await persist('closing the store', () => store.close?.());
   };
   decide.stats = () => ({
-    name: name ?? null, mode, ...n, logged: available,
+    name: name ?? null, mode, ...n, logged: store.size ?? available,
     share: n.calls ? n.local / n.calls : 0,
     apiCallsSaved: n.local - n.audits,
     live: { sampled: ringN, agreement: ringN ? ringAgree / ringN : null, ci: ringN ? wilson(ringAgree, ringN) : null },
@@ -391,7 +395,7 @@ function preview(resp) {
 
 export const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 
-function validate(name, api, options) {
+export function validate(name, api, options) {
   const fail = (msg) => { throw new TypeError(`tinydecide: ${msg}`); };
   if (name !== undefined && (typeof name !== 'string' || !NAME.test(name))) {
     fail(`the name must be 1–64 letters, digits, dots, dashes or underscores, like "support-intent"; got ${JSON.stringify(name)}`);
@@ -399,8 +403,7 @@ function validate(name, api, options) {
   if (typeof api !== 'function') fail(`shadow(${name ? `"${name}", ` : ''}api) needs your API call as a function, like (text) => classify(text); got ${typeof api}`);
   if (typeof options !== 'object') fail(`options must be an object; got ${typeof options}`);
   for (const k of Object.keys(options)) {
-    if (k === 'dir') fail('"dir" only works in Node, where answers and models are saved to files');
-    if (k === 'sink' || k === 'onModel') fail(`"${k}" was replaced by "store"; see the README`);
+    if (k === 'dir') fail('"dir" needs a named decision in Node, like shadow("support", api, { dir })');
     if (!OPTIONS.includes(k)) fail(`unknown option "${k}". Options: ${OPTIONS.join(', ')}`);
   }
   const unit = (k, lo, hi) => {

package/src/stats.js

@@ -31,8 +31,8 @@ export function wilson(x, n, z = 1.959963984540054) {
  * at level delta; it stops at the first cutoff that fails. The grid must not be chosen from the
  * calibration rows themselves.
  *
- *   guarantee 'overall': risk = P(answered locally and wrong)   — n is every calibration row
- *   guarantee 'local'  : risk = P(wrong | answered locally)     — n is the rows the cutoff answers
+ *   guarantee 'overall': risk = P(answered locally and wrong)   (n: all calibration rows)
+ *   guarantee 'local'  : risk = P(wrong | answered locally)     (n: rows answered locally)
  *
  * @param {Float64Array|number[]} score  per calibration row; answered locally when score ≥ cutoff
  * @param {Uint8Array|boolean[]} wrong   per calibration row; the local answer differs from the API's
@@ -43,10 +43,11 @@ export function certify(score, wrong, grid, { alpha, delta = 0.05, guarantee = '
   const n = score.length;
   const order = Array.from(score.keys()).sort((i, j) => score[j] - score[i]);
   const cuts = [...new Set(grid)].sort((a, b) => b - a);
-  // For the local guarantee, cutoffs that answer fewer rows than an error-free sample needs are
-  // skipped rather than failed. Which cutoffs are skipped depends only on the scores, never on the
-  // errors, so the test sequence is still fixed given the scores.
-  const floor = guarantee === 'local' ? minCalibration(alpha, delta) : 1;
+  // For the local guarantee, testing starts at the first cutoff that answers localStart() rows:
+  // starting at the bare minimum fails the whole sequence on a single mislabelled row among the most
+  // confident few. Which cutoffs are skipped depends only on the scores, never on the errors, so the
+  // test sequence is still fixed given the scores.
+  const floor = guarantee === 'local' ? localStart(alpha, delta) : 1;
   let best = { cutoff: Infinity, local: 0, errors: 0, pValue: 0, tested: 0 };
   let i = 0, local = 0, errors = 0;
   for (let c = 0; c < cuts.length; c++) {
@@ -61,6 +62,16 @@ export function certify(score, wrong, grid, { alpha, delta = 0.05, guarantee = '
   return best;
 }
 
+/**
+ * Local answers needed before the local guarantee starts testing: the smallest sample on which an
+ * error rate of half the budget would still certify, so one stray label error cannot end the test.
+ */
+export function localStart(alpha, delta = 0.05) {
+  let m = minCalibration(alpha, delta);
+  while (binomCdf(Math.floor((m * alpha) / 2), m, alpha) > delta) m++;
+  return m;
+}
+
 /** Smallest calibration size at which an error-free sample can certify alpha at level delta. */
 export function minCalibration(alpha, delta = 0.05) {
   return Math.ceil(Math.log(delta) / Math.log1p(-alpha));

package/src/train.js

@@ -6,7 +6,6 @@ import { U32Map, rng } from './hash.js';
 export const RECIPE = Object.freeze({ d: 32, lr: 0.5, minCount: 2, maxFeatures: 200_000, steps: 200_000, minEpochs: 5, maxEpochs: 25 });
 
 export const tick = makeTick();
-const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
 
 // Yield to the event loop between chunks of work. Browsers clamp nested setTimeout to 4 ms, so use a
 // MessageChannel there; Node has setImmediate.
@@ -21,7 +20,7 @@ function makeTick() {
 }
 
 /**
- * @param {{ w: Uint32Array, c: Uint32Array, t: Float32Array }[]} rows  features and target distribution
+ * @param {{ w: Uint32Array, c: Uint32Array, t: Float32Array }[]} rows  features and target distribution; remapped in place
  * @param {number} K
  * @returns {Promise<{ d, keys: Uint32Array, E: Float32Array, W: Float32Array, b: Float32Array, epochs: number }>}
  */
@@ -45,7 +44,11 @@ export async function train(rows, K, opts = {}) {
     for (const f of feats) { const r = index.get(f); if (r >= 0) out.push(r); }
     return Int32Array.from(out);
   };
-  const data = rows.map((r) => ({ w: ids(r.w), c: ids(r.c), t: r.t }));
+  // In place, so each row's raw feature copy can be freed as soon as it is mapped.
+  // shortcut: rows still take about 22 KB each at 2,000-char inputs (0.7 GB at the default 50,000-row
+  // window); cap the window by total features if long-input decisions must fit in less memory.
+  for (let i = 0; i < rows.length; i++) rows[i] = { w: ids(rows[i].w), c: ids(rows[i].c), t: rows[i].t };
+  const data = rows;
 
   const V = keys.length;
   const E = new Float32Array(V * d);
@@ -65,7 +68,7 @@ export async function train(rows, K, opts = {}) {
   const h = new Float32Array(d), hw = new Float32Array(d), hc = new Float32Array(d), gh = new Float32Array(d);
   const p = new Float32Array(K);
   const order = Int32Array.from({ length: N }, (_, i) => i);
-  let step = 0, last = now();
+  let step = 0, last = performance.now();
 
   for (let ep = 0; ep < epochs; ep++) {
     for (let i = N - 1; i > 0; i--) { const j = Math.floor(rand() * (i + 1)); const x = order[i]; order[i] = order[j]; order[j] = x; }
@@ -95,11 +98,11 @@ export async function train(rows, K, opts = {}) {
       }
       if (nw) scatter(E, ex.w, gh, -rate / nw, d);
       if (nc) scatter(E, ex.c, gh, -rate / nc, d);
-      if ((step & 255) === 0 && now() - last > yieldMs) {
+      if ((step & 255) === 0 && performance.now() - last > yieldMs) {
         onProgress({ phase: 'train', done: step / total });
         await tick();
         if (opts.signal?.aborted) throw abortError();
-        last = now();
+        last = performance.now();
       }
     }
   }

package/types/index.d.ts

@@ -1,9 +1,7 @@
-// Type definitions for tinydecide.
-
 /** learning: every call goes to your API · local: confident calls answered locally · guarded: back to your API after a failed check. */
 export type Mode = 'learning' | 'local' | 'guarded';
 
-/** Call it exactly like your API function. */
+/** Call it like your API function: one input in, a Promise of the response out. */
 export interface Decide<I, R> {
   (input: I): Promise<R>;
   /** The answer plus who gave it. */
@@ -39,18 +37,18 @@ export interface ShadowOptions<I = any, R = any> {
   delta?: number;
   /** Share of calls your API also answers in the background, to check agreement live. Default 0.02. */
   audit?: number;
-  /** Fixes the label set and its order. Needed when your API returns label indexes or probability arrays. */
+  /** Fixes the label set and its order. Needed when your API returns probability arrays; also names index labels. */
   labels?: string[];
   /** Starts from a compiled model, such as one built with `tinydecide compile`. */
   model?: Model;
-  /** Where answers, the model and its state live. Default: memory; in Node, `.tinydecide/<name>/` for a named decision. */
+  /** Where answers, the model and its state live. Default: memory; in Node, `.tinydecide/<name>/` for a named decision, or memory with one log line if that folder can't be opened. */
   store?: Store;
   /** Node only: the folder that holds named decisions. Default `.tinydecide`, or `$TINYDECIDE_DIR`. */
   dir?: string;
   /** Keeps related calls (one conversation, one customer) in the same split, so the certificate covers new ones. */
   group?: (input: I) => string | number | null | undefined;
   /** Reads the label, and optionally probabilities, from your API's response. Default: a string, or `choice` / `label` / `decision` / `answer` with `probs`. */
-  choice?: (response: R, labels: string[] | undefined) => { choice: string | null; probs?: Record<string, number> | null } | null | undefined;
+  choice?: (response: R, labels: string[] | undefined) => string | { choice: string | null; probs?: Record<string, number> | null } | null | undefined;
   /** Builds a local answer. Default: the label under the same key your API uses, plus `probs` and `confidence` if your API returns them. */
   respond?: (decision: Decision, shape: ResponseShape | null) => R;
   /** Answers locally when your API throws and a model exists. Default false. */
@@ -69,8 +67,8 @@ export interface ShadowOptions<I = any, R = any> {
     /** Most recent answers a compile uses. Default 50000. */
     window?: number;
   };
-  /** Extra options for each compile. */
-  compile?: Partial<CompileOptions>;
+  /** Extra options for each compile. `target`, `delta`, `audit` and `labels` are set above. */
+  compile?: Partial<Omit<CompileOptions, 'target' | 'delta' | 'audit' | 'labels'>>;
   /** Replaces the compile function. Node uses a worker thread by default. */
   compiler?: (rows: AnswerRecord[], options: CompileOptions & { background?: boolean }) => Promise<{ model: Model; report: Report }>;
   /** Source of randomness for the audit sample. Default Math.random. */
@@ -141,7 +139,7 @@ export interface AnswerRecord {
   sample?: false;
 }
 
-/** Where shadow() keeps answers, the model and its state. Only append, load and size are required. */
+/** Where shadow() keeps answers, the model and its state. Only append and load are required. */
 export interface Store {
   append(record: AnswerRecord): void;
   /** The most recent answers, oldest first. */
@@ -176,6 +174,10 @@ export interface CompileOptions {
   seed: number;
   /** The audit rate the model will run with, used to estimate savings. Default 0.02. */
   audit: number;
+  /** Width of each feature's vector. Default 32. */
+  d?: number;
+  /** Most features the model keeps, the most frequent first. Default 200000. */
+  maxFeatures?: number;
   onProgress?: (progress: { phase: string; done: number }) => void;
   signal?: AbortSignal;
 }
@@ -249,7 +251,7 @@ export interface ModelMeta {
   created?: string;
   certificate?: Certificate;
   rows?: { total: number; train: number; calib: number; test: number };
-  expected?: { share: number; localAgreement: number | null; deferred: { n: number; agreement: number | null } };
+  expected?: { share: number; localAgreement: number | null; deferred: { n: number; agreement: number | null; ratio: Record<string, number> } };
   verdict?: Verdict;
   response?: ResponseShape | null;
   [key: string]: unknown;
@@ -275,7 +277,7 @@ export class Model {
 
 // ── Node only ───────────────────────────────────────────────────────────────────────────────────
 
-/** Node only. Keeps one decision in a folder: answers.jsonl, model.tdm, report.json and, while guarded, state.json. */
+/** Node only. Keeps one decision in a folder: answers.jsonl, model.tdm, report.json, a lock file and, while guarded, state.json. Throws if another store holds the folder. */
 export function fileStore(dir: string, options?: { limit?: number }): Store & { readonly dir: string };
 /** Node only. */
 export function loadModel(path: string): Model;