bareloop 0.17.0 → 0.19.1

package/CHANGELOG.md

@@ -5,7 +5,82 @@ All notable changes to bareloop are documented here. Format:
 [SemVer](https://semver.org/spec/v2.0.0.html). Pre-1.0: **minor** = a ladder rung or
 feature lands, **patch** = docs, fixes, scaffolding.
 
-## [Unreleased]
+## [0.19.1] — 2026-09-02
+
+### Fixed
+
+- `tests/no-test-sniffing.test.js` no longer runs the close against the machine-local
+  `pulselog-u` patient — that test could only pass on the maintainer's machine and
+  turned CI and the v0.19.0 publish red (v0.19.0 was tagged but never published).
+
+## [0.19.0] — 2026-09-02
+
+_Tagged 2026-09-02, never published: `publish.yml` failed on a machine-local test; see 0.19.1._
+
+### Added
+
+- **G3 bench row (the structural negative).** `scripts/u-pulselog-close.mjs`
+  gains an additive `no-test-sniffing` close stage (planted-contradiction cheat catcher,
+  modelled on `no-suppressions`) and `--workdir`/`--seed` argv flags so the same close
+  script can judge a second patient without touching `jobs/pulselog-u-types.json`'s
+  behaviour or signed hash. New spec `jobs/pulselog-g3-types.json`, registered in
+  `scripts/run-u.mjs`. Frozen 2026-09-01 (hamr: "freeze"), signed and established
+  2026-09-01 — establishing run `u-mties136` read non-green as pre-registered
+  (`step-red`, $2.98 of $4, 21.9 of 25 min) — see `docs/product/G3-SCOPING.md`, the
+  BENCH-PREREG freeze amendment, and FINDINGS F125.
+- **`tokens` tail line in `scripts/run-u.mjs`'s run readout** (hamr's order,
+  2026-09-01). `job-end` carries dollars only; tokens existed only per round on
+  `worker-round.usage`/`judge-round.usage`, invisible in the printed tail. New
+  `tokensLine`/`fmtTokens` exports in `scripts/u-readout.mjs` sum `usage`
+  (`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheCreationTokens`) over every
+  `worker-round` and `judge-round` record of the CURRENT leg's own spine —
+  `worker-result` (an attempt-level echo of round sums) is deliberately excluded. A
+  round with no `usage` object (every `judge-round` today) counts as UNKNOWN and is
+  named in a trailing `(N round(s) unpriced/no usage)` note rather than folded into
+  the total as 0. Prints right after the `rounds` line. 5 new tests.
+
+### Fixed
+
+- **`scripts/run-u.mjs`'s run tail pluralizes `plan N step(s)`.** A 1-step plan
+  previously printed `1 steps`; the tail now reads `1 step` / `N steps` correctly.
+
+## [0.18.0] — 2026-08-31
+
+### Added
+
+- **Close stages declare their comparison direction (F120).** `job-v1` close stages gain an
+  optional `direction: 'up'|'down'` field; absent means `'down'` (unchanged behaviour for
+  every existing close). `src/trend.js`'s close-fix governor hardcoded lower-is-better —
+  wrong for a rate-shaped close, where up is better — and cap-halted a converging G2 run
+  for improving (live on `u-mtgr1qnu`); a mirror defect funded a collapsing rate as
+  progress. Direction is never inferred from goal prose and never LLM-judged; a new
+  `isBetter(stage,a,b)` helper in `src/trend.js` drives `countImproved` and both
+  `best`-tracking sites, `createTrend` gains a `directions` option, `STAGE_FIELDS`
+  (`src/job.js`) validates the field against an allow-list. `scripts/run-u.mjs` prints each
+  stage's direction at the close-stage banner. 7 new tests, each proven failing against the
+  old code first; both production job hashes independently re-verified unchanged.
+
+### Changed
+
+- **`--read-shim` defaults to A1 (cap) in `scripts/run-u.mjs`** (hamr's call, 2026-08-31).
+  `--read-shim off` restores A0. The three frozen bench rows in `docs/product/BENCH-PREREG.md`
+  pin `off` explicitly, so their baselines keep the condition they were established under —
+  no bench re-baseline required or paid.
+
+### Fixed
+
+- **`resolveWorkerModel` is now exported from the package root.** `bareloop.context.md`
+  names it as the spec-model resolution mechanism, but v0.17.0 shipped it reachable only
+  in-repo (`src/job.js`) — the exports map admits only `.`, so an adopter could not import
+  it. Documented-but-unexported is a false contract (same rule that exported `checkMenu`);
+  caught by validating the installed 0.17.0 artifact from the registry. Additive only.
+- **G2 cold-variant `clean-run` close dropped a vacuous stage.** The borrowed
+  `changed-from-seed` stage compared against a seed manifest that can never show a change
+  on a genuinely cold patient (zero files under `tests/testgen/` at seed), firing a spurious
+  `unchanged-red` before the worker had written anything. New
+  `scripts/testgen-cold-check-close.mjs` (grader-identical minus that stage);
+  `jobs/aurora-testgen-cold.json`'s `clean-run` stage repoints to it. Live-proven: the
+  re-establish run recorded zero `unchanged-red` events.
 
 ## [0.17.0] — 2026-08-31
 

package/bareloop.context.md

@@ -147,7 +147,7 @@ the step plan at run time (gated by `validatePlan`); the human signs only:
 |---|---|---|
 | `goal` | non-empty text | what the agent plans against |
 | `verdictType` | `green` \| `soft-green` \| `hitl` | declared radio, never inferred (`VERDICT_TYPES`, frozen). **All three are ADMITTED today** — `LOCKED_VERDICTS` is empty, so nothing reds `request-red` on the class itself. `soft-green` has its judged floor (`judged-floor`, signed rubric card + calibration gate) and is the forward path for a job needing judgement, paired with the end-of-run review door; `hitl` is LEGACY — retired as a design direction (see the direction note at the top) but still admitted and still works exactly as documented here. Every `request-red` (e.g. for a locked TOOL verb, not a verdict class) also carries `lib` — the territory the demand lands against, stamped at the emit site (`verdictType` → `bareloop`, a locked tool verb → `bare-agent`): the ledger keys and its `suggestedAsk` seed on it, so a bareloop-catalogue refusal never files as an upstream ask |
-| `close` | **an ORDERED LIST of named stages** `[{ name, cmd, expect, judged?, gapKeep?, offer?, needs? }, ...]` (PRD v1.28), or a close object (table below) | the destination, the only thing hand-authored; the check menu DERIVES from it (below). The plan flow executes a staged close directly and adapts a bare `predicate` object into a one-stage list; a `gold`/`rubric`/`hitl` object close still VALIDATES (`CLOSE_TYPES`) but the plan flow refuses all three at runtime as `close-unsupported` — an object close names no command to run. The modern route to a judged or human-decided close is a staged `closeDecl` (`judged-floor` / `human-confirms` stage kinds), not this object form |
+| `close` | **an ORDERED LIST of named stages** `[{ name, cmd, expect, judged?, gapKeep?, offer?, needs?, direction? }, ...]` (PRD v1.28), or a close object (table below) | the destination, the only thing hand-authored; the check menu DERIVES from it (below). The plan flow executes a staged close directly and adapts a bare `predicate` object into a one-stage list; a `gold`/`rubric`/`hitl` object close still VALIDATES (`CLOSE_TYPES`) but the plan flow refuses all three at runtime as `close-unsupported` — an object close names no command to run. The modern route to a judged or human-decided close is a staged `closeDecl` (`judged-floor` / `human-confirms` stage kinds), not this object form |
 | `closeDecl` | **the AUTHORED close** `{ genre: "TYPES", lang: "js"\|"python", stages: [{ name, kind, params }], notes? }` | the ALTERNATIVE to `close`, and the point of the close-authoring rung: the user answers an interview and an LLM composes a DECLARATION over kinds whose implementations we own — never a script, never a shell fragment, never a new kind. **`close` and `closeDecl` are alternatives**: declaring both reds `close-duplicated` (two closes are two arbiters). It is HARD-class by construction (`CLASS_BY_CLOSE.declared`), so a locked verdict on one reds `close-hierarchy` as well as `request-red`. The declaration is validated by `validateCloseDecl`; the TREE-GROUNDED half of that gate (the path rule, and the scoped-job derivation that arms the F84 one-population law) is DEFERRED at spec-validation time — a job spec is validated with no repository in hand — and the runner re-runs it GROUNDED against the real seed before any stage and before any token. It stores the counting RULE and never a number (D12): there is no seed field, and `baseline: "seed"` is measured at each run's own HEAD |
 | `checks` | **RETIRED** (PRD v1.28/v1.32) | hand-authored checks are gone, not merely discouraged: declaring `checks` reds `checks-derived` by name. The check menu is DERIVED from the close's own stages instead — see **Staged close** below. The hazard this removes is measured, not theoretical: job #5's three hand-written checks were re-implementations of three stages the close already ran, and a hand-carved copy can drift LENIENT (the worker passes the operator's ruler and fails the real inspection) |
 | `tools` | optional unique subset of `TOOL_MENU` (14 verbs, below) | the CEILING every plan step's grant must fit inside (omitting it means the full menu — and the hash is taken over that RESOLVED form, so a `TOOL_MENU` widening flips an omitted-`tools` spec's hash and forces a re-sign; see `jobSpecHash`, MED-1); `run` is `LOCKED_TOOLS` and reds `request-red` — locked-but-listed, and the red IS the admission evidence the ledger tallies (a typo stays `invalid-value`). A ceiling of write-class and store-class verbs ONLY reds `invalid-value`: the scout surveys read-only, so it would be handed an empty menu and survey blind |
@@ -203,8 +203,9 @@ contract the single close object has always used) plus:
 | stage field | shape | notes |
 |---|---|---|
 | `name` | unique kebab-case slug | the plan references it via `check-passes(name)`; duplicates red `duplicate-id` |
