@gaunt-sloth/batch 2.0.0-beta.9 → 2.0.1

package/dist/raterPromptArm.d.ts

@@ -0,0 +1,140 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { RaterCallCapture } from '@gaunt-sloth/core/core/shell/approvalCapture.js';
+import { buildComposedOpenWorldNote } from '@gaunt-sloth/core/core/shell/openWorld.js';
+import { buildParserPreflightNote } from '@gaunt-sloth/core/core/shell/abstention.js';
+/**
+ * The notes an arm can omit: a stable suite-facing token → **core's own builder for that note's
+ * exact text**.
+ *
+ * **Every entry is core's function, never a copy of its prose, and that is the entry requirement.**
+ * The off arm is produced by deleting a block from the built prompt, so the text used to find the
+ * block has to be the same bytes the builder put there. A second copy in this package would pass
+ * review, drift on the first wording change in core, then find nothing to delete — and an arm that
+ * deletes nothing sends the on-arm prompt under the off arm's name, so the comparison reports the
+ * note having no effect. {@link reconcileArmedCapture} raises on exactly that, but a registry built
+ * from copies would be relying on a runtime check to catch a defect the design need not have.
+ *
+ * **Two of `buildRaterPrompt`'s four preflight notes are therefore absent**: the script-env-leak
+ * note and the open-world floor note are composed inline in that function and core exports no
+ * builder for either. They become expressible the day core extracts one — which is a change to core
+ * with its own justification, not something to smuggle in here as a copied string.
+ */
+export declare const RATER_PROMPT_NOTES: {
+    /** [[EXT-81]]'s note: the data flow across the parts of a command our parser could not resolve
+     * as a whole. The note the A/B that motivated this node is about. */
+    readonly 'composed-open-world': typeof buildComposedOpenWorldNote;
+    /** The parser's own abstention note: what about the command's shape could not be resolved. */
+    readonly parser: typeof buildParserPreflightNote;
+};
+/** A note name a suite may omit — the keys of {@link RATER_PROMPT_NOTES}. */
+export type RaterPromptNoteName = keyof typeof RATER_PROMPT_NOTES;
+/** Every note name a suite may write, in declaration order, for error messages and validation. */
+export declare const RATER_PROMPT_NOTE_NAMES: RaterPromptNoteName[];
+/**
+ * One sweep cell's prompt arm: which of our own preflight notes this cell's ratings go out without.
+ *
+ * `omit: []` is the meaningful, and required, spelling of the baseline arm. A sweep value that
+ * declared nothing at all would be indistinguishable from an authoring slip, and the whole point of
+ * an A/B is that both arms say what they are.
+ */
+export interface RaterPromptArm {
+    readonly omit: readonly RaterPromptNoteName[];
+}
+/** The prompt as it actually left for the model. */
+export interface ArmedPrompt {
+    system: string;
+    user: string;
+}
+/**
+ * What one armed rating call did — recorded by the decorator, adjudicated afterwards by
+ * {@link reconcileArmedCapture}.
+ */
+export interface RaterPromptArmOutcome {
+    /** Whether the decorated model was invoked at all. `false` means `rateShellCommand` returned
+     * before the send site — it found no usable model — so nothing was measured. */
+    invoked: boolean;
+    /** Notes whose block was found and removed. */
+    removed: RaterPromptNoteName[];
+    /** Notes that do not apply to this command, so there was no block to remove. This is the
+     * byte-identical case and it is silent by design: a command carrying no composed note must
+     * produce the same prompt under both arms. */
+    absent: RaterPromptNoteName[];
+    /** Notes whose block core says exists on this command and the arm could not find in the prompt —
+     * a leak. Raised on, never tolerated. */
+    leaked: RaterPromptNoteName[];
+    /** The prompt as sent, once the arm had finished with it. */
+    sent?: ArmedPrompt;
+}
+/**
+ * Delete the arm's notes from a built rater user message.
+ *
+ * Pure, and keyed on the command: each note's block is `'\n\n' + <core's text for this command>`,
+ * because `buildRaterPrompt` pushes every note into its line buffer as `('', note)` and joins on
+ * `'\n'`. A note that does not apply to the command yields `null` and is recorded as `absent`.
+ */
+export declare function stripRaterPromptNotes(user: string, command: string, arm: RaterPromptArm): {
+    user: string;
+    removed: RaterPromptNoteName[];
+    absent: RaterPromptNoteName[];
+    leaked: RaterPromptNoteName[];
+};
+/**
+ * Wrap a rating model so this call's prompt goes out without the arm's notes.
+ *
+ * **Why the MODEL and not the prompt builder.** The prompt is built inside `rateShellCommand`, and
+ * every seam that could change it there would be a switch in the session's gate. The model is the
+ * one thing the gate takes from its caller, so decorating it is the only place a measurement can
+ * change the outgoing prompt without core growing a parameter for it. The `eval` rater target is
+ * also the only caller that constructs such a model.
+ *
+ * **A Proxy rather than a hand-written delegate**, because `rateShellCommand` reads more off a model
+ * than `withStructuredOutput` — `raterModelLabel` calls `_llmType()` and reads `model`/`modelName`/
+ * `modelId` — and a delegate that enumerated today's reads would silently answer `undefined` for
+ * tomorrow's. Every trap forwards with the TARGET as the receiver and binds methods to the target,
+ * so a provider class keeping state behind private `#fields` is not handed a `this` it cannot use.
+ *
+ * **A shape it does not recognise is a leak, not a pass-through.** If the messages are not the
+ * `[SystemMessage, HumanMessage]` pair with string content that `rateShellCommand` sends, the call
+ * is forwarded unchanged and every requested note is recorded as leaked, so the run fails loudly
+ * instead of quietly measuring the on-arm prompt under the off arm's name.
+ *
+ * @param model The resolved rating model.
+ * @param command The command this call rates — the notes are a function of it.
+ * @param arm The notes to omit.
+ * @param outcome The record this call writes into; one per rating call, so concurrent cases cannot
+ *   share it.
+ */
+export declare function armRaterModel(model: BaseChatModel, command: string, arm: RaterPromptArm, outcome: RaterPromptArmOutcome): BaseChatModel;
+/**
+ * A fresh outcome plus the model that writes into it — **one per rating call**, because the
+ * classifier is reused across cases the suite runner may run concurrently and a shared record would
+ * let one case's arm be adjudicated on another's call.
+ *
+ * `model` is `undefined` only in the state `buildRaterClassifier` refuses to build: an arm declared
+ * with no model to decorate. It is admitted here rather than guarded a second time, so that state
+ * lands on {@link reconcileArmedCapture}'s "never reached a rating call" arm — one rule, one place —
+ * instead of on a copy of the rule that could drift from it.
+ */
+export declare function armFor(model: BaseChatModel | undefined, command: string, arm: RaterPromptArm): {
+    model: BaseChatModel | undefined;
+    outcome: RaterPromptArmOutcome;
+};
+/**
+ * Adjudicate one armed rating call, **after it has returned and outside `rateShellCommand`'s
+ * fail-closed `try`**, and repair the call's diagnostic record.
+ *
+ * Two jobs, and both are about not lying:
+ *
+ * - **Raise on an arm that did not do what it said.** A leaked note, or a rating call the decorated
+ *   model never saw, means this cell's numbers are the other arm's numbers under this arm's name.
+ *   Silently reporting them is strictly worse than failing the run, because the comparison table
+ *   would then say the note changed nothing.
+ * - **Make `capture.prompt` the prompt that was SENT.** `rateShellCommand` fills the capture from
+ *   `buildRaterPrompt`'s output at the send site and its contract is that nothing downstream may
+ *   leave the archive disagreeing with what the model saw. The arm edits the message below that
+ *   point, so the arm is what owes the correction — and for a facility whose whole subject is prompt
+ *   content, a diagnostic record of the wrong arm's prompt would be the worst possible artifact.
+ *
+ * @param capture The record `rateShellCommand` handed back through `onCapture`, when it made one.
+ */
+export declare function reconcileArmedCapture(command: string, arm: RaterPromptArm, outcome: RaterPromptArmOutcome, capture: RaterCallCapture | undefined): void;

