bareloop 0.10.0 → 0.12.0

package/types/reviewdoor.d.ts

@@ -0,0 +1,81 @@
+/** the door's own record, off the run's spine — the LAST one, because a run that
+ * ends at a door writes exactly one and a reader that guesses which is which is a
+ * reader that will one day answer the wrong question.
+ * @param {any[]} events the run's spine, parsed
+ * @returns {any|null} */
+export function doorRecordOf(events: any[]): any | null;
+/**
+ * IS THE DOOR STILL OPEN? The same 60-day TTL a hitl checkpoint keeps
+ * (`PAUSE_TTL_MS`) and deliberately the same NUMBER — the door replaced `cancel`
+ * precisely because an unanswered door and an unresumed pause are one state, and
+ * two TTLs for one state is how they come to disagree.
+ *
+ * An UNREADABLE stamp refuses too: unknown is not young (F6). Reading the age is
+ * not the same as deciding on it, so this states both the answer and the arithmetic.
+ * @param {any} door the door record
+ * @param {{now?: () => number, ttlMs?: number}} [opts]
+ * @returns {{ok: boolean, ageMs: number|null, ttlMs: number, detail: string}}
+ */
+export function doorAgeGate(door: any, { now, ttlMs }?: {
+    now?: () => number;
+    ttlMs?: number;
+}): {
+    ok: boolean;
+    ageMs: number | null;
+    ttlMs: number;
+    detail: string;
+};
+/**
+ * Answer a run's review door.
+ *
+ * Never throws and never conjures: a malformed decision, a run that opened no
+ * door, an expired one, a tree that moved and a registry that is not there all
+ * come back as named reds. The loop's verdict is untouched on every path — this
+ * function has no way to write one.
+ *
+ * @param {object} opts
+ * @param {any} opts.job the SIGNED spec the run was judged by (its close is what an accept re-proves)
+ * @param {string} opts.workdir the patient, as it stands NOW
+ * @param {any[]} opts.events the run's own spine, parsed
+ * @param {string} opts.decision one of the three doors
+ * @param {string|null} [opts.text] the rerun's words — the gap, and refused when empty
+ * @param {number} [opts.closeTimeoutMs] the per-stage bound for the accept's re-run
+ * @param {string|null} [opts.registryDir] the workflow registry, when the runner keeps one
+ * @param {string|null} [opts.name] the workflow this run wrote its row against
+ * @param {string|null} [opts.runid] the RUN's id, exactly as the bridge row records it
+ * @param {string|null} [opts.at] when the person answered
+ * @param {() => number} [opts.now] the clock, injected for the TTL
+ * @param {number} [opts.ttlMs]
+ * @param {((type: string, data: any) => any)|null} [opts.emit] the run's spine, to record the disposition on
+ * @returns {Promise<{ok: boolean, decision: string|null, next: string|null, released: boolean,
+ *   doorRecorded: boolean, reds: any[], mechanical: any, door: any, text: string|null,
+ *   options: string[], ttlMs: number, note: string|null}>}
+ */
+export function answerReviewDoor({ job, workdir, events, decision, text, closeTimeoutMs, registryDir, name, runid, at, now, ttlMs, emit, }: {
+    job: any;
+    workdir: string;
+    events: any[];
+    decision: string;
+    text?: string | null | undefined;
+    closeTimeoutMs?: number | undefined;
+    registryDir?: string | null | undefined;
+    name?: string | null | undefined;
+    runid?: string | null | undefined;
+    at?: string | null | undefined;
+    now?: (() => number) | undefined;
+    ttlMs?: number | undefined;
+    emit?: ((type: string, data: any) => any) | null | undefined;
+}): Promise<{
+    ok: boolean;
+    decision: string | null;
+    next: string | null;
+    released: boolean;
+    doorRecorded: boolean;
+    reds: any[];
+    mechanical: any;
+    door: any;
+    text: string | null;
+    options: string[];
+    ttlMs: number;
+    note: string | null;
+}>;

package/types/run.d.ts

@@ -34,6 +34,13 @@
  *   metered claude-json text provider for the toolless drafter); ignored on every Loop-driven provider
  * @param {(type: string, data?: object) => object} opts.emit spine emitter
  * @param {(tier: string) => any} [opts.providerFor] P: per-step model-tier provider factory (forwarded to the plan flow)
+ * @param {any} [opts.judgeProvider] SOFTGREEN — the provider a JUDGED close stage runs its
+ *   locate call through, wired by the operator and PINNED to `JUDGE_MODEL` (src/judged.js:
+ *   the only tier with established injection resistance upstream). Forwarded to the plan
+ *   flow. It is its own seam and not `provider`/`providerFor`, because the judge tier is
+ *   never a step knob and never agent-selectable; absent, a judged stage instrument-stops as
+ *   a wiring gap rather than grading on whatever binding happened to be at hand. Its spend
+ *   lands on this ledger as `judge-round` (see `ACCOUNTED_ROUND_TYPES`).
  * @param {number} [opts.capRuns] shell-owned iteration cap for the plan flow's
  *   CLOSE-FIX loop (a plan STEP runs under the strike ladder instead)
  * @param {number} [opts.strikeLimit] shell-owned strike ceiling for a plan step's ladder