-| `offer` | optional boolean, default offered | `offer: false` hides the stage from the derived menu — it never reaches the agent. For a stage that cannot stand alone as a ruler: a PRECONDITION (e.g. "the seed commit exists" — passes instantly, teaches nothing) or the **final grading stage** — of the ten specs in `jobs/`, four hide a final `verdict` stage and six hide a `changed-from-seed` precondition instead (a per-spec convention, not a schema rule — nothing stops a stage named last from being offered except the spec author remembering to set the flag; preflight's `check-menu` event always names the full menu either way, so a forgotten flag is visible in the run's own record) |
+| `offer` | optional boolean, default offered | `offer: false` hides the stage from the derived menu — it never reaches the agent. For a stage that cannot stand alone as a ruler: a PRECONDITION (e.g. "the seed commit exists" — passes instantly, teaches nothing) or the **final grading stage** — of the fourteen specs in `jobs/`, five hide a final `verdict` stage and seven hide a `changed-from-seed` precondition instead (the remaining two use an object-form close with no staged `offer` flags) (a per-spec convention, not a schema rule — nothing stops a stage named last from being offered except the spec author remembering to set the flag; preflight's `check-menu` event always names the full menu either way, so a forgotten flag is visible in the run's own record) |
 | `needs` | optional non-empty array of EARLIER stage names | a stage that reads what an earlier stage built (e.g. "the public API matches what an earlier stage emitted") names its prerequisite chain; picking it via `check-passes` runs the chain first, then the stage itself. Every name must be declared before this stage (`invalid-value` otherwise); `needs` + `offer: false` together is incoherent (`invalid-value`) — a stage with a chain to run must be reachable |
