neurarch 0.1.0 → 0.1.2

package/README.md

@@ -9,6 +9,7 @@ npx neurarch rightsize jobs.csv          # each past job's request next to what
 npx neurarch Qwen/Qwen3-8B --batch 8     # the training peak for one model
 npx neurarch oom error.txt --model Qwen/Qwen3-8B --batch 8   # why it ran out of memory, and the least invasive fix
 npx neurarch Qwen/Qwen3-8B --inference --batch 4 --seq-len 4096 --gen 512   # weights + KV cache for a generation job
+npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524         # does the data fit what the config accepts
 ```
 
 The memory number is calibrated against measured runs, and every run is public
@@ -117,6 +118,34 @@ prices. Nothing was trained and nothing was measured, which is why the verb is
 "quoted": what it is good for is deciding whether to start the run, not
 predicting what comes out of it.
 
+## Does the data fit what the config accepts
+
+Some jobs never reach their peak: they are admitted, wait for the card, load the
+weights and then index past a table on the first batch. Each of these is
+readable from the config before anything is reserved.
+
+```
+$ npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524
+
+  data fit checked: sequence length, tokenizer size
+    block Sequences of 1024 tokens are longer than the 512-row position table
+          fix: Truncate or chunk to 512 tokens, or pick a model whose context covers 1024.
+    block The tokenizer has 30524 ids and the embedding has 30522 rows
+          fix: Call model.resize_token_embeddings(len(tokenizer)) before training, and budget for the new rows.
+```
+
+| flag | checked against | when it blocks |
+|---|---|---|
+| `--seq-len N` | the position scheme | past a learned position table (a rotary context only warns: it runs) |
+| `--tokenizer-size N` | rows in the token embedding | more tokenizer ids than rows |
+| `--classes N` | a `*ForSequenceClassification`-style head in the config, or a graph's final Linear | more labels than the head emits (fewer only warns) |
+| `--image-size N` | the patch position table | any other size |
+| `--channels N` | the first layer's input channels | any other count |
+
+A field you do not state is not checked, and the output lists what could not be
+compared and why, so a clean result never stands in for one nobody ran. A block
+sets the exit code to 1. The same check is `data` on `POST /api/v1/check`.
+
 ## Which modules a LoRA can sit on
 
 ```
@@ -188,7 +217,20 @@ gpt2-pretrain,openai-community/gpt2,4xA100-80,16,24,1024,
 `--prices prices.json` overrides the default list prices per GPU-hour
 (`{"H100": 2.49, "A100-80": 1.79}`); cards it does not name keep theirs, and the
 report says which were overridden. `--json` returns every row with the plan's
