bareloop 0.1.0 → 0.3.0

package/types/ralph.d.ts

@@ -1,23 +1,86 @@
 /**
  * Run a close command; its exit code is the verdict (hard green, PRD §4).
- * 0 → satisfied; nonzero → needs_revision (gap fed back); spawn error → failed (terminal).
+ * `expect` → satisfied; any other exit → needs_revision (gap fed back).
+ *
+ * THE FORBIDDEN ZONE (PRD v1.11, F17; adaptlearn F25/V10). The two clean bands
+ * are green (exit == expect, judgment rendered) and red (exit != expect,
+ * judgment rendered). Every other outcome rendered NO JUDGMENT and is therefore
+ * NOT A VERDICT — it gets its own name and escalates; coercing one into a
+ * verdict IS the instrument fault (law #8 generalized):
+ *   - `failed`    — the close cannot RUN (spawn error).             → broken-close
+ *   - `timed-out` — it ran and never finished judging.              → close-timeout
+ *   - `killed`    — it died by signal (status null, no spawn error). → close-killed
+ *   - `crashed`   — it ran, exited, and judged nothing.             → close-crashed
+ * `timed-out` is split OUT of `failed` deliberately: "raise the timeout" and
+ * "fix the argv" are different human decisions, so pooling them erases the
+ * decision information the escalation exists to carry.
+ *
+ * `judged` is the judgment-rendered signal, and it is the hard one. Exit code
+ * ALONE cannot separate a crash-at-load from an honest red — they are
+ * byte-identical at this seam, and against `node --test` so are the test counts
+ * (node synthesizes ONE failing test for the file that crashed, so a crash
+ * reports `tests 1 / fail 1`, exactly like a one-assertion failure). So the
+ * signal cannot be "zero judged"; it must be a FLOOR against a declared
+ * baseline: litectx runs ~390 tests, and a run claiming it judged 1 did not
+ * judge. `judged.pattern` extracts one integer from the close's own (redacted)
+ * output; below `judged.min` the close crashed, WHATEVER its exit code says —
+ * and that check runs on the GREEN side too: a close that exits 0 having judged
+ * nothing is a confident fake green, the only real failure there is (law #8).
+ * `judged` is OPTIONAL — a linter or a hitl close may have no count to give —
+ * and its absence stamps `unaudited: true` so the blind spot is NAMED on the
+ * record rather than passed off as a trustworthy exit code.
+ *
+ * `redact` scrubs the close's own output at the SOURCE — before the gap becomes
+ * a spine event or a worker prompt — so a secret a checked command echoes
+ * (a 401 dumping an `Authorization: Bearer …` header) never enters the
+ * append-only spine (the hard line). It is INJECTED, not imported: the shell
+ * stays stdlib-only and un-gameable, and the redactor is a fixed shell
+ * primitive (bareguard's, wired by the interpreter), never an emergent
+ * component — so V4 holds. The shell's canonical emission IS the redacted text;
+ * a benign gap is returned byte-identical (default: identity).
+ * `cwd` is where the close RUNS, and it is load-bearing (F8): a close is a
+ * command in a repository — `npm test`, `make check` — and every one of them is
+ * cwd-relative. Run it anywhere but the workdir and the arbiter judges the wrong
+ * tree: exit-code-is-truth silently becomes exit-code-of-some-other-repo-is-truth.
+ * The default (the runner's own cwd) exists only for callers with an absolute
+ * close; the runner and the interpreter always pass the workdir.
+ *
+ * `gapKeep` (F28) is a regex SOURCE whose matching lines are PRESERVED through
+ * the gap bound in addition to the head/tail sample: a large TAP suite prints
+ * its `not ok` lines in the middle of the stream, exactly where `boundGap`
+ * elides — so the failing-test NAMES (the causal input the worker navigates on)
+ * were deleted in transit and the worker was told "5 fail" and never WHICH. It
+ * is arbiter territory like the rest here: the drafted config cannot express it.
+ *
  * @param {string[]} close argv, e.g. ['node', '--test', 'close/']
+ * @param {(s: string) => string} [redact] source scrubber; identity by default
+ * @param {{ timeoutMs?: number, cwd?: string, expect?: number, judged?: {pattern: string, min: number}, gapKeep?: string }} [opts]
+ *   close wall-clock cap (operator-set via the runner, never the config's — the
+ *   agent must not author its arbiter's clock), the directory the close runs in
+ *   (the workdir — the tree it is judging), the exit code the SIGNED spec calls
+ *   success, the judgment-rendered signal, and the kept-failures pattern. All
+ *   five are arbiter territory: the drafted workflow config cannot express any.
+ * @returns {{verdict: 'satisfied'|'needs_revision'|'failed'|'timed-out'|'killed'|'crashed',
+ *   gap?: string, exitCode?: number, signal?: string, detail?: string,
+ *   judgedCount?: number|null, unaudited?: boolean}}
  */