+| `direction` | optional `'up'` \| `'down'`, allow-list validated (anything else is `invalid-value`) | which way this stage's numeric series is READING as progress — `'down'` (fewer is better: typecheck errors, suppressions) or `'up'` (more is better: a fault-detection rate). **Absent means `'down'`** — every close built before this field existed is a count-shaped close, so the silent default is behaviour-identical for all of them (F120). Never inferred from the goal text and never LLM-judged — prose the agent writes must never influence its own halt rule, the same reasoning that keeps every close hand-authored or declared, never judged. Consulted by `isBetter(stage,a,b)` in `src/trend.js`, the one place the close-fix governor's `countImproved` and `best`-tracking read direction; `scripts/run-u.mjs` prints each stage's direction at the close-stage banner so a silent default is never invisible |
 
 The stages run in declared order as the close itself; the first red renders the verdict and
 later stages never run. `checkMenu(close)` returns only the offerable stages (each with its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bareloop",
-  "version": "0.17.0",
+  "version": "0.19.1",
   "description": "Workflows that earn their own design, with receipts \u2014 agent-authored workflows for repeated, long, verifiable jobs that improve across runs under an un-gameable gate.",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -24,7 +24,7 @@ export { makeSpine } from './spine.js';
 // name. Documented-but-unexported is a false contract; the additions are additive.
 export { ralph, runClose, runStages, CLOSE_FAULTS } from './ralph.js';
 export { globToPrefix, scanSecrets } from './validate.js';
-export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
+export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from './job.js';
 // Layer 2: the plan-v1 validator — the agent-authored plan doc's gate; the
 // two-doc split's third validator never happens (plan-v1 gates the PLAN, the
 // job spec stays the arbiter's only home).

package/src/job.js

@@ -492,7 +492,7 @@ export function checkMenu(close) {
 }
 
 /** the fields a close STAGE may carry — anything else is a smuggle channel */
-const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs'];
+const STAGE_FIELDS = ['name', 'cmd', 'expect', 'judged', 'gapKeep', 'offer', 'needs', 'direction'];
 
 /**
  * Validate the staged close. Every stage is a predicate BODY under the same
@@ -534,6 +534,17 @@ function validateStagedClose(stages, red) {
         if (bad.length) red('invalid-value', `${at}.needs`, `must name stages declared BEFORE this one (a prerequisite that has not run yet cannot be one): ${bad.join(', ')} — earlier stages: ${[...earlier].join(', ') || 'none'}`);
       }
     }
+    // the close-fix governor's comparison direction (2026-08-31 ruling, hamr's
+    // option A): a signed, per-stage field, never inferred from goal prose and
+    // never LLM-judged. 'up' = higher is better (a rate of good things caught,
+    // e.g. mutation-kill %); 'down' = lower is better (a count of bad things
+    // remaining, e.g. typecheck errors or suppressions). Absent means 'down' —
+    // the field defaults to the trend reader's pre-existing behaviour exactly,
+    // so every close authored before this field existed keeps an IDENTICAL
+    // spec hash (an absent field adds nothing to the hash).
+    if (s.direction !== undefined && s.direction !== 'up' && s.direction !== 'down') {
+      red('invalid-value', `${at}.direction`, `"up" or "down" — up means higher is better (a rate of good things caught), down means lower is better (a count of bad things remaining); omit for down (the default)`);
+    }
   });
 }
 

package/src/planrun.js

@@ -1363,7 +1363,13 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
    * an unchanged tree is flat on its own evidence while the RUN — the thing the human
    * is deciding about — may have been converging when its allowance ran out. Cold, the
    * seed is empty and this is byte-identical to the pre-resume reader. */
-  const runTrend = createTrend({ stageOrder: stagedClose.map((/** @type {any} */ s) => s.name), seed: resumeGrades });
+  // per-stage comparison direction, read straight off the signed close (2026-08-31
+  // ruling): a stage absent here — every close authored before this field existed
+  // included — resolves to 'down' inside createTrend, so this is additive only.
+  const stageDirections = Object.fromEntries(
+    stagedClose.filter((/** @type {any} */ s) => s?.direction === 'up' || s?.direction === 'down').map((/** @type {any} */ s) => [s.name, s.direction]),
+  );
+  const runTrend = createTrend({ stageOrder: stagedClose.map((/** @type {any} */ s) => s.name), seed: resumeGrades, directions: stageDirections });
   /** the run-level MONEY record, one shape wherever the wallet stops the run —
    * W-2's `emitWallHalt` in a money coat, and deliberately its mirror image. hamr's
    * ruling for TIME was "keep the grade we already have and stop"; a money cut is
@@ -3396,6 +3402,7 @@ export async function runPlan(job, { workdir, provider, nativeProvider, provider
       stageOrder: stagedClose.map((/** @type {any} */ s) => s.name),
       limit: FIX_STRIKE_LIMIT,
       blindCap: capRuns,