@@ -97,12 +104,31 @@
  *        a manufactured-fixation probe). `true` is the ON/experimental arm; the
  *        default is the OFF arm. (Shell-owned seam, same doctrine as the provider
  *        binding.)
+ * @param {{decision: string, text?: string}|null} [opts.humanRuling] N4 — the SIGNER's
+ *   answer at a hitl pause (accept | rerun <text> | pause), carried by the leg that
+ *   RESUMES a paused run and forwarded verbatim to the plan flow. Absent on every
+ *   ordinary run; never authored and never defaulted (a defaulted answer to "is this
+ *   done?" is the rubber-stamp the class exists to prevent, 2026-08-12 §4).
+ * @param {{decision: string, text?: string|null, receivedAt?: string|null}|null} [opts.heldRuling]
+ *   F102 — the answer the CHECKPOINT holds (`readResume`'s `restart.pendingDecision`):
+ *   a decision a person already gave on a leg that stopped before a single round was
+ *   bought for it. Forwarded verbatim; the plan flow applies it exactly as a fresh one
+ *   and refuses a leg handed both. It is also what decides whether the TIME fold this
+ *   run declares is the chain's or this engagement's (F103).
+ * @param {boolean|null} [opts.reviewDoor] MODULE 8 — does this run END at the review
+ *   door (PRD v1.71 §3)? Forwarded verbatim to the plan flow, which owns the class
+ *   default. It changes what the run RECORDS and never what it returns: the door is a
+ *   disposition and the loop's verdict is not the door's to touch.
+ * @param {{text: string, fromRunid?: string|null, receivedAt?: string|null}|null} [opts.doorRerun]
+ *   MODULE 8 — this leg IS the fresh engagement a signer commissioned at a previous
+ *   run's review door, carrying their words. Forwarded verbatim.
  * @returns {Promise<string>} outcome: 'green' | 'already-green' | 'escalated' |
  *   'unapproved-spec' | 'job-red' | 'smoke-red' | 'plan-red' | 'check-red' |
  *   'close-red' | 'close-unsupported' | 'recipe-stale' | 'branch-red' | 'pricing-red' | 'provider-red' |
- *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' | `step-red:<id>`
+ *   'interpreter-red' | 'cap-halt' | 'wall-halt' | 'step-stalled' |
+ *   'hitl-pause' | 'hitl-decision-red' | `step-red:<id>`
  */
-export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch }: {
+export function runJob(rawSpec: object | string, { approvals, workdir, provider, nativeProvider, providerFor, judgeProvider, emit, capRuns, strikeLimit, shellCapUsd, closeTimeoutMs, layerRoot, bridge, priorSpentUsd, priorSpendComplete, priorWallMs, resumeSeed, resumeGrades, resumeReplans, resumeBranch, humanRuling, heldRuling, reviewDoor, doorRerun }: {
     approvals: unknown;
     workdir: string;
     provider: any;
@@ -114,6 +140,7 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     }) => any) | undefined;
     emit: (type: string, data?: object) => object;
     providerFor?: ((tier: string) => any) | undefined;
+    judgeProvider?: any;
     capRuns?: number | undefined;
     strikeLimit?: number | undefined;
     shellCapUsd?: number | undefined;
@@ -133,7 +160,38 @@ export function runJob(rawSpec: object | string, { approvals, workdir, provider,
     } | null | undefined;
     resumeBranch?: string | null | undefined;
     layerRoot?: boolean | undefined;
+    humanRuling?: {
+        decision: string;
+        text?: string;
+    } | null | undefined;
+    heldRuling?: {
+        decision: string;
+        text?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
+    reviewDoor?: boolean | null | undefined;
+    doorRerun?: {
+        text: string;
+        fromRunid?: string | null;
+        receivedAt?: string | null;
+    } | null | undefined;
 }): Promise<string>;
+/** @typedef {{code: string, path: string, detail?: string}} Red */
+/**
+ * THE ROUND RECORDS THE ONE LEDGER SUMS — as data, because two of them now exist
+ * and a hand-spelled condition per record is how a paid call comes to be free.
+ *
+ * `worker-round` is the attempt's own spend, metered per ROUND rather than per
+ * attempt-return (F12: a halted attempt's spend was invisible by 300×).
+ * `judge-round` is the CLOSE's, and it is the first spend a close has ever had:
+ * the judged floor (softgreen) buys a pinned locate call per artifact, and the
+ * budget-identity rule is that a budget funds the attempt PLUS its close. Both
+ * carry the honest `costUsd` — a null lands as `unpriced` and halts, never as $0.
+ *
+ * What is deliberately NOT here: `worker-result` / `worker-plan`, which are
+ * attempt TOTALS of the same rounds and would double-count.
+ */
+export const ACCOUNTED_ROUND_TYPES: readonly string[];
 export type Red = {
     code: string;
     path: string;