-own `peakGb`, `smallestFitGpu`, `maxBatch` and `twoCardSplit`.
+own `peakGb`, `smallestFitGpu`, `maxBatch` and `twoCardSplit`, plus `upperNeedGb` and
+`fit`: a row whose capacity holds the estimate but not the conservative peak (the
+estimate x 1.43, at or above the measured peak on 95% of held-out runs) is
+`borderline`, says "measure once", and claims as not needed only what the
+conservative peak would free.
+
+**Three answers per card.** The training block prints each card green (the
+conservative peak with 1.15x headroom fits), yellow `borderline` (the estimate
+fits, the conservative peak does not: measure one step first) or red (the estimate
+alone is past the card), then the upper bound, the largest batch it fits, and how
+many copies of it fit each card and the smallest MIG slice on A100 / H100 (memory
+only: compute and bandwidth are not considered). `--json` carries the same as
+`cost.peakGbUpper`, `cost.upperBound`, `cost.gpuVerdict`, `cost.maxBatchSafe` and
+`cost.shareable`; `cost.gpuFits` is unchanged.
 
 **The memory model.** The peak is `buildPlan`'s training peak under AdamW with
 bf16 autocast: weights, gradients and optimizer state plus activations (every

package/bin/neurarch.mjs

@@ -10,6 +10,7 @@
  *   npx neurarch Qwen/Qwen3-8B --batch 8 --seq-len 8192                # training peak at that length, no price
  *   npx neurarch Qwen/Qwen3-8B --inference --batch 4 --seq-len 4096 --gen 512   # weights + KV cache, which cards hold it
  *   npx neurarch Qwen/Qwen3-8B --lora-targets         # which modules a LoRA can sit on
+ *   npx neurarch bert-base-uncased --seq-len 1024 --tokenizer-size 30524   # will this data crash it after it gets the GPU
  *   npx neurarch rightsize jobs.csv                   # requested vs needed GPU over past jobs
  *
  * The number this exists to print is the second one: parameters derived from
@@ -19,7 +20,7 @@
  *
  * Zero dependencies; the engine is bundled. Set HF_TOKEN for gated repos.
  */
-import { inspectHFModel, keyFor, AGREE_TOLERANCE, priceHFModel, parseHumanSize, PREFLIGHT_GPUS, specFromFlags, renderLoraText, rightsize, renderMarkdown, headline, applyPrices, DEFAULT_CARDS, oomReport, renderOomText, readAttention, attentionPhrase, readSeqLen, DEFAULT_SEQ_LEN, inferHFModel, readInferencePrecision, INFERENCE_PRECISIONS, DEFAULT_GEN_TOKENS, DEFAULT_INFERENCE_BATCH, CHANGE_HEADROOM } from '../engine.bundle.mjs';
+import { inspectHFModel, keyFor, AGREE_TOLERANCE, priceHFModel, parseHumanSize, PREFLIGHT_GPUS, specFromFlags, renderLoraText, rightsize, renderMarkdown, headline, applyPrices, DEFAULT_CARDS, oomReport, renderOomText, readAttention, attentionPhrase, readSeqLen, DEFAULT_SEQ_LEN, inferHFModel, readInferencePrecision, INFERENCE_PRECISIONS, DEFAULT_GEN_TOKENS, DEFAULT_INFERENCE_BATCH, CHANGE_HEADROOM, storedTwiceSentence, dataFitHFModel } from '../engine.bundle.mjs';
 /** The channel tag on every link this program prints. `docs/DISTRIBUTION.md`
  *  has asked for one since the first release: without it a visit from a tool
  *  and a visit from a search result are the same row, and "which channel brings
@@ -197,7 +198,7 @@ for gated repos); nothing is uploaded.
 
 // `--data 3M` and `--gpu a100` take a value, so their value must not fall
 // through to `positional` and be read as a second model id.
-const VALUED = new Set(['--data', '--gpu', '--lora', '--quant', '--fit', '--serve', '--batch', '--attention', '--seq-len', '--gen', '--precision']);
+const VALUED = new Set(['--data', '--gpu', '--lora', '--quant', '--fit', '--serve', '--batch', '--attention', '--seq-len', '--gen', '--precision', '--tokenizer-size', '--classes', '--image-size', '--channels']);
 const flags = new Set();
 const opts = {};
 const positional = [];
@@ -234,6 +235,11 @@ if (flags.has('-h') || flags.has('--help') || positional.length === 0) {
                                      the change record: what may move on this base, and whether the gate approves it
   npx neurarch <model-id> --lora-targets   every Linear a LoRA can target, and PEFT target_modules
                                      for the attention and all-linear presets with r=8 / r=16 totals
+  npx neurarch <model-id> --seq-len 1024 --tokenizer-size 30524 --classes 5 [--image-size 384 --channels 1]
+                                     does YOUR data fit what the config accepts: sequence vs the
+                                     position table, tokenizer vs the embedding, labels vs the head,
+                                     image size and channels vs the first layer. These crash on the
+                                     first batch, after the reservation; this says so before it.
 
 --data takes the size of YOUR training set (3M, 500k, 2B). Without it there is
 no price, because a cost with no workload behind it is a cost for somebody
@@ -303,7 +309,21 @@ if (opts.gen != null) {
 const inferOpts = { batch: batchSize, promptTokens: seqLen, genTokens, precision };
 /** The training-peak block runs on any of these; `--inference` replaces it. */
 const trainingSizing = !inference && (opts.data != null || batchSize != null || seqLen != null || opts.attention != null);
-const sizingAsked = inference || trainingSizing || opts.lora != null;
+// The data the caller describes. `--seq-len` is the same number the peak is
+// sized at, so it is checked against the position scheme whenever it is given.
+const DATA_FLAGS = [['seq-len', 'seqLen'], ['tokenizer-size', 'tokenizerSize'], ['classes', 'numClasses'], ['image-size', 'imageSize'], ['channels', 'channels']];
+const dataSpec = {};
+for (const [flag, key] of DATA_FLAGS) {
+  if (opts[flag] == null) continue;
+  const n = Number(opts[flag]);
+  if (!Number.isInteger(n) || n < 1) {
+    process.stderr.write(`\n  ${red('cannot read')} --${flag} ${opts[flag]}. Use a positive integer.\n`);
+    process.exit(2);
+  }
+  dataSpec[key] = n;
+}
+const dataAsked = Object.keys(dataSpec).length > 0;
+const sizingAsked = inference || trainingSizing || opts.lora != null || dataAsked;
 
 const modelId = positional[0];
 const result = await inspectHFModel(modelId);
@@ -332,6 +352,7 @@ if (flags.has('--json')) {
     const spec = specFromFlags({ lora: opts.lora, quant: opts.quant, fit: opts.fit, serve: opts.serve });
     if (spec) out.change = priceHFModel(f, { samples: 50_000, source: 'assumed' }, runFrom(gpuFromFlag(opts.gpu)), spec, attention, seqLen).plan.change;
     if (flags.has('--lora-targets')) out.lora = priceHFModel(f, { samples: 50_000, source: 'assumed' }).plan.lora;
+    if (dataAsked) out.dataFit = dataFitHFModel(f, dataSpec);
     return out;
   };
   const payload = result.ok
@@ -341,6 +362,7 @@ if (flags.has('--json')) {
         compare: `https://neurarch.com/compare?a=${encodeURIComponent(modelId)}&b=&utm_source=${SOURCE}`,
         publishedParams: result.hub.publishedParams,
         derivedParams: result.facts.derivedParams,
+        storedTwice: result.facts.storedTwice,
         ratio: result.facts.ratio,
         absDelta: result.facts.absDelta,
         tolerance: AGREE_TOLERANCE,
@@ -364,7 +386,7 @@ if (flags.has('--json')) {
         }
       : { ok: false, modelId, reason: result.reason };
   process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-  process.exit(payload.ok ? 0 : 1);
+  process.exit(payload.ok && !(payload.dataFit?.findings ?? []).some((f) => f.severity === 'block') ? 0 : 1);
 }
 
 if (!result.ok && !sizingOnly) {
@@ -404,6 +426,12 @@ if (sizingOnly) {
   // The two numbers, first, because nothing below matters if they disagree.
   process.stdout.write(`  ${dim('published (safetensors.total)')}  ${bold(humanParams(hub.publishedParams))}  ${dim(hub.publishedParams.toLocaleString())}\n`);
   process.stdout.write(`  ${dim('derived (config.json alone) ')}  ${bold(humanParams(facts.derivedParams))}  ${dim(facts.derivedParams.toLocaleString())}\n`);
+  // A tied matrix the file writes twice: read from the safetensors header,
+  // and the delta below already counts it. Same sentence the /m/ page prints.
+  if (facts.storedTwice) {
+    process.stdout.write(`  ${dim('stored twice in the file    ')}  ${bold(`+${humanParams(facts.storedTwice.extra)}`)}  ${dim(facts.storedTwice.extra.toLocaleString())}\n`);
+    process.stdout.write(`  ${yellow('!')} ${storedTwiceSentence(facts.storedTwice)}\n`);
+  }
 
   const deltaLine = `${sign}${pct.toFixed(2)}%`;
   if (facts.comparability !== 'comparable') {
@@ -435,6 +463,24 @@ if (sizingOnly) {
   }
 }
 
+// ── Does the data fit what the config accepts ───────────────────────────────
+//
+// Before memory, because a job that indexes past a table on its first batch
+// does not get far enough for its peak to matter.
+if (dataAsked) {
+  const fit = dataFitHFModel(facts, dataSpec);
+  const blocks = fit.findings.filter((f) => f.severity === 'block');
+  process.stdout.write(`\n  ${bold('data fit')} ${dim(`checked: ${fit.checked.join(', ') || 'nothing'}`)}\n`);
+  if (!fit.findings.length && fit.checked.length) process.stdout.write(`    ${green('fits')}  ${dim('every stated field is within what the config accepts')}\n`);
+  for (const f of fit.findings) {
+    process.stdout.write(`    ${f.severity === 'block' ? red('block') : yellow('warn ')} ${f.title}\n`);
+    process.stdout.write(`          ${dim(f.detail)}\n`);
+    process.stdout.write(`          ${dim(`fix: ${f.fix}`)}\n`);
+  }
+  for (const s of fit.skipped) process.stdout.write(`    ${dim(`not checked: ${s.check} (${s.reason})`)}\n`);
+  for (const b of blocks) blockers.push({ title: b.title });
+}
+
 // ── What an inference job needs ────────────────────────────────────────────
 //
 // Weights at the stated precision plus the KV cache at the last generated
@@ -503,14 +549,37 @@ if (trainingSizing) {
   } else {
     process.stdout.write(`\n  ${bold('training memory')} ${dim('(no price without --data)')}\n`);
   }
-  const fits = Object.entries(cost.gpuFits)
-    .map(([card, ok]) => `${ok === null ? dim(card) : ok ? green(card) : red(card)}`)
+  // Three answers per card: green fits on the conservative peak, yellow
+  // borderline (the estimate fits, the conservative peak does not: measure
+  // once), red does not fit. An older engine without `gpuVerdict` falls back
+  // to the point-estimate boolean.
+  const fits = Object.entries(cost.gpuVerdict ?? cost.gpuFits)
+    .map(([card, v]) => (v === null ? dim(`${card} n/a`) : v === 'fits' || v === true ? green(`${card} yes`) : v === 'borderline' ? yellow(`${card} borderline`) : red(`${card} no`)))
     .join('  ');
   const batchShown = /at batch (\d+)/.exec(cost.assumptions)?.[1] ?? '32';
   // The sequence length is printed because it moves the peak more than the
   // batch does: a config's context window is not a training length.
   const tokens = cost.seqLen != null ? `, ${cost.seqLen} tokens` : '';
   process.stdout.write(`    ${dim('fits          ')}  ${fits}  ${dim(`(${opts.lora != null ? 'full fine-tune ' : ''}training peak ~${cost.peakGb.toFixed(1)} GB at batch ${batchShown}${tokens}${cost.activationGb == null ? ', activations unknown' : ''}, 1.15x headroom)`)}\n`);
+  if (cost.peakGbUpper > 0) {
+    const u = cost.upperBound;
+    process.stdout.write(`    ${dim('upper bound   ')}  ${cost.peakGbUpper.toFixed(1)} GB ${dim(`(the estimate x ${u.multiplier}: held out by architecture, ${Math.round(u.coverage * 100)}% of ${u.runs} measured runs peaked at or under it)`)}\n`);
+    if (Object.values(cost.gpuVerdict ?? {}).includes('borderline')) {
+      process.stdout.write(`    ${dim('borderline    ')}  ${yellow('the estimate fits, the upper bound with 1.15x headroom does not: measure once (one step at this batch) before reserving')}\n`);
+    }
+    const mbs = cost.maxBatchSafe;
+    if (mbs && (mbs.T4 != null || mbs.A100_40 != null || mbs.H100_80 != null)) {
+      const v = (x) => (x == null ? 'n/a' : x.toLocaleString('en-US'));
+      process.stdout.write(`    ${dim('safe batch    ')}  T4 ${v(mbs.T4)}  A100_40 ${v(mbs.A100_40)}  H100_80 ${v(mbs.H100_80)} ${dim('(largest batch the upper bound fits)')}\n`);
+    }
+  }
+  if (cost.shareable) {
+    const sh = cost.shareable;
+    const pick = sh.cards.filter((c) => ['T4 (16GB)', 'A100 (40GB)', 'H100 (80GB)'].includes(c.gpu)).map((c) => `${c.copies} on ${gpuSlug(c.gpu)}`).join(', ');
+    const mig = [['A100-40', sh.mig.A100_40], ['A100-80', sh.mig.A100_80], ['H100', sh.mig.H100_80]].filter(([, p]) => p).map(([g, p]) => `${g} ${p}`).join(', ');
+    const anyCopy = sh.cards.some((c) => c.copies > 0);
+    process.stdout.write(`    ${dim('shareable     ')}  ${anyCopy ? pick : 'no listed card holds one copy'}${mig ? `; smallest MIG slice ${mig}` : ''} ${dim(`(${sh.perCopyGb.toFixed(1)} GB a copy; memory only, compute and bandwidth not considered)`)}\n`);
+  }
   if (opts.lora != null) process.stdout.write(`    ${dim('adapter       ')}  ${dim('the change record below sizes the LoRA run: frozen bf16 base, adapters with AdamW state, the same activations')}\n`);
   if (cost.seqLen != null && seqLen == null) {
     process.stdout.write(`    ${dim('tokens        ')}  ${dim(`${cost.seqLen} assumed (default ${DEFAULT_SEQ_LEN}, or the context if shorter); --seq-len to change`)}\n`);

package/engine.bundle.mjs

@@ -32737,16 +32737,16 @@ async function fetchDiffusersConfig(modelId) {
 }
 async function fetchHFModelConfig(modelId) {
   try {
-    const authHeaders = hfAuthHeaders();
+    const authHeaders2 = hfAuthHeaders();
     const configResponse = await fetch(
       `https://huggingface.co/${modelId}/resolve/main/config.json`,
-      { headers: authHeaders }
+      { headers: authHeaders2 }
     );
     if (configResponse.ok) {
       const raw = await configResponse.json();
       const config2 = normalizeAndAugmentConfig(raw, modelId);
       config2._configSource = "config";
-      config2._realParamCount = await fetchHFRealParamCount(modelId, authHeaders);
+      config2._realParamCount = await fetchHFRealParamCount(modelId, authHeaders2);
       return config2;
     }
     const diffusion = await fetchDiffusersConfig(modelId);
@@ -32754,7 +32754,7 @@ async function fetchHFModelConfig(modelId) {
       diffusion._configSource = diffusion._configSource ?? "diffusers";
       return diffusion;
     }
-    const apiResponse = await fetch(`https://huggingface.co/api/models/${modelId}`, { headers: authHeaders });
+    const apiResponse = await fetch(`https://huggingface.co/api/models/${modelId}`, { headers: authHeaders2 });
     const modelInfo = apiResponse.ok ? await apiResponse.json() : {};
     const modelIdLower = modelId.toLowerCase();
     const pipelineTag = modelInfo.pipeline_tag ?? "";
@@ -41719,8 +41719,50 @@ var MEMORY_CALIBRATION = {
   noFit: 131,
   /** Runs measured after the factors were fixed, never in any fit, and the median miss on the ones that fit, percent. */
   afterFitRuns: 25,
-  afterFitMedianPct: 14
+  afterFitMedianPct: 14,
+  /**
+   * The upper multiplier U: held out one architecture at a time, measured peak
+   * / predicted peak over the fitted runs of 1 GB or more, at the 90th and
+   * 95th percentile (nearest rank), rounded up to two decimals. Predicted x U
+   * is at or above the measured peak on that share of held-out runs.
+   */
+  upperK90: 1.17,
+  upperK95: 1.43,
+  /** Held-out runs (1 GB or more, measured peak) the multipliers were read from. */
+  upperRuns: 91
 };
+var UPPER_K = MEMORY_CALIBRATION.upperK95;
+var UPPER_COVERAGE = 0.95;
+var UPPER_FLOOR_GB = 1;
+function upperPeakGb(peakGb) {
+  if (!(peakGb > 0)) return 0;
+  return Math.max(peakGb * UPPER_K, UPPER_FLOOR_GB);
+}
+function fitVerdict(peakGb, params, gb2) {
+  if (params <= 0) return null;
+  if (upperPeakGb(peakGb) * FIT_HEADROOM <= gb2) return "fits";
+  return peakGb <= gb2 ? "borderline" : "does_not_fit";
+}
+var MIG_PROFILES = {
+  A100_40: [{ name: "1g.5gb", gb: 5 }, { name: "1g.10gb", gb: 10 }, { name: "2g.10gb", gb: 10 }, { name: "3g.20gb", gb: 20 }, { name: "4g.20gb", gb: 20 }, { name: "7g.40gb", gb: 40 }],
+  A100_80: [{ name: "1g.10gb", gb: 10 }, { name: "1g.20gb", gb: 20 }, { name: "2g.20gb", gb: 20 }, { name: "3g.40gb", gb: 40 }, { name: "4g.40gb", gb: 40 }, { name: "7g.80gb", gb: 80 }],
+  H100_80: [{ name: "1g.10gb", gb: 10 }, { name: "1g.20gb", gb: 20 }, { name: "2g.20gb", gb: 20 }, { name: "3g.40gb", gb: 40 }, { name: "4g.40gb", gb: 40 }, { name: "7g.80gb", gb: 80 }]
+};
+var MIG_SOURCE = "NVIDIA Multi-Instance GPU User Guide, Supported MIG Profiles";
+var SHAREABLE_NOTE = "Memory only: copies of the conservative peak (upper bound x 1.15 headroom each) that fit the card's memory. Compute, memory bandwidth and the per-process CUDA context are not considered.";
+function shareableFor(peakGbUpper) {
+  if (!(peakGbUpper > 0)) return null;
+  const per = peakGbUpper * FIT_HEADROOM;
+  const mig = (k) => MIG_PROFILES[k].find((p) => per <= p.gb)?.name ?? null;
+  return {
+    perCopyGb: per,
+    cards: PREFLIGHT_GPUS.map((g) => ({ gpu: g.name, gb: g.gb, copies: Math.floor(g.gb / per) })),
+    mig: { A100_40: mig("A100_40"), A100_80: mig("A100_80"), H100_80: mig("H100_80") },
+    migSource: MIG_SOURCE,
+    memoryOnly: true,
+    note: SHAREABLE_NOTE
+  };
+}
 var ACTIVATION_BYTES_PER_ELEMENT = 2;
 var ATTENTION_TYPES2 = /attention|transformerEncoder|transformerDecoder|^mla$|ditBlock|swin/i;
 var ALWAYS_STORES_SCORES = /^hstuBlock$/;
@@ -41938,6 +41980,10 @@ function fitsCard(peakGb, params, gb2) {
   if (params <= 0) return null;
   return peakGb * FIT_HEADROOM <= gb2;
 }
+function smallestSafeCardFor(peakGb, params) {
+  return PREFLIGHT_GPUS.find((g) => fitVerdict(peakGb, params, g.gb) === "fits")?.name ?? null;
+}
+var UPPER_BOUND = { multiplier: UPPER_K, coverage: UPPER_COVERAGE, runs: MEMORY_CALIBRATION.upperRuns, multiplier90: MEMORY_CALIBRATION.upperK90 };
 var ATTENTION_LABEL = { sdpa: "SDPA", flash: "flash attention", eager: "eager" };
 function attentionPhrase(attention, scoresGb) {
   if (scoresGb == null || !(scoresGb > 0.05)) return "";
@@ -42034,7 +42080,11 @@ function summaryFor(f, plan, diff, withheld) {
     parts.push(f.warnings.length ? `will run, ${f.warnings.length} warning${f.warnings.length === 1 ? "" : "s"}` : "will run");
     const fits = plan.cost.gpuFits;
     const smallest = plan.cost.smallestFitGpu ? `${/^[AEIOU]/i.test(plan.cost.smallestFitGpu) ? "an" : "a"} ${plan.cost.smallestFitGpu}` : fits.T4 ? "a T4" : fits.A100_40 ? "an A100 40GB" : fits.H100_80 ? "an H100 80GB" : null;
-    if (smallest) parts.push(`fits ${smallest} at batch ${batchOf(plan)}`);
+    const article = (g) => `${/^[AEIOU]/i.test(g) ? "an" : "a"} ${g}`;
+    const safe = plan.cost.smallestSafeGpu;
+    if (smallest && plan.cost.smallestFitGpu && safe !== plan.cost.smallestFitGpu) {
+      parts.push(`fits ${smallest} at batch ${batchOf(plan)}, borderline there (measure once; ${safe ? `${article(safe)} holds the upper bound` : "no listed card holds the upper bound"})`);
+    } else if (smallest) parts.push(`fits ${smallest} at batch ${batchOf(plan)}`);
     else if (fits.T4 === false) parts.push("does not fit a single 80GB card");
     if (f.estCostUsd != null) parts.push(`about ${fmtUsd(f.estCostUsd)} to train`);
   }
@@ -42096,6 +42146,12 @@ function unreadablePlan(blockers) {
       peakGb: 0,
       activationGb: null,
       smallestFitGpu: null,
+      peakGbUpper: 0,
+      upperBound: UPPER_BOUND,
+      gpuVerdict: { T4: null, A100_40: null, H100_80: null },
+      smallestSafeGpu: null,
+      maxBatchSafe: { T4: null, A100_40: null, H100_80: null },
+      shareable: null,
       maxBatch: { T4: null, A100_40: null, H100_80: null },
       twoCardSplit: null,
       attention: DEFAULT_ATTENTION,
@@ -42155,6 +42211,22 @@ function buildPlanUnchecked(model, base, opts) {
     A100_40: maxBatchFor(batchFacts, gpuGb("A100 (40GB)", 40)),
     H100_80: maxBatchFor(batchFacts, gpuGb("H100", 80))
   } : { T4: null, A100_40: null, H100_80: null };
+  const peakGbUpper = f.params > 0 ? upperPeakGb(f.peakGb) : 0;
+  const gpuVerdict = {
+    T4: fitVerdict(f.peakGb, f.params, gpuGb("T4", 16)),
+    A100_40: fitVerdict(f.peakGb, f.params, gpuGb("A100 (40GB)", 40)),
+    H100_80: fitVerdict(f.peakGb, f.params, gpuGb("H100", 80))
+  };
+  const safeFacts = {
+    footprintGb: f.footprintGb * UPPER_K,
+    activationPerSampleGb: elems == null ? null : activationGbAt(elems, 1) * UPPER_K,
+    activationGbAt: elems == null ? void 0 : (b) => activationGbAt(elems, b) * UPPER_K
+  };
+  const maxBatchSafe = f.params > 0 ? {
+    T4: maxBatchFor(safeFacts, gpuGb("T4", 16)),
+    A100_40: maxBatchFor(safeFacts, gpuGb("A100 (40GB)", 40)),
+    H100_80: maxBatchFor(safeFacts, gpuGb("H100", 80))
+  } : { T4: null, A100_40: null, H100_80: null };
   const cost = {
     estCostUsd: f.estCostUsd,
     estTrainSec: f.estTrainSec,
@@ -42164,6 +42236,12 @@ function buildPlanUnchecked(model, base, opts) {
     fitsGpu: f.fitsGpu,
     gpuFits,
     peakGb: f.peakGb,
+    peakGbUpper,
+    upperBound: UPPER_BOUND,
+    gpuVerdict,
+    smallestSafeGpu: f.params > 0 ? smallestSafeCardFor(f.peakGb, f.params) : null,
+    maxBatchSafe,
+    shareable: f.params > 0 ? shareableFor(peakGbUpper) : null,
     activationGb: f.activationGb,
     smallestFitGpu: f.smallestFitGpu,
     maxBatch,
@@ -43530,6 +43608,124 @@ init_toastStore();
 // scripts/architecture-pages.ts
 var STRUCTURAL_CHECKS = ADVISOR_RULE_IDS.length + GUARDRAIL_GATE_IDS.length;
 
+// scripts/storedHead.ts
+var TIE_DEFAULT_FALSE = /* @__PURE__ */ new Set([
+  "llama",
+  "mistral",
+  "mixtral",
+  "qwen2",
+  "qwen2_moe",
+  "qwen3",
+  "qwen3_moe",
+  "phi",
+  "phi3",
+  "olmo",
+  "olmo2",
+  "granite",
+  "stablelm",
+  "deepseek_v3",
+  "gpt_neox"
+]);
+var LM_SUBCONFIG = /^(text|llm|language|language_model|thinker|decoder)_config$/;
+function lmSubConfigs(config, depth = 0) {
+  if (depth > 3 || !config || typeof config !== "object") return [];
+  const out = [];
+  for (const [k, v] of Object.entries(config)) {
+    if (!v || typeof v !== "object" || Array.isArray(v)) continue;
+    if (LM_SUBCONFIG.test(k)) out.push(v);
+    out.push(...lmSubConfigs(v, depth + 1));
+  }
+  return out;
+}
+function isTied(config) {
+  if (typeof config.tie_word_embeddings === "boolean") return config.tie_word_embeddings;
+  const subs = lmSubConfigs(config);
+  const nested = subs.map((s) => s.tie_word_embeddings).filter((v) => typeof v === "boolean");
+  if (nested.length) return nested.every(Boolean);
+  const types = [config, ...subs].map((c) => String(c.model_type ?? ""));
+  return !types.some((t) => TIE_DEFAULT_FALSE.has(t));
+}
+var HEAD = /(^|\.)(lm_head|embed_out)\.weight$/;
+var EMBED = /(^|\.)(embed_tokens|wte|word_embeddings|tok_embeddings|embed_in)\.weight$/;
+function isCandidate(name) {
+  return HEAD.test(name) || EMBED.test(name);
+}
+function storedTwice(config, tensors) {
+  if (!isTied(config)) return null;
+  const heads = tensors.filter((t) => HEAD.test(t.name));
+  const embeds = tensors.filter((t) => EMBED.test(t.name));
+  for (const h of heads) {
+    const e = embeds.find((x) => x.shape.length === h.shape.length && x.shape.every((d, i) => d === h.shape[i]));
+    if (e) {
+      return { extra: h.shape.reduce((a, b) => a * b, 1), head: h.name, embedding: e.name, shape: [...h.shape] };
+    }
+  }
+  return null;
+}
+var HF = "https://huggingface.co";
+function authHeaders() {
+  const token = typeof process !== "undefined" ? process.env?.HF_TOKEN?.trim() : void 0;
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+async function readSafetensorsHeader(url, fetchImpl = fetch) {
+  try {
+    const r1 = await fetchImpl(url, { headers: { ...authHeaders(), Range: "bytes=0-7" } });
+    if (!r1.ok) return null;
+    const lenBuf = new Uint8Array(await r1.arrayBuffer()).slice(0, 8);
+    if (lenBuf.length < 8) return null;
+    const n2 = Number(new DataView(lenBuf.buffer).getBigUint64(0, true));
+    if (!(n2 > 0 && n2 < 1e8)) return null;
+    const r2 = await fetchImpl(url, { headers: { ...authHeaders(), Range: `bytes=8-${8 + n2 - 1}` } });
+    if (!r2.ok) return null;
+    const header = JSON.parse(new TextDecoder().decode(await r2.arrayBuffer()));
+    return Object.entries(header).filter(([k]) => k !== "__metadata__").map(([name, v]) => ({ name, shape: v?.shape ?? [] }));
+  } catch {
+    return null;
+  }
+}
+async function readStoredHead(modelId, fetchImpl = fetch) {
+  let info;
+  try {
+    const r = await fetchImpl(`${HF}/api/models/${modelId}`, { headers: authHeaders() });
+    if (!r.ok) return { error: `Hub API answered ${r.status}` };
+    info = await r.json();
+  } catch (e) {
+    return { error: `Hub API unreachable (${e.message})` };
+  }
+  const revision = String(info?.sha ?? "main");
+  const names = (info?.siblings ?? []).map((s) => String(s.rfilename));
+  const base = `${HF}/${modelId}/resolve/${revision}`;
+  let files;
+  if (names.includes("model.safetensors.index.json")) {
+    try {
+      const r = await fetchImpl(`${base}/model.safetensors.index.json`, { headers: authHeaders() });
+      if (!r.ok) return { error: `index answered ${r.status}` };
+      const idx = await r.json();
+      files = [...new Set(Object.entries(idx.weight_map ?? {}).filter(([k]) => isCandidate(k)).map(([, f]) => f))];
+    } catch (e) {
+      return { error: `index unreadable (${e.message})` };
+    }
+  } else {
+    files = names.filter((n2) => n2.endsWith(".safetensors") && !n2.includes("/"));
+  }
+  if (!files.length) return { error: "no root-level safetensors file" };
+  const tensors = [];
+  for (const f of files.sort()) {
+    const t = await readSafetensorsHeader(`${base}/${f}`, fetchImpl);
+    if (!t) return { error: `header of ${f} unreadable` };
+    tensors.push(...t.filter((x) => isCandidate(x.name)));
+  }
+  tensors.sort((a, b) => a.name.localeCompare(b.name));
+  return {
+    modelId,
+    revision,
+    files: files.sort(),
+    tensors,
+    source: `${HF}/${modelId}/tree/${revision}`,
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+}
+
 // scripts/model-pages.ts
 var AGREE_TOLERANCE = 0.02;
 var SIZING_CARDS = [
@@ -43559,7 +43755,8 @@ function sizingFor(model, plan) {
   const train = (fixed, gb2) => {
     if (fixed == null || perSample == null) return { kind: "unknown" };
     const b = maxBatchFor({ footprintGb: fixed, activationPerSampleGb: perSample }, gb2);
-    return b == null ? { kind: "none" } : { kind: "batch", batch: b };
+    const upper = maxBatchFor({ footprintGb: fixed * UPPER_K, activationPerSampleGb: perSample * UPPER_K }, gb2);
+    return b == null ? { kind: "none" } : { kind: "batch", batch: b, upperBatch: upper };
   };
   const cards = SIZING_CARDS.map(({ label, gb: gb2 }) => {
     let full = train(fullFixedGb, gb2);
@@ -43661,7 +43858,8 @@ function factsFor2(key, snap) {
   const derivedParams = plan.model.params;
   if (!derivedParams) return { skipped: `${key}: the reconstruction carries no parameters` };
   const { kind, caveat } = classify(snap.config);
-  const ratio = derivedParams / snap.publishedParams;
+  const twice = snap.storedTensors ? storedTwice(snap.config, snap.storedTensors.tensors) : null;
+  const ratio = (derivedParams + (twice?.extra ?? 0)) / snap.publishedParams;
   const absDelta = Math.abs(ratio - 1);
   const prop = propagateShapes(model);
   const structureSeqLen = tokenSeqLenOf(model);
@@ -43676,6 +43874,7 @@ function factsFor2(key, snap) {
     snap,
     plan,
     derivedParams,
+    storedTwice: twice,
     ratio,
     absDelta,
     comparability: kind,
@@ -43688,6 +43887,169 @@ function factsFor2(key, snap) {
     sizing: sizingFor(model, plan)
   };
 }
+function storedTwiceSentence(t) {
+  const n2 = t.extra >= 1e9 ? `${(t.extra / 1e9).toFixed(2)}B` : `${(t.extra / 1e6).toFixed(1)}M`;
+  return `The checkpoint stores the tied embedding twice: +${n2} (\`${t.head}\` and \`${t.embedding}\`, ${t.shape.join(" x ")}). The model has one such matrix and the count above has it once; the delta compares that count plus the second copy against the file.`;
+}
+
+// src/utils/configDataFit.ts
+var CLASSIFIER_ARCH = /For(Sequence|Token|Image|Audio|MultipleChoice)Classification$/;
+var posInt2 = (v) => {
+  const n2 = typeof v === "string" && v.trim() !== "" ? Number(v) : v;
+  return typeof n2 === "number" && Number.isInteger(n2) && n2 > 0 ? n2 : null;
+};
+function inputContractOf(model, config) {
+  const comps = model.components ?? [];
+  const first = (t) => comps.find((c) => c.type === t);
+  const source = {};
+  const emb = first("embedding");
+  const vocabSize = posInt2(emb?.params?.vocabSize);
+  if (vocabSize != null) source.vocabSize = "the token embedding";
+  const patch = first("patchEmbed");
+  const learned = first("learnedPositionalEmbedding");
+  let maxPositions = null;
+  let positionKind = null;
+  if (!patch) {
+    if (learned && posInt2(learned.params?.maxLen) != null) {
+      maxPositions = posInt2(learned.params?.maxLen);
+      positionKind = "learned";
+      source.maxPositions = "the learned position table";
+    } else if (posInt2(emb?.params?.maxSeqLen) != null) {
+      maxPositions = posInt2(emb?.params?.maxSeqLen);
+      positionKind = comps.some((c) => c.type === "rope") ? "rotary" : "declared";
+      source.maxPositions = positionKind === "rotary" ? "max_position_embeddings (rotary)" : "the declared maximum length";
+    }
+  }
+  let imageSize = null;
+  let channels = null;
+  if (patch) {
+    imageSize = posInt2(patch.params?.imgSize);
+    channels = posInt2(patch.params?.inChans);
+    if (imageSize != null) source.imageSize = "the patch embedding";
+    if (channels != null) source.channels = "the patch embedding";
+  } else if (!emb) {
+    const shape = first("input")?.params?.shape ?? null;
+    if (Array.isArray(shape) && shape.length === 3 && shape.every((x) => posInt2(x) != null)) {
+      channels = shape[0];
+      source.channels = "the input shape";
+    }
+  }
+  let numLabels = null;
+  const archs = Array.isArray(config?.architectures) ? config.architectures.map(String) : [];
+  if (archs.some((a) => CLASSIFIER_ARCH.test(a))) {
+    const id2label = config?.id2label;
+    numLabels = id2label && typeof id2label === "object" ? Object.keys(id2label).length || null : posInt2(config?.num_labels);
+    if (numLabels != null) source.numLabels = `the ${archs.find((a) => CLASSIFIER_ARCH.test(a))} head`;
+  } else if (!emb) {
+    const tail = [...comps].reverse().find((c) => !["output", "softmax", "dropout", "flatten", "activation", "relu"].includes(c.type));
+    if (tail?.type === "linear" && posInt2(tail.params?.outFeatures) != null) {
+      numLabels = posInt2(tail.params?.outFeatures);
+      source.numLabels = "the final Linear";
+    }
+  }
+  return { vocabSize, maxPositions, positionKind, numLabels, imageSize, channels, source };
+}
+function checkDataFit(contract, data) {
+  const checked = [];
+  const skipped = [];
+  const findings = [];
+  const c = contract;
+  if (data.seqLen != null) {
+    if (c.maxPositions == null) {
+      skipped.push({ check: "sequence length", reason: c.imageSize != null ? "a vision model: its position table is checked against the image size" : "the model declares no maximum length" });
+    } else {
+      checked.push("sequence length");
+      if (data.seqLen > c.maxPositions) {
+        if (c.positionKind === "learned") {
+          findings.push({
+            rule: "seq-over-positions",
+            severity: "block",
+            title: `Sequences of ${data.seqLen} tokens are longer than the ${c.maxPositions}-row position table`,
+            detail: `Position ids past ${c.maxPositions - 1} index outside a learned table, so the first batch that long raises an IndexError (a device-side assert on GPU) after the reservation is taken.`,
+            fix: `Truncate or chunk to ${c.maxPositions} tokens, or pick a model whose context covers ${data.seqLen}.`
+          });
+        } else {
+          findings.push({
+            rule: "seq-over-context",
+            severity: "warn",
+            title: `Sequences of ${data.seqLen} tokens are past the model's ${c.maxPositions}-token context`,
+            detail: c.positionKind === "rotary" ? "Rotary positions are computed, so the job runs; quality past the trained length is not something the config can vouch for, and attention memory grows with the length." : "The config declares this as the longest input; past it, behaviour depends on the implementation.",
+            fix: c.positionKind === "rotary" ? "Set rope_scaling for the longer context, or truncate to the trained length." : `Truncate to ${c.maxPositions} tokens.`
+          });
+        }
+      }
+    }
+  }
+  if (data.tokenizerSize != null) {
+    if (c.vocabSize == null) skipped.push({ check: "tokenizer size", reason: "the model has no token embedding" });
+    else {
+      checked.push("tokenizer size");
+      if (data.tokenizerSize > c.vocabSize) {
+        findings.push({
+          rule: "tokenizer-over-vocab",
+          severity: "block",
+          title: `The tokenizer has ${data.tokenizerSize} ids and the embedding has ${c.vocabSize} rows`,
+          detail: `Any of the ${data.tokenizerSize - c.vocabSize} ids past ${c.vocabSize - 1} indexes outside the embedding. The usual cause is special tokens added to the tokenizer without resizing the model.`,
+          fix: "Call model.resize_token_embeddings(len(tokenizer)) before training, and budget for the new rows."
+        });
+      }
+    }
+  }
+  if (data.numClasses != null) {
+    if (c.numLabels == null) skipped.push({ check: "label count", reason: "no classification head is visible in the config or the graph" });
+    else {
+      checked.push("label count");
+      if (data.numClasses > c.numLabels) {
+        findings.push({
+          rule: "labels-over-head",
+          severity: "block",
+          title: `The data has ${data.numClasses} labels and ${c.source.numLabels ?? "the head"} emits ${c.numLabels}`,
+          detail: `A label id of ${c.numLabels} or more is out of range for the loss, which on GPU is a device-side assert with no line number.`,
+          fix: `Load with num_labels=${data.numClasses} (and ignore_mismatched_sizes=True for a pretrained head).`
+        });
+      } else if (data.numClasses < c.numLabels) {
+        findings.push({
+          rule: "labels-under-head",
+          severity: "warn",
+          title: `The data has ${data.numClasses} labels and the head emits ${c.numLabels}`,
+          detail: "It runs; the extra outputs are never a target, which is usually a head left over from a different task.",
+          fix: `Load with num_labels=${data.numClasses} if the head is meant for this data.`
+        });
+      }
+    }
+  }
+  if (data.imageSize != null) {
+    if (c.imageSize == null) skipped.push({ check: "image size", reason: "the model has no fixed image size (no patch position table)" });
+    else {
+      checked.push("image size");
+      if (data.imageSize !== c.imageSize) {
+        findings.push({
+          rule: "image-size-mismatch",
+          severity: "block",
+          title: `Images are ${data.imageSize}px and the position table was built for ${c.imageSize}px`,
+          detail: "The patch count no longer matches the learned position table, so the forward pass raises on the first batch.",
+          fix: `Resize to ${c.imageSize}px, or pass interpolate_pos_encoding=True where the model supports it.`
+        });
+      }
+    }
+  }
+  if (data.channels != null) {
+    if (c.channels == null) skipped.push({ check: "channels", reason: "the model states no input channels" });
+    else {
+      checked.push("channels");
+      if (data.channels !== c.channels) {
+        findings.push({
+          rule: "channels-mismatch",
+          severity: "block",
+          title: `Images have ${data.channels} channel${data.channels === 1 ? "" : "s"} and the first layer expects ${c.channels}`,
+          detail: "The first convolution or patch projection has a fixed input-channel count; a mismatch raises on the first batch.",
+          fix: data.channels === 1 && c.channels === 3 ? "Repeat the grey channel to three in the transform." : `Convert the images to ${c.channels} channels.`
+        });
+      }
+    }
+  }
+  return { checked, skipped, findings, contract };
+}
 
 // src/utils/trainCost.ts
 init_paramEstimator();
@@ -43939,7 +44301,7 @@ async function rightsize(csv, opts = {}) {
   const cache = /* @__PURE__ */ new Map();
   const results = [];
   for (const j of parsed.jobs) {
-    const empty = { batch: null, hours: null, seqLen: null, loraRank: null, attention: null, peakGb: null, needGb: null, smallestCard: null, rightSized: null, spentUsd: 0, savedUsd: 0, plan: null, params: null };
+    const empty = { batch: null, hours: null, seqLen: null, loraRank: null, attention: null, peakGb: null, needGb: null, smallestCard: null, upperNeedGb: null, fit: null, rightSized: null, spentUsd: 0, savedUsd: 0, plan: null, params: null };
     if ("error" in j) {
       results.push({ jobId: j.jobId, model: j.model, requested: null, ...empty, verdict: "unknown", reason: j.error });
       continue;
@@ -43967,17 +44329,24 @@ async function rightsize(csv, opts = {}) {
       continue;
     }
     const needGb = sized.peakGb * HEADROOM2;
+    const upperNeedGb = upperPeakGb(sized.peakGb) * HEADROOM2;
     const c = classify2(needGb, req, cards);
-    const savedUsd2 = c.verdict === "over" && c.rightSized ? Math.max(0, (req.hourly - c.rightSized.hourly) * j.hours) : 0;
+    const restsOn = c.verdict === "over" ? c.rightSized : c.verdict === "right-sized" ? req : null;
+    const fit = restsOn == null ? null : upperNeedGb <= restsOn.gb ? "fits" : "borderline";
+    const claim = fit === "borderline" && c.verdict === "over" ? classify2(upperNeedGb, req, cards) : c;
+    const savedUsd2 = claim.verdict === "over" && claim.rightSized ? Math.max(0, (req.hourly - claim.rightSized.hourly) * j.hours) : 0;
     const p = sized.plan.cost;
+    const measure = `borderline: the upper bound (${upperNeedGb.toFixed(1)} GB with headroom, ${Math.round(UPPER_COVERAGE * 100)}% of held-out runs) does not fit ${restsOn?.gb ?? 0} GB; measure once`;
     results.push({
       ...base,
       seqLen,
       verdict: c.verdict,
-      reason: c.verdict === "under" ? `predicted peak ${sized.peakGb.toFixed(1)} GB x ${HEADROOM2} does not fit ${req.gb} GB: the job OOMed or relied on something the graph does not declare` : c.verdict === "right-sized" ? null : `${c.rightSized.gb} GB holds the ${needGb.toFixed(1)} GB the job needed` + (c.rightSized.count < req.count ? `; ${req.count} cards to ${c.rightSized.count}: the same work on fewer cards takes longer, so read the figure as capacity reserved and not needed` : ""),
+      reason: c.verdict === "under" ? `predicted peak ${sized.peakGb.toFixed(1)} GB x ${HEADROOM2} does not fit ${req.gb} GB: the job OOMed or relied on something the graph does not declare` : c.verdict === "right-sized" ? fit === "borderline" ? measure : null : `${c.rightSized.gb} GB holds the ${needGb.toFixed(1)} GB the job needed` + (c.rightSized.count < req.count ? `; ${req.count} cards to ${c.rightSized.count}: the same work on fewer cards takes longer, so read the figure as capacity reserved and not needed` : "") + (fit === "borderline" ? `; ${measure}, so the not-needed figure is claimed only down to ${claim.verdict === "over" && claim.rightSized ? labelOf(claim.rightSized) : "the request itself"}, which holds the upper bound` : ""),
       peakGb: sized.peakGb,
       needGb,
       smallestCard: c.smallestCard,
+      upperNeedGb,
+      fit,
       rightSized: c.rightSized ? { ...c.rightSized, label: labelOf(c.rightSized) } : null,
       savedUsd: savedUsd2,
       plan: { peakGb: p.peakGb, activationGb: p.activationGb, smallestFitGpu: p.smallestFitGpu, maxBatch: p.maxBatch, twoCardSplit: p.twoCardSplit },
@@ -44001,7 +44370,7 @@ async function rightsize(csv, opts = {}) {
     prices: { cards, overridden: opts.overridden ?? [], source: PRICE_SOURCE }
   };
 }
-var METHOD = `Needed memory is the training peak \`buildPlan\` predicts from the graph: weights, gradients and optimizer state (${OPTIMIZER_K} x 16 bytes per parameter) plus activations (fitted factors on every layer's output, the intermediates inside each layer, recurrent gate states, the largest tensor's backward copy, and stored attention scores), with ${HEADROOM2}x headroom for allocator fragmentation and the CUDA context. It estimates the training peak under AdamW with bf16 autocast; inference jobs and other optimizers will differ. ${calibrationSentence()} (every run: https://www.neurarch.com/memory-calibration.html). The score term counts only the attention score matrices eager attention stores for backward; PyTorch SDPA (the Hugging Face default) and flash attention do not keep them, so the plan, like every other plan, leaves that term out unless the CSV's attention column says eager. Token models are sized at the CSV's seq_len, or ${DEFAULT_SEQ_LEN} tokens (the model's context if shorter) when it is blank. A job with lora_rank is sized with the base frozen in bf16 (2 bytes per parameter) and adapters on every Linear but the head carrying AdamW state. A multi-card job is sized as one model sharded across its cards (FSDP / ZeRO-3 style): the peak at the global batch (per-device batch x cards) against the summed capacity. Plain DDP keeps a full copy on every card, so for a DDP job read the single-card peak at the per-device batch instead. A request is right-sized when it is the smallest capacity that holds the peak or one size up; the right-sized request is the cheapest single card that holds it, and several cards only when no single card does. The not-needed figure assumes the same wall hours: a slower card can lengthen a run, so the figure is reservation capacity paid for and not needed, not a promise about a cheaper run.`;
+var METHOD = `Needed memory is the training peak \`buildPlan\` predicts from the graph: weights, gradients and optimizer state (${OPTIMIZER_K} x 16 bytes per parameter) plus activations (fitted factors on every layer's output, the intermediates inside each layer, recurrent gate states, the largest tensor's backward copy, and stored attention scores), with ${HEADROOM2}x headroom for allocator fragmentation and the CUDA context. It estimates the training peak under AdamW with bf16 autocast; inference jobs and other optimizers will differ. ${calibrationSentence()} (every run: https://www.neurarch.com/memory-calibration.html). The score term counts only the attention score matrices eager attention stores for backward; PyTorch SDPA (the Hugging Face default) and flash attention do not keep them, so the plan, like every other plan, leaves that term out unless the CSV's attention column says eager. Token models are sized at the CSV's seq_len, or ${DEFAULT_SEQ_LEN} tokens (the model's context if shorter) when it is blank. A job with lora_rank is sized with the base frozen in bf16 (2 bytes per parameter) and adapters on every Linear but the head carrying AdamW state. A multi-card job is sized as one model sharded across its cards (FSDP / ZeRO-3 style): the peak at the global batch (per-device batch x cards) against the summed capacity. Plain DDP keeps a full copy on every card, so for a DDP job read the single-card peak at the per-device batch instead. A request is right-sized when it is the smallest capacity that holds the peak or one size up; the right-sized request is the cheapest single card that holds it, and several cards only when no single card does. The not-needed figure assumes the same wall hours: a slower card can lengthen a run, so the figure is reservation capacity paid for and not needed, not a promise about a cheaper run. Every verdict is also checked against the conservative peak, the estimate x ${UPPER_K} (held out by architecture, ${Math.round(UPPER_COVERAGE * 100)}% of measured runs of 1 GB or more peaked at or under it): a row whose capacity holds the estimate and not the conservative peak is marked borderline ("measure once"), and an over row that is borderline claims as not needed only what the conservative peak would free.`;
 var DOES_NOT_KNOW = [
   "Data loader memory: pinned host buffers, prefetch queues and worker processes on the GPU host.",
   "Custom kernels beyond the attention column: fused optimizers, fused losses and other custom ops can add or remove memory it does not see.",
@@ -44034,7 +44403,7 @@ function renderMarkdown(r) {
       j.attention === "eager" ? "eager attention" : ""
     ].filter(Boolean).join(", ");
     const note = [extras, j.reason ?? ""].filter(Boolean).join("; ");
-    L.push(`| ${md(j.jobId)} | ${md(j.model)} | ${j.requested?.label ?? ""} | ${j.batch ?? ""} | ${j.hours ?? ""} | ${gb(j.needGb)} | ${j.smallestCard ?? (j.needGb != null ? "none single" : "")} | ${j.verdict} | ${j.verdict === "over" ? j.rightSized?.label ?? "" : j.verdict === "right-sized" ? "as requested" : ""} | ${usd(j.spentUsd)} | ${j.savedUsd > 0 ? usd(j.savedUsd) : "-"} | ${md(note)} |`);
+    L.push(`| ${md(j.jobId)} | ${md(j.model)} | ${j.requested?.label ?? ""} | ${j.batch ?? ""} | ${j.hours ?? ""} | ${gb(j.needGb)} | ${j.smallestCard ?? (j.needGb != null ? "none single" : "")} | ${j.verdict}${j.fit === "borderline" ? " (borderline)" : ""} | ${j.verdict === "over" ? j.rightSized?.label ?? "" : j.verdict === "right-sized" ? "as requested" : ""} | ${usd(j.spentUsd)} | ${j.savedUsd > 0 ? usd(j.savedUsd) : "-"} | ${md(note)} |`);
   }
   L.push("", "## Method", "", METHOD, "");
   L.push("## Prices", "", `Default: ${r.prices.source}.` + (r.prices.overridden.length ? ` Overridden by --prices: ${r.prices.overridden.join(", ")}.` : " Pass --prices to use your own rates."), "");
@@ -44107,10 +44476,10 @@ var GIANT_REQUEST_SHARE = 0.2;
 var HEADROOM3 = 1.15;
 var LATE_STEP = 5;
 var f2 = (x) => x >= 10 ? x.toFixed(1) : x.toFixed(2);
-function batchThatFits(facts, cardGb) {
+function batchThatFits(facts, cardGb, k = 1) {
   const { footprintGb, activationPerSampleGb } = facts;
   if (footprintGb == null || activationPerSampleGb == null || !(activationPerSampleGb > 0)) return null;
-  const b = Math.floor((cardGb / HEADROOM3 - footprintGb) / activationPerSampleGb);
+  const b = Math.floor((cardGb / HEADROOM3 - footprintGb * k) / (activationPerSampleGb * k));
   return b >= 1 ? b : null;
 }
 function inferenceSizeFixes(facts, cardGb) {
@@ -44246,6 +44615,33 @@ function diagnoseOom(text, facts = {}) {
       ]
     );
   }
+  if (!inference && card != null && facts.predictedPeakGb != null && facts.predictedUpperGb != null && facts.predictedUpperGb * HEADROOM3 > card && !(facts.step != null && facts.step > LATE_STEP)) {
+    const k = facts.upperK ?? facts.predictedUpperGb / facts.predictedPeakGb;
+    const cov = facts.upperCoverage != null ? `${Math.round(facts.upperCoverage * 100)}% of held-out measured runs peaked at or under it` : "the conservative estimate";
+    evidence.push(`the conservative peak is ${f2(facts.predictedUpperGb)} GB (${f2(facts.predictedUpperGb * HEADROOM3)} GB with headroom): ${cov}`);
+    const fixes = [];
+    const b = batchThatFits(facts, card, k);
+    if (b != null && facts.batch != null && b < facts.batch) {
+      let micro = b;
+      while (micro > 1 && facts.batch % micro !== 0) micro--;
+      const accum = facts.batch / micro;
+      fixes.push({
+        action: `batch ${micro} with gradient accumulation of ${accum} steps`,
+        because: `${b} is the largest batch whose conservative peak fits ${f2(card)} GB with ${Math.round((HEADROOM3 - 1) * 100)}% headroom; ${micro} x ${accum} keeps the effective batch at ${facts.batch}`,
+        changesTraining: false
+      });
+    }
+    fixes.push({
+      action: "measure one step before the full run: log torch.cuda.max_memory_allocated() after the first optimizer step",
+      because: "at the edge of a card the estimate is a fit check, not a precise number; one measured step settles it",
+      changesTraining: false
+    });
+    return result(
+      "borderline",
+      `The job was borderline on this card: the predicted peak of ${f2(facts.predictedPeakGb)} GB fits ${f2(card)} GB with headroom, but the conservative peak of ${f2(facts.predictedUpperGb)} GB does not. This out-of-memory is inside the estimate's own error, not evidence of memory the model does not declare.`,
+      fixes
+    );
+  }
   if (card != null && facts.predictedPeakGb != null && facts.predictedPeakGb <= card * FITS_WITH_ROOM) {
     const late = facts.step != null && facts.step > LATE_STEP;
     return result(
@@ -44295,6 +44691,9 @@ function factsFor3(model, batch, seqLen, attention, step) {
   const act = plan.cost.activationGb;
   return {
     predictedPeakGb: plan.cost.peakGb,
+    predictedUpperGb: plan.cost.peakGbUpper,
+    upperK: plan.cost.upperBound.multiplier,
+    upperCoverage: plan.cost.upperBound.coverage,
     footprintGb: act != null ? plan.cost.peakGb - act : null,
     activationPerSampleGb: act != null && batch > 0 ? act / batch : null,
     batch,
@@ -44374,6 +44773,9 @@ function graphOfFacts(facts) {
     updatedAt: ""
   };
 }
+function dataFitHFModel(facts, data) {
+  return checkDataFit(inputContractOf(graphOfFacts(facts), facts.snap.config), data);
+}
 function inferHFModel(facts, opts) {
   const model = graphOfFacts(facts);
   const prompt = opts.promptTokens ?? withSeqLen(model, null).seqLen ?? DEFAULT_SEQ_LEN;
@@ -44441,6 +44843,8 @@ async function inspectHFModel(modelId, fetchImpl = fetch) {
     fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
     config
   };
+  const stored = await readStoredHead(modelId, fetchImpl);
+  snap.storedTensors = "error" in stored ? null : { tensors: stored.tensors, source: stored.source, fetchedAt: stored.fetchedAt };
   const facts = factsFor2(keyFor(modelId), snap);
   if ("skipped" in facts) return { ok: false, hub, reason: facts.skipped };
   return { ok: true, hub, facts };
@@ -44458,6 +44862,7 @@ export {
   PRICE_SOURCE,
   applyPrices,
   attentionPhrase,
+  dataFitHFModel,
   graphOfFacts,
   headline,
   inferHFModel,
@@ -44473,7 +44878,8 @@ export {
   renderMarkdown,
   renderOomText,
   rightsize,
-  specFromFlags
+  specFromFlags,
+  storedTwiceSentence
 };
 /*! Bundled license information:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neurarch",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Know what a GPU job needs before it takes a reservation: training peak memory, the smallest card that holds it and what a run costs, read from a Hugging Face config or a traced graph. `neurarch rightsize jobs.csv` puts each past job's request next to what it needed.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -8,10 +8,10 @@
   "homepage": "https://neurarch.com/memory-calibration.html",
   "repository": {
     "type": "git",
-    "url": "https://github.com/neurarch-ai/neurarch"
+    "url": "git+https://github.com/neurarch-ai/neurarch.git"
   },
   "bin": {
-    "neurarch": "./bin/neurarch.mjs"
+    "neurarch": "bin/neurarch.mjs"
   },
   "files": [
     "bin",