neurarch 0.1.0 → 0.1.1

package/README.md

@@ -188,7 +188,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

@@ -19,7 +19,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 } 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
@@ -341,6 +341,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,
@@ -404,6 +405,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') {
@@ -503,14 +510,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,10 @@ 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/trainCost.ts
 init_paramEstimator();
@@ -43939,7 +44142,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 +44170,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 +44211,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 +44244,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 +44317,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 +44456,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 +44532,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,
@@ -44441,6 +44681,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 };
@@ -44473,7 +44715,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.1",
   "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",