snowspeeder/roast_command_center
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add per-user learned machine profile; fix methodology honesty issues
Test and deploy / test-and-deploy (push) Successful in 1m26s
Details

Browse Source 
Replaces the flat additive batch-size correction with a per-user
multiplicative pace factor learned from each account's own logged
roasts (shared/learn.js, GET /api/machine-profile), plus a lot-scoped
"last refine" auto-suggestion. Also fixes the reference data being
framed as "your own roasts" on a now-multi-user product, and
reclassifies the drying/Maillard sanity checks as informational since
they're algebraically derived from the DTR check rather than
independent (yellow = 0.56 x first crack, not entered separately).

Bug fixes found by an adversarial Opus review of the first pass:
- Unicode minus sign (U+2212) broke duration parsing against the
  app's own generated refine-suggestion text
- Printed sanity-checks table still showed a bare pass/fail glyph for
  the now-informational drying/Maillard rows
- Printed time-ledger box didn't show the pace multiplication step,
  so it stopped reconciling by hand once pace != 1
- Field 6.4 (manual batch correction) was double-counted: excluded
  from the learned-pace fit but added back after the multiplication
- Learned pace had no outlier rejection or hard clamp
- computeLedger had no test coverage
- Batch-size help copy overstated what the pace factor models (it's
  a single blanket ratio, not conditioned on batch weight)