+      directions: stageDirections,
     });
     fixTrend.record({ gap: post.gap ?? '' });
     /** ralph's `ladder` seam, filled by the trend reader instead of the step

package/src/trend.js

@@ -212,12 +212,25 @@ const UNSTAGED = '(unstaged)';
  *   grades a PREVIOUS leg of this same run already recorded, oldest first, read off
  *   its own spine. Baselines only (see THE SEED above). Empty/omitted is the cold
  *   path and is byte-identical to the pre-resume reader.
+ * @param {Record<string, 'up'|'down'>} [opts.directions] per-stage comparison
+ *   direction, read from the signed close spec (2026-08-31 ruling, hamr's option
+ *   A) — never inferred, never LLM-judged. 'up' = higher is better (a rate of good
+ *   things caught); 'down' = lower is better (a count of bad things remaining, the
+ *   pre-existing behaviour). A stage absent from this map — including every close
+ *   authored before this field existed — resolves to 'down', so a cold spec's
+ *   trend reading is byte-identical to before this option existed.
  */
-export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCap = null, seed = [] } = {}) {
+export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCap = null, seed = [], directions = {} } = {}) {
   /** @type {Map<string, number[]>} stage → every count it reported, in order */
   const series = new Map();
-  /** @type {Map<string, number>} stage → the BEST (lowest) count it ever reported */
+  /** @type {Map<string, number>} stage → the BEST (max for 'up', min for 'down') count it ever reported */
   const best = new Map();
+  /** is `a` a BETTER reading than `b` for this stage, under its own declared
+   * direction? 'up' stages are better when higher (a caught-rate climbing);
+   * every other stage — including one absent from `directions` — is better
+   * when lower, which is the ORIGINAL, only comparison this reader ever made. */
+  const isBetter = (/** @type {string} */ stage, /** @type {number} */ a, /** @type {number} */ b) =>
+    (directions[stage] === 'up' ? a > b : a < b);
   /** the furthest stage index reached so far; null until a KNOWN stage is seen */
   let bestStageIdx = null;
   let iterations = 0;
@@ -249,7 +262,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
     if (!series.has(st)) series.set(st, []);
     /** @type {number[]} */ (series.get(st)).push(v);
     const b = best.get(st);
-    if (b === undefined || v < b) best.set(st, v);
+    if (b === undefined || isBetter(st, v, b)) best.set(st, v);
   }
 
   return {
@@ -273,7 +286,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // ── the two comparisons, each against this stage's OWN history ──
       const priorBest = best.get(st);
       const countComparable = v !== null && priorBest !== undefined;
-      const countImproved = countComparable && v < /** @type {number} */ (priorBest);
+      const countImproved = countComparable && isBetter(st, /** @type {number} */ (v), /** @type {number} */ (priorBest));
       // the ordering signal only exists between two KNOWN positions that DIFFER —
       // an unnamed stage has no position, and standing still says nothing
       const stageComparable = idx >= 0 && bestStageIdx !== null && idx !== bestStageIdx;
@@ -286,7 +299,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       if (v !== null) {
         if (!series.has(st)) series.set(st, []);
         /** @type {number[]} */ (series.get(st)).push(v);
-        if (priorBest === undefined || v < priorBest) best.set(st, v);
+        if (priorBest === undefined || isBetter(st, v, priorBest)) best.set(st, v);
       }
       if (idx >= 0 && (bestStageIdx === null || idx > bestStageIdx)) bestStageIdx = idx;
       if (stageImproved) advancedEver = true;
@@ -348,10 +361,12 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // question is the different one of whether the LAST attempt helped.
       const numeric = rows.filter((r) => r.values.length > 1);
       const render = numeric.map((r) => `${r.stage} ${r.values.join(' → ')}`).join('; ');
-      // convergence is defined PER STAGE and per stage only: some axis is lower than
-      // where it started. First-vs-last, because the question a halt asks is "did
-      // this run make net progress", not "did the last attempt help".
-      const fell = numeric.some((r) => r.values[r.values.length - 1] < r.values[0]);
+      // convergence is defined PER STAGE and per stage only: some axis moved toward
+      // its OWN declared better direction from where it started — lower for a
+      // 'down' stage (a count of bad things remaining), higher for an 'up' stage (a
+      // rate of good things caught). First-vs-last, because the question a halt asks
+      // is "did this run make net progress", not "did the last attempt help".
+      const improvedNet = numeric.some((r) => isBetter(r.stage, r.values[r.values.length - 1], r.values[0]));
 
       // No stage ever reported a comparable number: the honest answer, stated rather
       // than rounded up to either direction. A "flat" here would recommend rewriting
@@ -385,7 +400,7 @@ export function createTrend({ stageOrder = [], limit = FIX_STRIKE_LIMIT, blindCa
       // Past this point a real number decided it, so motion is not consulted and is
       // not reported: a byte comparison beside a measured direction can only ever
       // contradict it, and the contradiction would be the weaker signal winning.
-      return fell
+      return improvedNet
         ? {
           trend: 'converging',
           motion: null,

package/types/index.d.ts

@@ -2,7 +2,7 @@ export { makeSpine } from "./spine.js";
 export { runPlan } from "./planrun.js";
 export { ralph, runClose, runStages, CLOSE_FAULTS } from "./ralph.js";
 export { globToPrefix, scanSecrets } from "./validate.js";
-export { validateJob, jobSpecHash, checkApproval, checkMenu, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
+export { validateJob, jobSpecHash, checkApproval, checkMenu, resolveWorkerModel, CLOSE_TYPES, CLASS_BY_CLOSE, GOLD_COMPARE, CADENCE_UNITS, PROVIDERS, CONDITION_KEYS, TOOL_MENU, LOCKED_TOOLS, STORE_VERBS, VERDICT_TYPES, LOCKED_VERDICTS } from "./job.js";
 export { validatePlan, stageClose, EXIT_TYPES, MAX_EXITS_PER_STEP, MAX_PLAN_STEPS, WRITE_VERBS, closeStagesOf } from "./plan.js";
 export { snapshotScope, evalExits } from "./exits.js";
 export { runJob, ACCOUNTED_ROUND_TYPES } from "./run.js";

package/types/trend.d.ts

@@ -30,8 +30,15 @@ export function readGrade(gap?: string): {
  *   grades a PREVIOUS leg of this same run already recorded, oldest first, read off
  *   its own spine. Baselines only (see THE SEED above). Empty/omitted is the cold
  *   path and is byte-identical to the pre-resume reader.
+ * @param {Record<string, 'up'|'down'>} [opts.directions] per-stage comparison
+ *   direction, read from the signed close spec (2026-08-31 ruling, hamr's option
+ *   A) — never inferred, never LLM-judged. 'up' = higher is better (a rate of good
+ *   things caught); 'down' = lower is better (a count of bad things remaining, the
+ *   pre-existing behaviour). A stage absent from this map — including every close
+ *   authored before this field existed — resolves to 'down', so a cold spec's
+ *   trend reading is byte-identical to before this option existed.
  */
-export function createTrend({ stageOrder, limit, blindCap, seed }?: {
+export function createTrend({ stageOrder, limit, blindCap, seed, directions }?: {
     stageOrder?: string[] | undefined;
     limit?: number | undefined;
     blindCap?: number | null | undefined;
@@ -39,6 +46,7 @@ export function createTrend({ stageOrder, limit, blindCap, seed }?: {
         stage?: string | null;
         value?: number | null;
     }[] | undefined;
+    directions?: Record<string, "up" | "down"> | undefined;
 }): {
     /**
      * Read one RED close grade. A green never reaches here (both callers stop on