package/dist/raterPromptArm.js

@@ -0,0 +1,306 @@
+/**
+ * @packageDocumentation
+ * [[BATCH-31]] — **prompt-content A/B for the approvals rater: the same corpus rated twice, once
+ * with one of our own preflight notes in the prompt and once without.**
+ *
+ * [[EXT-81]] needed exactly that comparison and could not express it as a suite. A sweep can move
+ * the rung and the model; nothing could say *omit this note*. It was measured instead by a
+ * standalone harness
+ * (`docs/test-sessions/ext-81-composed-note-sweep-2026-08-04/harness/composed-open-world-note.mjs`)
+ * that built the shipping prompt and **deleted the note block out of it** — and that harness, not a
+ * new prompt builder, is what this module generalises.
+ *
+ * ## What "production" means here, because the whole argument below hangs on it
+ *
+ * **Production is the SESSION's approvals gate**: `GthAgentRunner`'s rating call, the one that
+ * decides whether a shell command a live agent proposed runs, prompts, or halts. That is the gate
+ * whose safety context must never be suppressible. `gth eval` is a measuring instrument — it rates
+ * a corpus and prints a table, and gates nothing — so making an omission expressible *there* is the
+ * point of this node, not a hazard.
+ *
+ * The forbidden design is therefore precise: **a switch inside the gate** — a parameter on
+ * `rateShellCommand` or `buildRaterPrompt` that suppresses a note. [[EXT-81]]'s implementer
+ * identified that shape and declined to build it. Nothing here adds one; **core is untouched by
+ * this node.**
+ *
+ * ## The shape taken: a third sweep-override kind with its own route
+ *
+ * A sweep value already carries two override kinds, and they reach the run by two different routes:
+ * `model:` through `initConfig({ model })`, and `config:` by a deep merge onto the resolved
+ * `GthConfig`. This adds a third, `notes:`, whose route is:
+ *
+ * ```text
+ *   suite  sweep value  notes: { omit: [<note>] }
+ *     -> EvalSweepValue.notes  (parsed and validated against the registry below)
+ *     -> SweepCell.notes       (expandSweep; never merged into the cell's `config`)
+ *     -> RaterClassifierOptions.notes
+ *     -> armRaterModel(...)    <- a decorator around the RATING MODEL, in this package
+ *     -> the note block is deleted from the outgoing user message
+ * ```
+ *
+ * The one-file A/B EXT-81 wanted is then a one-axis sweep: `{ name: on, notes: { omit: [] } }`
+ * against `{ name: off, notes: { omit: [composed-open-world] } }`.
+ *
+ * ## How production-unreachability is ENFORCED, not merely intended
+ *
+ * Four independent legs, each of which a test can fail:
+ *
+ * 1. **The omission never becomes config.** `notes:` is a sibling of `config:`, not a key inside it,
+ *    and `initConfigForCell` deep-merges only `cell.config`. So the value has no representation in
+ *    `GthConfig`, and therefore none in `.gsloth.config.json`, in an env var, or in a CLI flag —
+ *    the three carriers the node names. Pinned by a spec that plants the omission in a config, in
+ *    an `approvals` block, and on the rating call's own options object, drives the SESSION gate over
+ *    a noted command, and asserts the note is still in the prompt that was sent.
+ * 2. **The omission is not data at all — it is a function.** What actually removes the note is a
+ *    `BaseChatModel` decorator constructed here at classifier-build time. A config file, an
+ *    environment variable and a command-line flag can carry a string; none of them can carry a model
+ *    decorator. There is no serialisable spelling of this facility for a session to deserialise.
+ * 3. **The session's gate cannot import this module.** `@gaunt-sloth/batch` depends on
+ *    `@gaunt-sloth/core`, where `GthAgentRunner` and `rateShellCommand` live. The reverse edge is a
+ *    dependency cycle, so core cannot reach `armRaterModel` even deliberately. This is enforced by
+ *    the package graph rather than by a convention someone has to remember.
+ * 4. **The declaration is rejected on every target that runs an agent.** `notes:` parses only on a
+ *    `rater` suite, which runs no agent and executes no tool — so the surface does not exist on the
+ *    suite kinds that drive real sessions.
+ *
+ * **What none of that proves, stated because the honest limit matters:** leg 3 shows core cannot
+ * construct this arm; it does not show core will never grow a suppression switch of its own. Only a
+ * *wired* switch is a production path, so the discriminating test is the one in leg 1 — drive the
+ * runner's gate and watch the note survive — and the mutation that proves it real is to make the
+ * runner pass a suppression flag and see that spec go red. A test that merely asserted something
+ * about this package's barrel exports would pass while proving nothing about the hazard.
+ *
+ * ## Where the route is held, end to end
+ *
+ * Three specs, one per link, because a facility can be perfectly built and still measure nothing:
+ * `packages/batch/spec/raterPromptArm.spec.ts` (parse, expand, arm, reconcile),
+ * `packages/core/spec/raterPromptNotesNotSuppressible.spec.ts` (leg 1 above — the session's gate),
+ * and `packages/app/spec/evalCommandRaterArm.spec.ts`, which runs the A/B suite through the `eval`
+ * command itself. The last one exists because the hand-off in `evalCommand.ts` is the single line
+ * that connects the other two: cut it and every arm silently sends the same prompt, the comparison
+ * table honestly reports the note changing nothing, and both of the other specs stay green.
+ *
+ * ## Shapes rejected
+ *
+ * - **A `notes:` option on `rateShellCommand` / `buildRaterPrompt`.** This is the naive fix and it
+ *   is the one the node forbids: a switch in the gate that suppresses safety context for one
+ *   measurement's benefit. Defaults and documentation do not redeem it — it puts the code path in
+ *   the session's own rating call, where the next caller to grow an option bag can reach it.
+ * - **A sweep axis that overrides `target:` fields.** The node names this as a candidate, and it was
+ *   rejected because it would falsify a constraint the existing sweep depends on. `resolveRung`'s
+ *   docblock states that a cell can override `config:` and `model:` but cannot reach a `target`
+ *   field, and that this is *deliberate* and is what makes `config: { approvals: auto }` the way an
+ *   axis moves the rung. An axis able to rewrite `target` would give the rung two spellings with a
+ *   silent precedence between them. Adding a third route leaves that constraint exactly as true as
+ *   it was.
+ * - **A `target.notes:` field with no sweep reach.** Expressible, but a `target` is suite-level, so
+ *   the A/B would again be two hand-written suite files — the thing this node exists to remove.
+ * - **Reproducing a note's text in this package.** See {@link RATER_PROMPT_NOTES}: a second copy of
+ *   the prose would drift, and a drifted copy deletes nothing, so both arms would send the same
+ *   prompt and the measurement would report "the note has no effect". That is the failure mode that
+ *   passes its own test, so only notes core exports a byte-exact builder for are expressible.
+ *
+ * ## Why the decorator never throws, and the caller adjudicates instead
+ *
+ * The strip happens inside `structured.invoke`, which `rateShellCommand` runs inside the `try` whose
+ * whole job is to turn a throw into the fail-closed `destructive` verdict. A decorator that threw on
+ * a leak would therefore be recorded as a rating, and the arm's own failure would read as the
+ * rater's judgement. So the decorator only ever RECORDS what it did, and
+ * {@link reconcileArmedCapture} — called by the target after the rating call has returned, outside
+ * that `try` — is what raises.
+ */
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { buildComposedOpenWorldNote } from '@gaunt-sloth/core/core/shell/openWorld.js';
+import { buildParserPreflightNote } from '@gaunt-sloth/core/core/shell/abstention.js';
+/**
+ * The notes an arm can omit: a stable suite-facing token → **core's own builder for that note's
+ * exact text**.
+ *
+ * **Every entry is core's function, never a copy of its prose, and that is the entry requirement.**
+ * The off arm is produced by deleting a block from the built prompt, so the text used to find the
+ * block has to be the same bytes the builder put there. A second copy in this package would pass
+ * review, drift on the first wording change in core, then find nothing to delete — and an arm that
+ * deletes nothing sends the on-arm prompt under the off arm's name, so the comparison reports the
+ * note having no effect. {@link reconcileArmedCapture} raises on exactly that, but a registry built
+ * from copies would be relying on a runtime check to catch a defect the design need not have.
+ *
+ * **Two of `buildRaterPrompt`'s four preflight notes are therefore absent**: the script-env-leak
+ * note and the open-world floor note are composed inline in that function and core exports no
+ * builder for either. They become expressible the day core extracts one — which is a change to core
+ * with its own justification, not something to smuggle in here as a copied string.
+ */
+export const RATER_PROMPT_NOTES = {
+    /** [[EXT-81]]'s note: the data flow across the parts of a command our parser could not resolve
+     * as a whole. The note the A/B that motivated this node is about. */
+    'composed-open-world': buildComposedOpenWorldNote,
+    /** The parser's own abstention note: what about the command's shape could not be resolved. */
+    parser: buildParserPreflightNote,
+};
+/** Every note name a suite may write, in declaration order, for error messages and validation. */
+export const RATER_PROMPT_NOTE_NAMES = Object.keys(RATER_PROMPT_NOTES);
+/** A fresh, empty outcome for one rating call. */
+function emptyOutcome() {
+    return { invoked: false, removed: [], absent: [], leaked: [] };
+}
+/**
+ * Delete the arm's notes from a built rater user message.
+ *
+ * Pure, and keyed on the command: each note's block is `'\n\n' + <core's text for this command>`,
+ * because `buildRaterPrompt` pushes every note into its line buffer as `('', note)` and joins on
+ * `'\n'`. A note that does not apply to the command yields `null` and is recorded as `absent`.
+ */
+export function stripRaterPromptNotes(user, command, arm) {
+    let out = user;
+    const removed = [];
+    const absent = [];
+    const leaked = [];
+    for (const name of arm.omit) {
+        const note = RATER_PROMPT_NOTES[name](command);
+        if (note === null) {
+            absent.push(name);
+            continue;
+        }
+        const block = `\n\n${note}`;
+        const at = out.indexOf(block);
+        if (at === -1) {
+            leaked.push(name);
+            continue;
+        }
+        out = out.slice(0, at) + out.slice(at + block.length);
+        removed.push(name);
+    }
+    return { user: out, removed, absent, leaked };
+}
+/**
+ * Wrap a rating model so this call's prompt goes out without the arm's notes.
+ *
+ * **Why the MODEL and not the prompt builder.** The prompt is built inside `rateShellCommand`, and
+ * every seam that could change it there would be a switch in the session's gate. The model is the
+ * one thing the gate takes from its caller, so decorating it is the only place a measurement can
+ * change the outgoing prompt without core growing a parameter for it. The `eval` rater target is
+ * also the only caller that constructs such a model.
+ *
+ * **A Proxy rather than a hand-written delegate**, because `rateShellCommand` reads more off a model
+ * than `withStructuredOutput` — `raterModelLabel` calls `_llmType()` and reads `model`/`modelName`/
+ * `modelId` — and a delegate that enumerated today's reads would silently answer `undefined` for
+ * tomorrow's. Every trap forwards with the TARGET as the receiver and binds methods to the target,
+ * so a provider class keeping state behind private `#fields` is not handed a `this` it cannot use.
+ *
+ * **A shape it does not recognise is a leak, not a pass-through.** If the messages are not the
+ * `[SystemMessage, HumanMessage]` pair with string content that `rateShellCommand` sends, the call
+ * is forwarded unchanged and every requested note is recorded as leaked, so the run fails loudly
+ * instead of quietly measuring the on-arm prompt under the off arm's name.
+ *
+ * @param model The resolved rating model.
+ * @param command The command this call rates — the notes are a function of it.
+ * @param arm The notes to omit.
+ * @param outcome The record this call writes into; one per rating call, so concurrent cases cannot
+ *   share it.
+ */
+export function armRaterModel(model, command, arm, outcome) {
+    const forward = (target, prop) => {
+        const value = Reflect.get(target, prop, target);
+        return typeof value === 'function'
+            ? value.bind(target)
+            : value;
+    };
+    const armInvoke = (messages) => {
+        outcome.invoked = true;
+        if (!Array.isArray(messages) || messages.length !== 2) {
+            outcome.leaked.push(...arm.omit);
+            return messages;
+        }
+        const [system, user] = messages;
+        if (typeof system?.content !== 'string' || typeof user?.content !== 'string') {
+            outcome.leaked.push(...arm.omit);
+            return messages;
+        }
+        const stripped = stripRaterPromptNotes(user.content, command, arm);
+        outcome.removed.push(...stripped.removed);
+        outcome.absent.push(...stripped.absent);
+        outcome.leaked.push(...stripped.leaked);
+        outcome.sent = { system: system.content, user: stripped.user };
+        return [new SystemMessage(system.content), new HumanMessage(stripped.user)];
+    };
+    return new Proxy(model, {
+        get(target, prop) {
+            if (prop !== 'withStructuredOutput')
+                return forward(target, prop);
+            const original = Reflect.get(target, prop, target);
+            if (typeof original !== 'function')
+                return original;
+            return (...args) => {
+                const runnable = original.apply(target, args);
+                if (runnable === null || typeof runnable !== 'object')
+                    return runnable;
+                return new Proxy(runnable, {
+                    get(runnableTarget, runnableProp) {
+                        if (runnableProp !== 'invoke')
+                            return forward(runnableTarget, runnableProp);
+                        const invoke = Reflect.get(runnableTarget, runnableProp, runnableTarget);
+                        if (typeof invoke !== 'function')
+                            return invoke;
+                        return (messages, ...rest) => invoke.apply(runnableTarget, [
+                            armInvoke(messages),
+                            ...rest,
+                        ]);
+                    },
+                });
+            };
+        },
+    });
+}
+/**
+ * A fresh outcome plus the model that writes into it — **one per rating call**, because the
+ * classifier is reused across cases the suite runner may run concurrently and a shared record would
+ * let one case's arm be adjudicated on another's call.
+ *
+ * `model` is `undefined` only in the state `buildRaterClassifier` refuses to build: an arm declared
+ * with no model to decorate. It is admitted here rather than guarded a second time, so that state
+ * lands on {@link reconcileArmedCapture}'s "never reached a rating call" arm — one rule, one place —
+ * instead of on a copy of the rule that could drift from it.
+ */
+export function armFor(model, command, arm) {
+    const outcome = emptyOutcome();
+    return {
+        model: model === undefined ? undefined : armRaterModel(model, command, arm, outcome),
+        outcome,
+    };
+}
+/**
+ * Adjudicate one armed rating call, **after it has returned and outside `rateShellCommand`'s
+ * fail-closed `try`**, and repair the call's diagnostic record.
+ *
+ * Two jobs, and both are about not lying:
+ *
+ * - **Raise on an arm that did not do what it said.** A leaked note, or a rating call the decorated
+ *   model never saw, means this cell's numbers are the other arm's numbers under this arm's name.
+ *   Silently reporting them is strictly worse than failing the run, because the comparison table
+ *   would then say the note changed nothing.
+ * - **Make `capture.prompt` the prompt that was SENT.** `rateShellCommand` fills the capture from
+ *   `buildRaterPrompt`'s output at the send site and its contract is that nothing downstream may
+ *   leave the archive disagreeing with what the model saw. The arm edits the message below that
+ *   point, so the arm is what owes the correction — and for a facility whose whole subject is prompt
+ *   content, a diagnostic record of the wrong arm's prompt would be the worst possible artifact.
+ *
+ * @param capture The record `rateShellCommand` handed back through `onCapture`, when it made one.
+ */
+export function reconcileArmedCapture(command, arm, outcome, capture) {
+    if (!outcome.invoked) {
+        throw new Error(`eval: the prompt arm omitting [${arm.omit.join(', ')}] never reached a rating call for ` +
+            `"${command}" — the gate found no usable rating model, so this cell would report the ` +
+            "other arm's prompt under this arm's name.");
+    }
+    if (outcome.leaked.length > 0) {
+        // This sentence names a DRIFT between core and the arm, and it is allowed to, because the one
+        // authoring slip that could otherwise reach it — the same note named twice, where the second
+        // pass finds the block the first already removed — is refused when the suite is parsed.
+        throw new Error(`eval: the prompt arm could not remove [${outcome.leaked.join(', ')}] from the rating ` +
+            `prompt for "${command}" — core builds that note for this command but it was not found in ` +
+            'the prompt. The arm and the prompt builder have diverged; this cell would have rated the ' +
+            'un-omitted prompt.');
+    }
+    if (capture && outcome.sent)
+        capture.prompt = outcome.sent;
+}
+//# sourceMappingURL=raterPromptArm.js.map