A follow-up Opus pass also caught the per-user profile cache
surviving logout/account-switch in a shared browser; fixed by
sweeping it alongside the existing plan-draft cleanup.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
This commit is contained in:
snowspeeder
2026-07-31 12:40:03 -04:00
co-authored by Claude Sonnet 5
parent 0a0356b86e
commit 2237c199c1
14 changed files with 999 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public/js/field-help-content.js
+119 -53
View File
@@ -755,15 +755,38 @@ export const HELP_TOPICS = {
const label = input?.closest(".ledger-row")?.querySelector(".l-label");
return label ? [label] : [];
},
render(_plan, unit) {
render(_plan, unit, profile) {
const pace = profile?.pace;
const paceText =
pace?.source === "learned"
? `Your own account is currently running at ${pace.value.toFixed(2)}× the reference ` +
`pace (learned from ${pace.n} of your logged roasts) — that factor scales your ` +
"whole first-crack line by how fast your roasts have actually run overall. It's a " +
"single blanket ratio across your history, not something that adjusts itself by " +
"batch weight, so this table's specific charge/heat/fan settings are still worth " +
"reading as the reference operator's own notes, not something the learned pace " +
"stands in for."
: "This app now applies a learned per-user pace factor to first crack instead of a " +
"flat added-seconds guess (below, it defaults to 1× until you've logged at least " +
"two roasts with an actual first-crack time). That factor tracks how fast your " +
"machine runs overall — it isn't conditioned on batch weight — so the specific " +
"settings in this table are still the reference operator's own charge/heat/fan " +
"choices, not derived from your machine.";
return frag(
p(
"Batch size is the strongest correlate with first-crack time in your logged data " +
"(r = +0.67). Your logs: 225 g lands first crack roughly 1:30–2:00 later than 200 g " +
"at similar settings — the 226 g batches sat at 11:16 and 12:24 when nothing at 200 g " +
"went past 10:33. Enter the correction for your green weight versus the reference " +
"weights below.",
"Batch size was the strongest correlate with first-crack time in the reference " +
"operator's own logged data (r = +0.67): a 226 g batch landed first crack roughly " +
"1:30–2:00 later than 200 g at similar settings — a ~13% weight increase stretching " +
"first crack ~40%, a scaling relationship a flat added-seconds guess can't fully " +
"represent. Field 6.4 below is still that same flat additive guess — you still " +
"enter it by hand for your own batch, and it's now folded into the line that the " +
"learned pace factor scales, so it moves by that factor too. What's new is a " +
"separate learned pace factor (below) that scales your entire first-crack line by " +
"how fast your account's roasts have actually run — but it's one blanket ratio " +
"across your whole history, not a per-batch-weight adjustment, so it doesn't replace " +
"6.4 for batch-to-batch changes.",
),
p(paceText),
buildTable({
cols: [
{ label: "Batch", key: "batch" },
@@ -785,7 +808,7 @@ export const HELP_TOPICS = {
},
"milestones-ror": {
title: "Milestones & the RoR budget — your machine's proven numbers",
title: "Milestones & the RoR budget — proven numbers, learned or reference",
targets: [],
place() {
const subheads = [...document.querySelectorAll("#sec-machine .subhead")];
@@ -794,24 +817,49 @@ export const HELP_TOPICS = {
console.warn('field-help: "milestones-ror" fell back to positional lookup — subhead text changed?');
return subheads[0] ? [subheads[0]] : [];
},
render(_plan, unit) {
render(_plan, unit, profile) {
const t = (c) => convTemp(c, unit);
const d = (c) => convDelta(c, unit);
const u = unitLabel(unit);
const ru = rateUnitLabel(unit);
const rows = [
{ milestone: "Charge", median: `${t(MACHINE.charge.medianC)} ${u}`, range: `${t(MACHINE.charge.rangeC[0])}–${t(MACHINE.charge.rangeC[1])} ${u}`, note: "The probe reading when beans go in, i.e. your preheat. Higher for larger batches." },
{ milestone: "Turning point", median: `${t(MACHINE.turningPoint.medianC)} ${u} @ ${MACHINE.turningPoint.medianTime}`, range: `${t(MACHINE.turningPoint.rangeC[0])}–${t(MACHINE.turningPoint.rangeC[1])} ${u} @ ${MACHINE.turningPoint.rangeTime}`, note: "Falls out of charge temperature and batch mass; you don't set it directly. A TP much past 1:05 at 200 g means you charged cool." },
{ milestone: "Yellow", median: `${t(MACHINE.yellow.medianC)} ${u}`, range: `${t(MACHINE.yellow.rangeC[0])}–${t(MACHINE.yellow.rangeC[1])} ${u}`, note: "Threshold-derived in your logs, not observed. Use as a rough guide and start calling it by eye — grassy smell turns to bread, colour goes straw." },
{ milestone: "First crack", median: `${t(MACHINE.firstCrack.medianC)} ${u}`, range: `${t(MACHINE.firstCrack.rangeC[0])}–${t(MACHINE.firstCrack.rangeC[1])} ${u}`, note: "Tight and reliable across all your lots. This is your most trustworthy single number." },
{ milestone: "Drop (light)", median: `${t(MACHINE.drop.medianC)} ${u}`, range: `${t(MACHINE.drop.rangeC[0])}–${t(MACHINE.drop.rangeC[1])} ${u}`, note: `All your logged roasts are light. For darker levels, build the ladder yourself: raise drop ${d(2)}–${d(3)} ${u}, weigh, record — don't extrapolate.` },
const milestoneDefs = [
{ label: "Charge", ref: MACHINE.charge, learnedKey: "charge", timeSuffix: "", note: "The probe reading when beans go in, i.e. your preheat. Higher for larger batches." },
{ label: "Turning point", ref: MACHINE.turningPoint, learnedKey: "tp", timeSuffix: ` @ ${MACHINE.turningPoint.medianTime}`, rangeTimeSuffix: ` @ ${MACHINE.turningPoint.rangeTime}`, note: "Falls out of charge temperature and batch mass; you don't set it directly. A TP much past 1:05 at 200 g means you charged cool." },
{ label: "Yellow", ref: MACHINE.yellow, learnedKey: "yellow", timeSuffix: "", note: "Threshold-derived, not observed. Use as a rough guide and start calling it by eye — grassy smell turns to bread, colour goes straw." },
{ label: "First crack", ref: MACHINE.firstCrack, learnedKey: "fc", timeSuffix: "", note: "Tight and reliable in the reference log. Usually the single most trustworthy number here." },
{ label: "Drop (light)", ref: MACHINE.drop, learnedKey: "drop", timeSuffix: "", note: `For darker levels, build the ladder yourself: raise drop ${d(2)}–${d(3)} ${u}, weigh, record — don't extrapolate.` },
];
// Each milestone falls back to the reference band independently — a user might have
// enough of their own First crack readings to trust long before they bother recording
// Turning point, so this isn't a single all-or-nothing learned/reference switch.
const rows = milestoneDefs.map(({ label, ref, learnedKey, timeSuffix, rangeTimeSuffix, note }) => {
const learned = profile?.bands?.[learnedKey];
const useLearned = learned?.source === "learned";
const medianC = useLearned ? learned.medianC : ref.medianC;
const rangeC = useLearned ? learned.rangeC : ref.rangeC;
return {
milestone: useLearned ? `${label} (n=${learned.n})` : label,
median: `${t(medianC)} ${u}${timeSuffix}`,
range: `${t(rangeC[0])}–${t(rangeC[1])} ${u}${rangeTimeSuffix ?? timeSuffix}`,
note,
};
});
const anyLearned = profile?.bandsSource === "learned";
const introText = anyLearned
? "The rows marked (n=…) below are learned from your own logged roasts on this " +
"account; the rest still use the reference operator's original Hottop log until " +
"you've recorded enough actual temperatures of your own. The times and ratios in " +
"this app port between similar drum roasters; the temperatures never do — they're " +
"whichever machine and probe actually produced them."
: "These bands are the reference operator's original 14 Hottop KN-8828B-2K+ roasts — " +
"not yours, unless you're them. They'll start being replaced by your own account's " +
"figures automatically once you log actual temperatures at each milestone. The times " +
"and ratios in this app port between similar drum roasters; the temperatures never do.";
return frag(
p(
"These bands are from your own logged roasts — the same machine, probe and operator. " +
"The times and ratios in this app port between machines; the temperatures do not. " +
`Your probe reads first crack at ${t(176)}–${t(187)} ${u}, well below the ~${t(196)} ${u} ` +
"a fast, well-immersed probe would show; that doesn't make it wrong, it makes it yours.",
`${introText} Reference first crack reads ${t(176)}–${t(187)} ${u}, well below the ` +
`~${t(196)} ${u} a fast, well-immersed probe would show; that doesn't make it wrong, ` +
"it makes it that probe's own.",
),
buildTable({
cols: [
@@ -912,22 +960,25 @@ export const HELP_TOPICS = {
"change now shows up about a minute from now.",
}),
aside({
tag: "What your logs will NOT tell you",
tag: "What the reference operator's own logs do NOT tell you",
warn: true,
text:
'"More heat before yellow gives an earlier first crack" does not hold in your data — ' +
"heat delivered before yellow correlates positively with first-crack time (r = +0.43) " +
"because it's partly a proxy for elapsed time; average heat rate shows almost none " +
"(r = +0.20). The honest correlates are batch size (+0.67) and time to yellow (+0.59) " +
"— both descriptive, neither causal. The taper is a starting shape, not a validated " +
"control law: for a real lever, vary only the time of the first heat cut across three " +
"batches of the same coffee.",
'"More heat before yellow gives an earlier first crack" does not hold in the reference ' +
"operator's 14-roast log — heat delivered before yellow correlates positively with " +
"first-crack time (r = +0.43) because it's partly a proxy for elapsed time; average " +
"heat rate shows almost none (r = +0.20). The honest correlates there are batch size " +
"(+0.67) and time to yellow (+0.59) — both descriptive, neither causal, and specific " +
"to that one operator's machine. The taper is a starting shape, not a validated " +
"control law: for a real lever on your own machine, vary only the time of the first " +
"heat cut across three batches of the same coffee and see what actually moves.",
}),
h4("Fan, measured causally"),
p(
`Isolated fan steps with the burner held steady give roughly ${MACHINE.fanEffectCPerMinPer10Pct} ` +
"°C/min of RoR per +10% fan. Only 5 clean windows across 4 roasts — but it is the one " +
"number here from a controlled comparison rather than a correlation.",
`On the reference machine, isolated fan steps with the burner held steady gave roughly ` +
`${MACHINE.fanEffectCPerMinPer10Pct} °C/min of RoR per +10% fan — only 5 clean windows ` +
"across 4 roasts, but the one number in this reference set from a controlled " +
"comparison rather than a correlation. Worth re-measuring on your own machine before " +
"trusting it there.",
),
h4("The plant model"),
formula("RoR (°C/min) = 0.0903 × (0.988·H + 0.215·F + 167.0 − BT)"),
@@ -935,10 +986,11 @@ export const HELP_TOPICS = {
p("H = heat %, F = fan %, BT = bean temp °C; above 178 °C add ~+1.4 °C/min for the exotherm."),
p(
"Treat it as a sanity check on direction and rough magnitude, not a setpoint calculator: " +
"it carries a ±5 °C band, a 60-second dead time, was fitted on light roasts of " +
"200–226 g, and its fan term's sign is wrong for planning (fitted from closed-loop " +
"data — use the −1.3 figure instead). Where the equation and your logs disagree, " +
"believe your logs.",
"it carries a ±5 °C band, a 60-second dead time, was fitted on the reference " +
"operator's light roasts of 200–226 g, and its fan term's sign is wrong for planning " +
"(fitted from closed-loop data — use the −1.3 figure instead). Where the equation and " +
"your own logged roasts disagree, believe your logs — this formula is a planning aid " +
"borrowed from someone else's machine, not a law.",
),
);
},
@@ -950,8 +1002,10 @@ export const HELP_TOPICS = {
render() {
return frag(
p(
"Four checks stand between an arithmetically valid plan and a roastable one. A fail " +
"sends you back to the ledger — never to the machine.",
"Two of these are real checks that stand between an arithmetically valid plan and a " +
"roastable one — a fail sends you back to the ledger, never to the machine. The " +
"other two (drying share, Maillard share) are shown for context only; see the aside " +
"below for why.",
),
buildTable({
cols: [
@@ -962,21 +1016,20 @@ export const HELP_TOPICS = {
],
rows: [
{
check: "Drying share",
check: "Drying share (informational)",
compute: "yellow ÷ drop",
should: `${SANITY_BANDS.drying.lo}–${SANITY_BANDS.drying.hi}%`,
meaning:
"High → yellow is late and you are spending the roast drying instead of " +
"browning; Maillard gets starved. Low → you rushed to yellow and the internal " +
"pressure never built.",
"Can't fail independently of DTR (see below) — shown for context. High → " +
"yellow reads late relative to drop; low → yellow reads early.",
},
{
check: "Maillard share",
check: "Maillard share (informational)",
compute: "maillard ÷ drop",
should: `${SANITY_BANDS.maillard.lo}–${SANITY_BANDS.maillard.hi}%`,
meaning:
"Low → too small a browning window for sweetness and complexity to develop. " +
"Usually the mirror image of a drying share that ran long.",
"Same derivation as drying share, so the same caveat applies. Mirrors it: " +
"whichever way drying share leans, this leans the other.",
},
{
check: "Development ratio",
@@ -994,6 +1047,18 @@ export const HELP_TOPICS = {
},
],
}),
aside({
tag: "Why drying share and Maillard share stopped being pass/fail",
text:
"Yellow is never entered independently in this app — it's always derived as " +
"0.56 × first crack (see Anchor & profile). That means drying% = 0.56 × (A ÷ D) and " +
"Maillard% = 0.44 × (A ÷ D): both are pure algebra on the DTR check, not separate " +
"measurements. Whenever DTR passes, the arithmetic guarantees drying lands in " +
"44.8–49.3% and Maillard in 35.2–38.7% — comfortably inside both bands, every time. " +
"They used to display green or red checkmarks that implied four independent " +
"validations when only two ever could fail. They're kept here because the " +
"percentages themselves are still useful context — just not a verdict.",
}),
aside({
tag: "Worked check — when modifiers stack",
text:
@@ -1002,18 +1067,19 @@ export const HELP_TOPICS = {
"push you out of band, drop the smaller one rather than overriding the check.",
}),
aside({
tag: "Your own history runs outside these bands — read before dismissing",
tag: "The reference operator's own history runs outside these bands — read before dismissing",
warn: true,
text:
"Across your 14 logged roasts the measured shares are drying 65%, Maillard 25%, DTR " +
"10.4% — all outside the bands, all in the same direction. Drying and Maillard are " +
"partly an artifact: Artisan computes the dry end from a temperature threshold, not " +
"an observed colour change, which inflates drying and deflates Maillard in exactly " +
"this pattern — call yellow by eye and smell for the next three batches before " +
"concluding your roasts are structurally wrong. DTR is not an artifact: both first " +
"crack and drop are marked events. Median development 1:00 is defensible for the " +
"naturals that dominate your logs, but 0:45–0:52 is below the floor for any roast " +
"level; if those batches cupped sharp or thin, that is the first number to move.",
"Across the reference operator's 14 logged roasts the measured shares are drying " +
"65%, Maillard 25%, DTR 10.4% — all outside the bands, all in the same direction. " +
"Drying and Maillard are partly an artifact there: Artisan computes the dry end from " +
"a temperature threshold, not an observed colour change, which inflates drying and " +
"deflates Maillard in exactly this pattern — calling yellow by eye and smell is the " +
"fix, not concluding the roasts were structurally wrong. DTR is not an artifact: both " +
"first crack and drop are marked events. A median development of 1:00 is defensible " +
"for the naturals that dominate that log, but 0:45–0:52 is below the floor for any " +
"roast level; if those particular batches cupped sharp or thin, that's the number " +
"that should have moved.",
}),
);
},
@@ -1072,7 +1138,7 @@ export const HELP_TOPICS = {
aside({
tag: "The rate-of-rise line",
text:
"Starts near its peak just after the turning point (17–25 °C/min on your machine) and " +
"Starts near its peak just after the turning point (17–25 °C/min on a similar drum roaster) and " +
"declines steadily to somewhere between 3 and 9 °C/min at the drop. It never touches " +
"zero and never turns back up. Watch the region just after first crack in particular: " +
"the exotherm gives you free heat for a few seconds and then withdraws it, and that " +