-export function runClose(close: string[]): {
-    verdict: string;
-    detail: string;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    detail?: undefined;
-    gap?: undefined;
-    exitCode?: undefined;
-} | {
-    verdict: string;
-    gap: string;
-    exitCode: number | null;
-    detail?: undefined;
+export function runClose(close: string[], redact?: (s: string) => string, { timeoutMs, cwd, expect, judged, gapKeep }?: {
+    timeoutMs?: number;
+    cwd?: string;
+    expect?: number;
+    judged?: {
+        pattern: string;
+        min: number;
+    };
+    gapKeep?: string;
+}): {
+    verdict: "satisfied" | "needs_revision" | "failed" | "timed-out" | "killed" | "crashed";
+    gap?: string;
+    exitCode?: number;
+    signal?: string;
+    detail?: string;
+    judgedCount?: number | null;
+    unaudited?: boolean;
 };
 /**
  * The loop: `while close-red and under-cap: run the middle`. Stops at first
@@ -38,11 +101,54 @@ export function runClose(close: string[]): {
  * @param {string[]} opts.close argv whose exit code is truth
  * @param {number} opts.capRuns budget: max middle runs
  * @param {(type: string, data?: object) => object} opts.emit a spine emitter
+ * @param {(s: string) => string} [opts.redact] source scrubber for close output
+ *   (secrets never enter the spine); injected so the shell stays stdlib-only
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell/operator
+ *   territory — the workflow config cannot express it)
+ * @param {string} [opts.cwd] the directory every close runs in — the tree it is
+ *   judging (F8: a cwd-relative close run elsewhere judges the wrong repository)
+ * @param {number} [opts.expect] the exit code the SIGNED spec calls success
+ * @param {{pattern: string, min: number}} [opts.judged] the judgment-rendered signal
+ * @param {string} [opts.gapKeep] kept-failures pattern (F28): matching close-output
+ *   lines survive the gap bound so a large suite's `not ok` names reach the worker
+ * @param {() => string[]} [opts.workerWrites] the crash-attribution instrument (F32):
+ *   answers "which files has the WORKER written so far this run?" — the runner wires
+ *   it to the gate audit's allow-decision writes. Injected like `redact` so the shell
+ *   stays stdlib-only and dumb; consulted ONLY at a crashed verdict. With no seam, or
+ *   with zero writes, a crash stays what it always was: an instrument stop.
  * @returns {Promise<'green'|'escalated'>}
  */
-export function ralph({ middle, close, capRuns, emit }: {
+export function ralph({ middle, close, capRuns, emit, redact, closeTimeoutMs, cwd, expect, judged, gapKeep, workerWrites }: {
     middle: (iteration: number, gap?: string) => void | Promise<void>;
     close: string[];
     capRuns: number;
     emit: (type: string, data?: object) => object;
+    redact?: ((s: string) => string) | undefined;
+    closeTimeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    expect?: number | undefined;
+    judged?: {
+        pattern: string;
+        min: number;
+    } | undefined;
+    gapKeep?: string | undefined;
+    workerWrites?: (() => string[]) | undefined;
 }): Promise<"green" | "escalated">;
+/**
+ * The forbidden zone, named (PRD v1.11). Each row is an outcome in which the
+ * close rendered NO JUDGMENT — so it is not a verdict, it never feeds a gap
+ * back, and it is never retried. They are kept SEPARATE on purpose: pooling
+ * them would erase the decision information the escalation exists to carry —
+ * "raise the timeout", "fix the argv", and "re-run, it was OOM-killed" are
+ * three different human answers.
+ * Exported because the RUNNER's close-first precheck runs the same arbiter
+ * before any tokens: two maps would be two instruments, and two instruments
+ * disagreeing about the same outcome is the fault this whole addendum exists
+ * to close.
+ * @type {Record<string, {category: string, decision: string, options: string[]}>}
+ */
+export const CLOSE_FAULTS: Record<string, {
+    category: string;
+    decision: string;
+    options: string[];
+}>;

package/types/run.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Run an approved job end to end: approval gate → primitive smoke → sequential
+ * per-step interpret loops under the one ledger → the hitl step opens the draft
+ * PR (deterministic git, never model tools) and becomes the decision-ready
+ * escalation. Every predicate step runs its close FIRST (close-first skip,
+ * resume model): already-green skips the step for zero tokens as a distinct
+ * spine record, so a stopped run reruns from where it died — the workdir plus
+ * the closes are the checkpoint. The sealed config draft (one shot + one
+ * redraft) is deferred to the first step that actually needs a worker; a clean
+ * rerun pays zero provider calls.
+ *
+ * N2 bounds (honest, documented): text-mode steps write a single `target`
+ * artifact; tool-mode steps (2b) work multi-file through the gated shell tools,
+ * granted per step by the SPEC (mode/tools — the drafted config cannot express
+ * either); `gold`/`rubric` closes refuse `close-unsupported` (execution lands
+ * with the verdict classes, N4); the pricing-red halt lands at the step
+ * boundary — the Gate still caps within a step, but an unpriced result cannot
+ * be summed, so the run stops rather than counting it $0 (F6).
+ *
+ * @param {object|string} rawSpec the job spec (job-v1), text or parsed
+ * @param {object} opts
+ * @param {unknown} opts.approvals `{ specHash, signer, ts }` records (from OUTSIDE the spec)
+ * @param {string} opts.workdir the run directory (the fence's root)
+ * @param {string} [opts.target] the step artifact path (text-mode steps; unused by tool-mode steps)
+ * @param {any} opts.provider shell-owned LLM binding (never the config's)
+ * @param {(type: string, data?: object) => object} opts.emit spine emitter
+ * @param {number} [opts.capRuns] shell-owned per-step iteration cap
+ * @param {number} [opts.shellCapUsd] the shell's hard USD ceiling
+ * @param {number} [opts.closeTimeoutMs] close wall-clock cap (shell territory)
+ * @param {ExecCmd} [opts.execCmd] process runner for the hitl PR mechanics
+ *        (shell-owned seam, same doctrine as the provider binding)
+ * @returns {Promise<string>} outcome: 'green' | 'escalated' | 'unapproved-spec' |
+ *   'job-red' | 'smoke-red' | 'config-red' | 'pricing-red' | 'provider-red' |
+ *   'cap-halt' | 'close-unsupported' | `step-red:<id>`
+ */
+export function runJob(rawSpec: object | string, { approvals, workdir, target, provider, emit, capRuns, shellCapUsd, closeTimeoutMs, execCmd }: {
+    approvals: unknown;
+    workdir: string;
+    target?: string | undefined;
+    provider: any;
+    emit: (type: string, data?: object) => object;
+    capRuns?: number | undefined;
+    shellCapUsd?: number | undefined;
+    closeTimeoutMs?: number | undefined;
+    execCmd?: ExecCmd | undefined;
+}): Promise<string>;
+export type Red = {
+    code: string;
+    path: string;
+    detail?: string;
+};
+export type ExecCmd = (argv: string[], opts?: {
+    cwd?: string;
+}) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+};

package/types/text.d.ts

@@ -1 +1,35 @@
-export function stripFences(t: string): string;
+/**
+ * Fence-robust artifact extraction (F2 port requirements #1/#2):
+ * - a fenced block opening within the first {@link FENCE_PREAMBLE_LINES} lines
+ *   is the artifact — prose-wrapped and preamble fences extract clean (the F21
+ *   instrument caveat: prose written to the target corrupted the close signal);
+ * - a fence opening deeper is the artifact's own content — the trimmed whole
+ *   text is the artifact (fence-heavy artifacts belong in tool mode, where the
+ *   worker writes files directly and nothing is parsed);
+ * - no fence → the trimmed whole text, with N0's unclosed-leading-fence strip
+ *   as the fallback (reference parity);
+ * - nothing extractable → `code: null` plus a named reason: artifact-red
+ *   material for the caller's OWN axis, never a silent empty write.
+ * Never throws.
+ * @param {string|null|undefined} t
+ * @returns {{ code: string|null, red: string|null }}
+ */
+export function extractArtifact(t: string | null | undefined): {
+    code: string | null;
+    red: string | null;
+};
+/**
+ * The ONE spelling of the F6 honest-null cost read on a bare-agent result.
+ * `metrics.costUsd` is the honest null when NOTHING priced — never fall
+ * through to `cost` when metrics exist: `cost` sums priced rounds only, so an
+ * all-unpriced run reports cost 0 and `?? cost` would launder the explicit
+ * unknown into a silent $0 (the F6 class — four shipped launderings were this
+ * exact fallback chain hand-spelled). `unpricedRounds` makes a PARTIALLY
+ * unpriced run visible (costUsd finite but an under-count).
+ * @param {any} r a Loop.run() result (or null)
+ * @returns {{ costUsd: number|null, unpricedRounds: number }}
+ */
+export function priceOf(r: any): {
+    costUsd: number | null;
+    unpricedRounds: number;
+};

package/types/validate.d.ts

@@ -9,13 +9,54 @@
  */
 export function globToPrefix(scope: string): string;
 /**
- * Validate a workflow config against schema v1.
+ * A scope may never reach the arbiter's inputs (design law #1): it must
+ * resolve to a PROPER subdirectory of the run directory. Absolute paths and
+ * ".." segments escape it; "." / "./**" cover the whole run directory — where
+ * the close suite lives. Windows spellings ("..\", "C:\") count as escapes.
+ * Exported for the job validator: the operator's outer fence obeys the SAME
+ * law through the same code — two containment transforms would be the F9
+ * red-class one level up.
+ * @param {string} s
+ */
+export function scopeContained(s: string): boolean;
+/** Shared with the job validator — one definition of "a JSON object" for both
+ * documents (the sibling-validator drift class).
+ * @param {unknown} v */
+export function isObj(v: unknown): boolean;
+/** @param {unknown} v @returns {v is string} */
+export function isNonEmptyString(v: unknown): v is string;
+/**
+ * Scan a RAW text stream (a spine file, a close's output, a transcript) for
+ * known secret shapes and return the literal matches. The ONE spelling of the
+ * text-side scan, for the same reason SECRET_PATTERNS is the ONE inventory: a
+ * hand-rolled copy that misses a shape is a leak on the very output it guards
+ * (seven copies of this expression lived in scripts/ before it landed here).
+ * `sweepSecretLiterals` is the config-tree twin — same shapes, tree walk.
+ * Never throws; returns [] for a missing stream.
+ * @param {unknown} raw
+ * @returns {string[]} every match, in stream order per pattern
+ */
+export function scanSecrets(raw: unknown): string[];
+/**
+ * Red every string in a config tree that carries a known secret-token shape.
+ * @param {any} root
+ * @param {(code: string, path: string, detail?: string) => void} red
+ */
+export function sweepSecretLiterals(root: any, red: (code: string, path: string, detail?: string) => void): void;
+/**
+ * Validate a workflow config against schema v1. Returns the parsed config on
+ * ok (single parse — callers never re-parse; null on any red).
  * @param {object|string} input parsed config, or raw JSON text (parse failures are a red)
- * @param {{ shellCapUsd?: number }} [opts] the shell's cap — a config may tighten it, never exceed it
- * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}> }}
+ * @param {{ shellCapUsd?: number, jobWriteScope?: string[] }} [opts] the shell's
+ *   ceilings — a config may tighten either, never exceed. `shellCapUsd`: at N2+
+ *   the shell passes min(shell cap, job budgetUsd) — the ceiling chain
+ *   workflow ≤ job ≤ shell. `jobWriteScope`: the job spec's outer fence
+ *   (operator law, job-v1) — every workflow scope must fit inside it.
+ * @returns {{ ok: boolean, reds: Array<{code: string, path: string, detail?: string}>, config: object|null }}
  */
-export function validateConfig(input: object | string, { shellCapUsd }?: {
+export function validateConfig(input: object | string, { shellCapUsd, jobWriteScope }?: {
     shellCapUsd?: number;
+    jobWriteScope?: string[];
 }): {
     ok: boolean;
     reds: Array<{
@@ -23,6 +64,7 @@ export function validateConfig(input: object | string, { shellCapUsd }?: {
         path: string;
         detail?: string;
     }>;
+    config: object | null;
 };
 /**
  * Changed JSON paths between two configs — the one-knob mutation checker
@@ -33,6 +75,8 @@ export function validateConfig(input: object | string, { shellCapUsd }?: {
  * @returns {string[]} sorted changed paths, dot-notation with array indices
  */
 export function diffPaths(a: object, b: object): string[];
-export const LOOP_SHAPES: string[];
-export const SLOTS: string[];
-export const VERBS: string[];
+export const LOOP_SHAPES: readonly string[];
+export const SLOTS: readonly string[];
+export const VERBS: readonly string[];
+export const REMEMBER_KINDS: string[];
+export const SECRET_PATTERNS: RegExp[];