package/dist/raterPromptArm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raterPromptArm.js","sourceRoot":"","sources":["../src/raterPromptArm.ts"],"names":[],"mappings":"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"}

package/dist/raterTarget.d.ts

@@ -3,7 +3,7 @@
  * BATCH-25 Half B — the `rater` classification target: grade gth's OWN approvals rater over a
  * corpus of shell commands.
  *
- * It is the {@link ../evalTypes.js RunClassifyFn} seam Half A defined, and nothing more. Every case
+ * It is the {@link "evalTypes.js"!RunClassifyFn | RunClassifyFn} seam Half A defined, and nothing more. Every case
  * is a sequence of commands; each round is put through the SAME three pieces the production gate
  * uses — `rateShellCommand` (the rating prompt), `mapVerdictToAction` (the rung-keyed decision
  * mapping) and `ShellNegotiationState` (§5's transcript and its two bounds) — and what they return
@@ -23,8 +23,9 @@
  *    because the argument ran out is produced nowhere else, so `neg-01-escalate` — the same command
  *    proposed three times, ending at a human — is not expressible without it.
  *
- * Both come from core's own {@link import('@gaunt-sloth/core/core/shell/negotiation.js')
- * ShellNegotiationState}, the class the production runner drives, rather than from counters of our
+ * Both come from core's own
+ * {@link @gaunt-sloth/core!core/shell/negotiation.ShellNegotiationState | ShellNegotiationState},
+ * the class the production runner drives, rather than from counters of our
  * own. Re-implementing "when is this round-1" or "when is the bound spent" here would be exactly the
  * second opinion rule 1 below forbids — and §5.6's warning is that an implementation clearing the
  * counter without the transcript *"looks correct and passes any obvious test"*.
@@ -39,15 +40,16 @@
  *    eval facility has no second opinion about what a rating MEANS, and cannot drift from the thing
  *    it measures. A suite's `classification.labels` is the only place the vocabulary is written
  *    down, and it is authored, not compiled in.
- * 2. **A model-free decision reports no label.** See {@link classifyOneRound}.
+ * 2. **A model-free decision reports no label.** See `classifyOneRound`.
  */
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import type { GthConfig } from '@gaunt-sloth/core/config.js';
+import type { RaterPromptArm } from '#src/raterPromptArm.js';
 import { HARDLINE_REFUSAL_MARKER } from '#src/evalTypes.js';
 import type { ForcedByMechanism, PreflightMechanism, RaterTarget, RunClassifyFn } from '#src/evalTypes.js';
 /**
  * The marker a rationale carries when the §8 hardline floor refuses the command — see
- * {@link ../evalTypes.js HARDLINE_REFUSAL_MARKER} for why it is a rationale marker and not a label.
+ * {@link "evalTypes.js"!HARDLINE_REFUSAL_MARKER | HARDLINE_REFUSAL_MARKER} for why it is a rationale marker and not a label.
  * Re-exported here, beside the code that emits it:
  *
  * ```yaml
@@ -102,7 +104,7 @@ export declare const NEGOTIATION_BOUND_MARKER = "negotiation bound spent";
  *
  * ## What the probes are for
  *
- * Two things, neither of which is attribution — {@link forcedMechanism} gets the arm's NAME from
+ * Two things, neither of which is attribution — `forcedMechanism` gets the arm's NAME from
  * core directly:
  *
  * 1. **They derive the permissive rating.** A preflight raises only an outcome below core's
@@ -114,14 +116,14 @@ export declare const NEGOTIATION_BOUND_MARKER = "negotiation bound spent";
  *    corpus. That belongs in a unit test here rather than in someone's eval report, which is what
  *    {@link calibrateMechanisms} is for.
  *
- * The probe table is typed as a TOTAL record over {@link ../evalTypes.js PreflightMechanism}, which
+ * The probe table is typed as a TOTAL record over {@link "evalTypes.js"!PreflightMechanism | PreflightMechanism}, which
  * derives from core's own preflight list — so a preflight core gains does not compile here until
  * someone writes the command that observes it.
  *
  * A probe cannot be run with NO verdict: the preflights raise only an outcome below the
  * deterministic floor, and a missing verdict becomes core's fail-closed one, which is *at* the
  * floor. Every command then comes back with the identical placeholder — see
- * {@link ../evalTypes.js PREFLIGHT_MECHANISMS} for the whole rule.
+ * {@link "evalTypes.js"!PREFLIGHT_MECHANISMS | PREFLIGHT_MECHANISMS} for the whole rule.
  *
  * Exported for the unit suite, which exercises each mechanism on a command that is NOT its probe:
  * that test has to be able to prove the two differ, or it silently stops being that test.
@@ -135,7 +137,7 @@ export declare const MECHANISM_PROBES: Readonly<Record<PreflightMechanism, strin
  * fail across every corpus. That must be a red unit test rather than a surprise in someone's eval
  * report.
  *
- * Attribution itself is not at stake. {@link forcedMechanism} names the arm from core's
+ * Attribution itself is not at stake. `forcedMechanism` names the arm from core's
  * `preflightFloorFinding` rather than from this index, so two mechanisms that came to share a
  * sentence stay individually attributable — a shrunken map is the SIGNAL that something moved, not
  * the damage it causes.
@@ -143,7 +145,7 @@ export declare const MECHANISM_PROBES: Readonly<Record<PreflightMechanism, strin
 export declare function calibrateMechanisms(): Map<string, ForcedByMechanism>;
 /**
  * The rating a `forced_by: <preflight>` round is driven with, discovered from core rather than
- * spelled — see {@link calibrateGate}. Exported for the unit suite, which pins that it is an outcome
+ * spelled — see `calibrateGate`. Exported for the unit suite, which pins that it is an outcome
  * the gate APPROVES on a command with no preflight (i.e. genuinely permissive, so overriding it is a
  * real finding), without naming one.
  */
@@ -157,8 +159,28 @@ export interface RaterClassifierOptions {
     /** `$HOME`, for the prompt's home-path folding. Defaults to the process environment's, exactly as
      * production does. */
     home?: string;
-    /** Rating-call timeout; defaults to core's `RATER_DEFAULT_TIMEOUT_MS`. */
+    /**
+     * Timeout for ONE model call of the gate — the rating call, and the alignment check behind it.
+     * Absent, each falls back to the run's `approvals.raterTimeoutMs` and then to core's
+     * `RATER_DEFAULT_TIMEOUT_MS`.
+     *
+     * It is one budget PER CALL and not one shared across both, because that is core's contract
+     * (`AlignmentCheckOptions.timeoutMs`) and production's behaviour: `GthAgentRunner` hands the same
+     * resolved value to each. A declined command at a negotiating rung therefore costs up to twice
+     * this in wall-clock, which is what the rationale's two fail-closed sentences let a reader see.
+     */
     timeoutMs?: number;
+    /**
+     * [[BATCH-31]] — this cell's PROMPT ARM: which of our own preflight notes its ratings go out
+     * without, so one suite can express a note-on / note-off comparison instead of two.
+     *
+     * It does NOT mirror an option `rateShellCommand` takes, and that is the design rather than an
+     * inconsistency with the options above: a suppression the gate itself understood would be a
+     * switch inside the gate. What arrives here is a declaration; what removes the note is a model
+     * decorator built in this package. See `raterPromptArm.ts` for the whole argument, including how
+     * the omission is kept out of every route a session can reach.
+     */
+    notes?: RaterPromptArm;
 }
 /**
  * Build the {@link RunClassifyFn} for a {@link RaterTarget} — the whole of Half B.
@@ -168,7 +190,7 @@ export interface RaterClassifierOptions {
  * config error into an N-times-repeated one and add a profile load to every case's latency.
  *
  * @param target The parsed `rater` target (its `rung` is the suite's declaration — see
- *   {@link resolveRung}).
+ *   `resolveRung`).
  * @param config The run's resolved config — the sweep cell's, when sweeping, so `model:` and
  *   `config: { approvals: … }` axes both land here.
  * @param options Test/caller overrides; see {@link RaterClassifierOptions}.