@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/input-scan/tokens.js

@@ -12,6 +12,8 @@
  * specific class every one of its values satisfies.
  */
 import { KNOWN_EXTENSIONS } from "./formats.js";
+import { isAllDigits, isAllHex } from "../lib/text.js";
+import { presentAt, presentFirst } from "../lib/present.js";
 import { MAX_OPAQUE_ID_MEAN_RUN, MAX_OPAQUE_ID_SEPARATOR_FRACTION, MAX_SUFFIX_TOKEN_LENGTH, MIN_OPAQUE_ID_CASE_FLIPS, MIN_OPAQUE_ID_CHAR_CLASSES, MIN_OPAQUE_ID_DIGIT_FRACTION, MIN_OPAQUE_ID_LENGTH, OPAQUE_ID_CASE_FLIP_DIVISOR, } from "./tuning.js";
 export const ID_SYMBOL = "ID";
 export const DIGIT_SYMBOL = "#";
@@ -33,45 +35,106 @@ export function splitStem(fileName) {
     const parts = fileName.split(".");
     let cut = parts.length;
     while (cut > 1) {
-        const candidate = parts[cut - 1].toLowerCase();
+        const candidate = presentAt(parts, cut - 1, "the trailing extension part").toLowerCase();
         if (!KNOWN_EXTENSIONS.has(candidate) || candidate.length > MAX_SUFFIX_TOKEN_LENGTH)
             break;
         cut--;
     }
     return { stem: parts.slice(0, cut).join("."), suffix: parts.slice(cut).join(".").toLowerCase() };
 }
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the fixed 8-4-4-4-12 hex groups are what make an identifier machine-issued rather than written.
 const UUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-const HEX_DIGEST_PATTERN = /^(?:[0-9a-fA-F]{32}|[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$/;
-const BASE64URL_PATTERN = /^[A-Za-z0-9\-_=]+$/;
+const DIGEST_HEX_LENGTHS = new Set([32, 40, 64]);
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- captures year, month, and day out of `2026-08-24` or `2026_08_24` for the calendar range check below.
 const DELIMITED_DATE_PATTERN = /^(\d{4})[-_](\d{2})[-_](\d{2})$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the same capture for the compact `20260824` form.
 const COMPACT_DATE_PATTERN = /^(\d{4})(\d{2})(\d{2})$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- finds a date fused inside a longer run; the lookarounds keep digits outside the date in their own runs.
+const EMBEDDED_DATE_PATTERN = /(?<![0-9])(?:\d{4}[-_]\d{2}[-_]\d{2}|\d{8})(?![0-9])/g;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- letter and digit runs are the shape whose mean length separates written words from random class-mixed tokens.
+const ALPHA_DIGIT_RUN_PATTERN = /[A-Za-z]+|[0-9]+/g;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- splits a run into letter, digit, and `-_=` separator tokens; the three classes are the token lattice below.
+const TOKEN_RUN_PATTERN = /[A-Za-z]+|[0-9]+|[-_=]+/g;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- splits a path segment into base64url-charset runs and the runs outside that charset, each whole.
+const SEGMENT_RUN_PATTERN = /[A-Za-z0-9\-_=]+|[^A-Za-z0-9\-_=]+/g;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- an alphanumeric run of three or more characters inside a shared affix is identifier material to mask.
+const MASKABLE_RUN_PATTERN = /[A-Za-z0-9]{3,}/g;
+function isAsciiUpper(char) {
+    return char >= "A" && char <= "Z";
+}
+function isAsciiLower(char) {
+    return char >= "a" && char <= "z";
+}
+export function isAsciiLetter(char) {
+    return isAsciiUpper(char) || isAsciiLower(char);
+}
+export function isAsciiDigit(char) {
+    return char >= "0" && char <= "9";
+}
+function isBase64UrlSymbol(char) {
+    return char === "-" || char === "_" || char === "=";
+}
+function isAlphanumeric(char) {
+    return isAsciiLetter(char) || isAsciiDigit(char);
+}
+function hasAsciiUpper(value) {
+    return Array.from(value).some(isAsciiUpper);
+}
+function hasAsciiLower(value) {
+    return Array.from(value).some(isAsciiLower);
+}
+function hasAsciiLetter(value) {
+    return Array.from(value).some(isAsciiLetter);
+}
+function hasAsciiDigit(value) {
+    return Array.from(value).some(isAsciiDigit);
+}
+function hasAlphanumeric(value) {
+    return Array.from(value).some(isAlphanumeric);
+}
+function isBase64UrlRun(value) {
+    return value.length > 0 && Array.from(value).every((char) => isAlphanumeric(char) || isBase64UrlSymbol(char));
+}
+function isHexRun(value) {
+    return value.length > 0 && isAllHex(value);
+}
 function charClassCount(value) {
     let classes = 0;
-    for (const pattern of [/[A-Z]/, /[a-z]/, /[0-9]/, /[-_=]/])
-        if (pattern.test(value))
-            classes++;
+    if (hasAsciiUpper(value))
+        classes++;
+    if (hasAsciiLower(value))
+        classes++;
+    if (hasAsciiDigit(value))
+        classes++;
+    if (Array.from(value).some(isBase64UrlSymbol))
+        classes++;
     return classes;
 }
 function meanRunLength(value) {
-    const runs = value.match(/[A-Za-z]+|[0-9]+/g) ?? [];
+    const runs = value.match(ALPHA_DIGIT_RUN_PATTERN) ?? [];
     if (runs.length === 0)
         return 0;
     return runs.reduce((total, run) => total + run.length, 0) / runs.length;
 }
 function caseTransitions(value) {
+    const chars = value.split("");
     let flips = 0;
-    for (let i = 1; i < value.length; i++) {
-        const before = value[i - 1];
-        const after = value[i];
-        if (!/[A-Za-z]/.test(before) || !/[A-Za-z]/.test(after))
+    for (let i = 1; i < chars.length; i++) {
+        const before = presentAt(chars, i - 1, "case-run characters");
+        const after = presentAt(chars, i, "case-run characters");
+        if (!isAsciiLetter(before) || !isAsciiLetter(after))
             continue;
         if ((before === before.toUpperCase()) !== (after === after.toUpperCase()))
             flips++;
     }
     return flips;
 }
-function fractionOf(value, pattern) {
-    return (value.match(pattern) ?? []).length / value.length;
+function charFraction(value, matches) {
+    let count = 0;
+    for (const char of value)
+        if (matches(char))
+            count++;
+    return count / value.length;
 }
 /**
  * A machine-issued identifier: a UUID, a fixed-length hex digest, or a long
@@ -86,20 +149,20 @@ function fractionOf(value, pattern) {
 export function isOpaqueId(value) {
     if (UUID_PATTERN.test(value))
         return true;
-    if (HEX_DIGEST_PATTERN.test(value))
+    if (isHexRun(value) && DIGEST_HEX_LENGTHS.has(value.length))
         return true;
     if (value.length < MIN_OPAQUE_ID_LENGTH)
         return false;
-    if (!BASE64URL_PATTERN.test(value))
+    if (!isBase64UrlRun(value))
         return false;
     if (charClassCount(value) < MIN_OPAQUE_ID_CHAR_CLASSES)
         return false;
     const flipBudget = Math.max(MIN_OPAQUE_ID_CASE_FLIPS, Math.floor(value.length / OPAQUE_ID_CASE_FLIP_DIVISOR));
     if (caseTransitions(value) >= flipBudget)
         return true;
-    if (fractionOf(value, /[-_=]/g) > MAX_OPAQUE_ID_SEPARATOR_FRACTION)
+    if (charFraction(value, isBase64UrlSymbol) > MAX_OPAQUE_ID_SEPARATOR_FRACTION)
         return false;
-    return meanRunLength(value) <= MAX_OPAQUE_ID_MEAN_RUN && fractionOf(value, /[0-9]/g) >= MIN_OPAQUE_ID_DIGIT_FRACTION;
+    return meanRunLength(value) <= MAX_OPAQUE_ID_MEAN_RUN && charFraction(value, isAsciiDigit) >= MIN_OPAQUE_ID_DIGIT_FRACTION;
 }
 /** A calendar date written compactly or with a single separator: `20260824`, `2026-08-24`. */
 export function isDateToken(value) {
@@ -111,11 +174,11 @@ export function isDateToken(value) {
     const day = Number(parts[3]);
     return year >= 1900 && year <= 2999 && month >= 1 && month <= 12 && day >= 1 && day <= 31;
 }
-const EMBEDDED_DATE_PATTERN = /(?<![0-9])(?:\d{4}[-_]\d{2}[-_]\d{2}|\d{8})(?![0-9])/g;
 function pushRuns(text, into) {
-    for (const run of text.matchAll(/[A-Za-z]+|[0-9]+|[-_=]+/g)) {
+    for (const run of text.matchAll(TOKEN_RUN_PATTERN)) {
         const value = run[0];
-        const kind = /^[0-9]/.test(value) ? "digit" : /^[A-Za-z]/.test(value) ? "alpha" : "delim";
+        const head = value.charAt(0);
+        const kind = isAsciiDigit(head) ? "digit" : isAsciiLetter(head) ? "alpha" : "delim";
         into.push({ kind, value });
     }
 }
@@ -130,9 +193,9 @@ function pushRuns(text, into) {
  */
 export function tokenizeSegment(segment) {
     const tokens = [];
-    for (const match of segment.matchAll(/[A-Za-z0-9\-_=]+|[^A-Za-z0-9\-_=]+/g)) {
+    for (const match of segment.matchAll(SEGMENT_RUN_PATTERN)) {
         const value = match[0];
-        if (!/[A-Za-z0-9]/.test(value)) {
+        if (!hasAlphanumeric(value)) {
             tokens.push({ kind: "delim", value });
             continue;
         }
@@ -164,7 +227,7 @@ export function tokenizeName(fileName) {
     for (let i = 0; i < parts.length; i++) {
         if (i > 0)
             tokens.push({ kind: "delim", value: "." });
-        tokens.push(...tokenizeSegment(parts[i]));
+        tokens.push(...tokenizeSegment(presentAt(parts, i, "stem dot-parts")));
     }
     return { tokens, suffix };
 }
@@ -191,7 +254,7 @@ export function classifyValues(values) {
     if (values.length === 0)
         return { tokenClass: "any" };
     if (values.length === 1) {
-        const only = values[0];
+        const only = presentFirst(values, "the single value");
         if (isDateToken(only))
             return { tokenClass: "date" };
         if (isOpaqueId(only))
@@ -200,24 +263,22 @@ export function classifyValues(values) {
     }
     if (values.every((value) => isDateToken(value)))
         return { tokenClass: "date" };
-    if (values.every((value) => /^[0-9]+$/.test(value))) {
-        const width = values[0].length;
+    if (values.every((value) => value.length > 0 && isAllDigits(value))) {
+        const width = presentFirst(values, "digit values").length;
         return values.every((value) => value.length === width) ? { tokenClass: "digits-fixed", width } : { tokenClass: "digits" };
     }
-    if (values.every((value) => /^[0-9a-fA-F]+$/.test(value) && value.length >= 4))
+    if (values.every((value) => isHexRun(value) && value.length >= 4))
         return { tokenClass: "hex" };
     if (values.every((value) => isOpaqueId(value))) {
         const lengths = values.map((value) => value.length);
         return { tokenClass: "opaque-id", minLength: Math.min(...lengths), maxLength: Math.max(...lengths) };
     }
-    if (values.every((value) => /^[A-Za-z]+$/.test(value)))
+    if (values.every((value) => value.length > 0 && Array.from(value).every(isAsciiLetter)))
         return { tokenClass: "word" };
     const skeletons = new Set(values.map((value) => maskSegment(value)));
-    if (skeletons.size === 1) {
-        const skeleton = [...skeletons][0];
-        if (skeleton.includes(DIGIT_SYMBOL) || skeleton.includes(ID_SYMBOL) || skeleton.includes(DATE_SYMBOL)) {
-            return { tokenClass: "pattern", skeleton };
-        }
+    const [skeleton] = skeletons;
+    if (skeleton !== undefined && skeletons.size === 1 && (skeleton.includes(DIGIT_SYMBOL) || skeleton.includes(ID_SYMBOL) || skeleton.includes(DATE_SYMBOL))) {
+        return { tokenClass: "pattern", skeleton };
     }
     return { tokenClass: "any" };
 }
@@ -230,7 +291,8 @@ export function classifyValues(values) {
 export function commonAffixes(values) {
     if (values.length < 2)
         return { prefix: "", suffix: "" };
-    let prefix = values[0];
+    const head = presentFirst(values, "affix values");
+    let prefix = head;
     for (const value of values) {
         let i = 0;
         while (i < prefix.length && i < value.length && prefix[i] === value[i])
@@ -239,7 +301,7 @@ export function commonAffixes(values) {
         if (!prefix)
             break;
     }
-    let suffix = values[0].slice(prefix.length);
+    let suffix = head.slice(prefix.length);
     for (const value of values) {
         const rest = value.slice(prefix.length);
         let i = 0;
@@ -259,9 +321,9 @@ export function commonAffixes(values) {
  * member happened to share it.
  */
 export function maskAffix(affix) {
-    return affix.replace(/[A-Za-z0-9]{3,}/g, (run) => {
-        const mixedCase = /[A-Z]/.test(run) && /[a-z]/.test(run);
-        const alphanumeric = /[A-Za-z]/.test(run) && /[0-9]/.test(run);
+    return affix.replace(MASKABLE_RUN_PATTERN, (run) => {
+        const mixedCase = hasAsciiUpper(run) && hasAsciiLower(run);
+        const alphanumeric = hasAsciiLetter(run) && hasAsciiDigit(run);
         return mixedCase || alphanumeric ? `<x${run.length}>` : run;
     });
 }

package/dist/input-scan/types.d.ts

@@ -10,7 +10,7 @@
  * into its submission would make its central judgement invisible.
  */
 /** One file the walk found. `path` is relative to the analysis root. */
-export interface ScannedFile {
+export type ScannedFile = {
     readonly path: string;
     readonly size: number;
     /** Trailing extension components, outermost last: `sample.vcf.gz` → `["vcf", "gz"]`. */
@@ -19,7 +19,7 @@ export interface ScannedFile {
     readonly format: string;
     /** Compression wrapper reported ALONGSIDE the inner format, never in place of it. */
     readonly wrapper?: string;
-}
+};
 /**
  * A filename position whose token differs across a shape's members.
  *
@@ -27,7 +27,7 @@ export interface ScannedFile {
  * identifier (`0001`…`800`) from a categorical label (`tumor`/`normal`) from a shard
  * index (`chr1`…`chr22`), and those readings imply entirely different kinds.
  */
-export interface VariablePosition {
+export type VariablePosition = {
     /** Token index within the shape's name pattern — the `<n>` placeholder it fills. */
     readonly index: number;
     /** Literal text immediately preceding the token, when any (`PT` in `PT001`). */
@@ -35,35 +35,35 @@ export interface VariablePosition {
     readonly distinctValues: number;
     /** Bounded sample of the values observed at this position. */
     readonly sampleValues: readonly string[];
-}
+};
 /**
  * How two variable positions vary together. A fully-crossed pair is a nested design
  * (every subject × every timepoint); a partially-crossed one is not, and the
  * difference is design evidence a flat file count destroys.
  */
-export interface PositionCooccurrence {
+export type PositionCooccurrence = {
     readonly positions: readonly [number, number];
     /** Distinct value pairs observed. */
     readonly observedPairs: number;
     /** Pairs the two value sets could form. `observedPairs === possiblePairs` is a full crossing. */
     readonly possiblePairs: number;
-}
+};
 /** Header fields read from a bounded prefix of one member of a shape. */
-export interface HeaderReadout {
+export type HeaderReadout = {
     /** The member the readout came from. */
     readonly path: string;
     /** Decoder-reported fields, flat and bounded (`delimiter`, `columns`, `sampleCount`, …). */
     readonly fields: Readonly<Record<string, string | number | boolean>>;
     /** Why no readout is present, when the decode did not produce one. */
     readonly unavailable?: string;
-}
+};
 /**
  * A set of files that are mechanically indistinguishable by name structure, format,
  * and location. A shape is an observation, never a grouping of the dataset: the
  * agent may split one shape into several kinds, cover several shapes with one kind,
  * or ignore the shape entirely.
  */
-export interface FileShape {
+export type FileShape = {
     /** Stable within one manifest (`shape-1`, `shape-2`, …) so overlaps can name shapes. */
     readonly id: string;
     /** Directory the members share, relative to the analysis root. */
@@ -81,7 +81,7 @@ export interface FileShape {
     readonly examplePaths: readonly string[];
     /** Present once the header readout has run for this shape. */
     readonly header?: HeaderReadout;
-}
+};
 /**
  * Value-set overlap between two shapes' variable positions, reported WITH its gaps.
  *
@@ -89,7 +89,7 @@ export interface FileShape {
  * text before comparing, and near-miss namings defeat it. Reported as evidence it is
  * useful; asserted as a shared axis it is a guess a consumer cannot tell was guessed.
  */
-export interface ShapeValueOverlap {
+export type ShapeValueOverlap = {
     readonly shapes: readonly [string, string];
     readonly positions: readonly [number, number];
     readonly sharedValues: number;
@@ -99,13 +99,13 @@ export interface ShapeValueOverlap {
     /** Bounded samples of the two gaps, so a near-complete correspondence names its misses. */
     readonly onlyInFirstSample: readonly string[];
     readonly onlyInSecondSample: readonly string[];
-}
+};
 /** One member of the no-shared-structure aggregate. */
-export interface UnstructuredEntry {
+export type UnstructuredEntry = {
     readonly path: string;
     readonly size: number;
     readonly format: string;
-}
+};
 /**
  * Files whose name structure matches no other file, in aggregate.
  *
@@ -114,7 +114,7 @@ export interface UnstructuredEntry {
  * capability exists to prevent. Whether these are notable singletons worth prose or
  * an unclassified remainder is the agent's determination.
  */
-export interface UnstructuredFiles {
+export type UnstructuredFiles = {
     readonly count: number;
     readonly totalBytes: number;
     /**
@@ -123,18 +123,18 @@ export interface UnstructuredFiles {
      * one file each — under whatever large files failed to group.
      */
     readonly sample: readonly UnstructuredEntry[];
-}
+};
 /** How many files carry each detected format, across the whole scanned tree. */
-export interface FormatCount {
+export type FormatCount = {
     readonly format: string;
     readonly count: number;
-}
+};
 /**
  * The agent-facing manifest: bounded by construction, so injecting it into a briefing
  * or returning it from `scan_inputs` costs a fixed amount of context whatever the tree
  * size. The complete per-file list lives on {@link InputScan}, host-side.
  */
-export interface InputScanManifest {
+export type InputScanManifest = {
     /** Path scanned, relative to the analysis root. */
     readonly root: string;
     readonly fileCount: number;
@@ -153,13 +153,13 @@ export interface InputScanManifest {
     readonly shapes: readonly FileShape[];
     readonly valueOverlaps: readonly ShapeValueOverlap[];
     readonly unstructured: UnstructuredFiles;
-}
+};
 /**
  * The scan's full result. `files` is the complete enumeration — it stays host-side and
  * backs coverage and the index projection; `manifest` is the bounded projection the
  * agent reads.
  */
-export interface InputScan {
+export type InputScan = {
     readonly files: readonly ScannedFile[];
     readonly manifest: InputScanManifest;
     /**
@@ -169,4 +169,4 @@ export interface InputScan {
      * tokenisation.
      */
     readonly positionValues: ReadonlyMap<string, readonly (readonly string[])[]>;
-}
+};

package/dist/lib/async-utils.d.ts

@@ -7,16 +7,12 @@ export declare function sleep(ms: number): Promise<void>;
  * Run each task with a cap on how many run at the same time, and give back the results in the order of
  * the input.
  *
- * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
- * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
- * is an array of thunks and not an array of promises, because a promise is already running when it is
- * made, and a cap over a set of started promises caps nothing.
+ * The input is an array of thunks and not an array of promises, because a promise is already running when
+ * it is made, and a cap over a set of started promises caps nothing.
  *
  * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
  *
  * The failure behavior is that of `Promise.all`. The first rejection rejects the whole call, and each
  * task that the queue already started still runs to completion.
  */
-export declare function allWithConcurrency<T extends readonly (() => unknown)[] | []>(tasks: T, concurrency: number): Promise<{
-    -readonly [P in keyof T]: Awaited<T[P] extends () => infer R ? R : never>;
-}>;
+export declare function allWithConcurrency<R>(tasks: ReadonlyArray<() => R | PromiseLike<R>>, concurrency: number): Promise<Awaited<R>[]>;

package/dist/lib/async-utils.js

@@ -1,19 +1,18 @@
 /**
  * Shared async utilities — sleep and a bounded-concurrency `Promise.all`.
  */
+import { setTimeout as timerSleep } from "node:timers/promises";
 import PQueue from "p-queue";
 /** Promise-based delay. */
 export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+    return timerSleep(ms);
 }
 /**
  * Run each task with a cap on how many run at the same time, and give back the results in the order of
  * the input.
  *
- * The signature mirrors `Promise.all`. The mapped return type is element-wise, thus a tuple of thunks
- * with different return types keeps each one, and a plain array of thunks gives a plain array. The input
- * is an array of thunks and not an array of promises, because a promise is already running when it is
- * made, and a cap over a set of started promises caps nothing.
+ * The input is an array of thunks and not an array of promises, because a promise is already running when
+ * it is made, and a cap over a set of started promises caps nothing.
  *
  * `concurrency` must be a number at or above 1. p-queue throws a `TypeError` for any other value.
  *
@@ -22,8 +21,5 @@ export function sleep(ms) {
  */
 export function allWithConcurrency(tasks, concurrency) {
     const queue = new PQueue({ concurrency });
-    // `addAll` collapses every task onto one result type, thus it cannot express the element-wise type
-    // above. The cast is sound because `addAll` maps the input array through `Promise.all`, which keeps
-    // the position of each task, and each element is the awaited return of the task at that position.
-    return queue.addAll(tasks);
+    return Promise.all(tasks.map((task) => queue.add(task)));
 }

package/dist/lib/cache.js

@@ -27,7 +27,7 @@ export class BoundedTtlCache {
         this.entries.set(key, { value, expiresAt: this.now() + ttlMs });
         while (this.entries.size > this.maximum) {
             const oldest = this.entries.keys().next().value;
-            if (oldest === undefined)
+            if (typeof oldest !== "string")
                 break;
             this.entries.delete(oldest);
         }

package/dist/lib/chrome.d.ts

@@ -8,9 +8,9 @@
  * A connection is lazy, and an endpoint connects again after a disconnect. Each endpoint also carries its own
  * page gate. The gate bounds the pages that run at the same time against that one sidecar.
  */
-import type { Browser, BrowserContext, Page } from "puppeteer-core";
+import type { ConsoleMessage, HTTPRequest, MediaFeature, ScreenshotOptions, Viewport, WaitForOptions } from "puppeteer-core";
 import type { Logger } from "./logger.js";
-export interface ChromeConfig {
+export type ChromeConfig = {
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
     /**
@@ -24,7 +24,7 @@ export interface ChromeConfig {
      */
     readonly browserUrl?: string;
     readonly maxPages?: number;
-}
+};
 /**
  * Whether the config names a browser to connect to. A composition with no endpoint has no eyes, and a
  * caller reads that up front instead of failing once for each attempted connection.
@@ -36,7 +36,47 @@ export declare function hasBrowserUrl(cfg: ChromeConfig): cfg is ChromeConfig &
     readonly browserUrl: string;
 };
 /** The connect operation of one endpoint. */
-export type BrowserConnector = (browserUrl: string) => Promise<Browser>;
+export type BrowserConnector = (browserUrl: string) => Promise<ConnectedBrowser>;
+/** A document area of one capture, in CSS pixels: the columns from `x`, and the rows from `fromY` to `toY`. */
+export type CaptureArea = {
+    readonly x: number;
+    readonly width: number;
+    readonly fromY: number;
+    readonly toY: number;
+};
+/** The browser context that one look runs in. */
+export type LookContext = {
+    newPage(): Promise<LookPage>;
+    close(): Promise<void>;
+};
+/** The page events that a look reads, with the payload each listener gets. */
+export type LookPageEvents = {
+    console: ConsoleMessage;
+    pageerror: Error;
+    requestfailed: HTTPRequest;
+};
+/**
+ * The page surface that a look reads, with no vendor type in the shape. The evaluate member carries the
+ * three call forms the capture module drives, each with the return type that the read of the result needs.
+ */
+export type LookPage = {
+    on<Key extends keyof LookPageEvents>(event: Key, listener: (event: LookPageEvents[Key]) => void): unknown;
+    setViewport(viewport: Viewport): Promise<void>;
+    emulateMediaFeatures(features: MediaFeature[]): Promise<void>;
+    goto(url: string, options?: WaitForOptions): Promise<unknown>;
+    waitForSelector(selector: string, options?: WaitForOptions): Promise<unknown>;
+    screenshot(options: ScreenshotOptions): Promise<string | Uint8Array>;
+    evaluate(pageFunction: () => number): Promise<number | undefined>;
+    evaluate(pageFunction: (attribute: string, blockId: string, margin: number) => CaptureArea | null, attribute: string, blockId: string, margin: number): Promise<CaptureArea | null>;
+    evaluate(pageFunction: (...args: never[]) => unknown, ...args: unknown[]): Promise<unknown>;
+};
+/** The browser surface that the connection cache reads: the live flag, the socket, and the page factory. */
+export type ConnectedBrowser = {
+    readonly connected: boolean;
+    on(event: "disconnected", listener: () => void): unknown;
+    wsEndpoint(): string;
+    createBrowserContext(): Promise<LookContext>;
+};
 /**
  * Replace the connect operation, and give back the restore of the previous one.
  *
@@ -48,5 +88,5 @@ export type BrowserConnector = (browserUrl: string) => Promise<Browser>;
  * binding, thus a replacement never reaches a later file of the same test run.
  */
 export declare function setBrowserConnector(next: BrowserConnector): () => void;
-export declare function getBrowser(browserUrl?: string, injected?: Logger): Promise<Browser>;
-export declare function withPage<T>(cfg: ChromeConfig, fn: (page: Page, context: BrowserContext) => Promise<T>): Promise<T>;
+export declare function getBrowser(browserUrl?: string, injected?: Logger): Promise<ConnectedBrowser>;
+export declare function withPage<T>(cfg: ChromeConfig, fn: (page: LookPage, context: LookContext) => Promise<T>): Promise<T>;

package/dist/lib/console-logger.js

@@ -21,8 +21,8 @@ function prefixed(names, msg) {
 function makeConsoleLogger(names, bindings) {
     const emit = (level) => (msg, fields) => {
         // The one sanctioned console site in the harness — writing to console is
-        // this function's entire contract. `no-console` exempts this file by path
-        // in eslint.config.js rather than by an inline disable here.
+        // this function's entire contract. `no-console` exempts this file and its test
+        // by path in oxlint.config.ts rather than by an inline disable here.
         console[level](prefixed(names, msg), { ...bindings, ...fields });
     };
     return {

package/dist/lib/db-result.d.ts

@@ -18,13 +18,30 @@
  *    workflow-call seam (its `finally` only rolls back and releases).
  *
  * Consumers unwrap per their edge: HTTP routes `.match(...)`; DBOS step bodies
- * `resultStep(runStep)` / `unwrapOrThrow`; tool `execute` bodies `unwrapOrThrow`
- * (a throw becomes an `is_error` tool_result via dispatch).
+ * `unwrapOrThrow`; tool `execute` bodies `unwrapOrThrow` (the tool adapter of
+ * the loop turns a throw into an error tool result).
  */
 import { ResultAsync } from "neverthrow";
-import type { Pool, PoolClient } from "pg";
+import type { Pool, PoolClient, QueryConfig, QueryResultRow } from "pg";
 /** A query/mutation/connection accepted by the data-access layer. */
-type Querier = Pool | PoolClient;
+export type Querier = Pool | PoolClient;
+/**
+ * What a transaction body reads of the client `withTransaction` opens: one
+ * structural `query`. A real `Pool` and `PoolClient` both satisfy it, and so
+ * does a test double that answers `query` alone.
+ */
+export type TransactionQuerier = {
+    query<R extends QueryResultRow = Record<string, unknown>>(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: R[];
+        rowCount: number | null;
+    }>;
+};
+/** What `withTransaction` reads of the pool it borrows from: one `connect`. */
+export type Connectable = {
+    connect(): Promise<TransactionQuerier & {
+        release(): void;
+    }>;
+};
 /**
  * A storage-layer failure. Absence is deliberately NOT modelled: single-row
  * reads return `ok(T | null)` and mutations against a missing row return
@@ -89,5 +106,4 @@ export declare function tryMutation<T>(op: string, fn: () => Promise<T>): Result
  * transaction and releases the connection so a cancelled tx never poisons the
  * pool.
  */
-export declare function withTransaction<T>(pool: Pool, op: string, fn: (client: PoolClient) => ResultAsync<T, DbError>): ResultAsync<T, DbError>;
-export type { Querier };
+export declare function withTransaction<T>(pool: Connectable, op: string, fn: (client: TransactionQuerier) => ResultAsync<T, DbError>): ResultAsync<T, DbError>;

package/dist/lib/db-result.js

@@ -18,9 +18,10 @@
  *    workflow-call seam (its `finally` only rolls back and releases).
  *
  * Consumers unwrap per their edge: HTTP routes `.match(...)`; DBOS step bodies
- * `resultStep(runStep)` / `unwrapOrThrow`; tool `execute` bodies `unwrapOrThrow`
- * (a throw becomes an `is_error` tool_result via dispatch).
+ * `unwrapOrThrow`; tool `execute` bodies `unwrapOrThrow` (the tool adapter of
+ * the loop turns a throw into an error tool result).
  */
+import { z } from "zod";
 import { ResultAsync, err, ok } from "neverthrow";
 const _assertDomainError = true;
 /** pg SQLSTATE classes that mean "connection is gone", mapped to `connection_failed`. */
@@ -41,21 +42,16 @@ const CONSTRAINT_SQLSTATE = {
     "23502": "not_null",
     "23514": "check",
 };
+const SqlstateCauseSchema = z.object({ code: z.string() });
 function sqlstate(cause) {
-    if (cause && typeof cause === "object" && "code" in cause) {
-        const code = cause.code;
-        return typeof code === "string" ? code : undefined;
-    }
-    return undefined;
+    const parsed = SqlstateCauseSchema.safeParse(cause);
+    return parsed.success ? parsed.data.code : undefined;
 }
 /** pg surfaces the tripped constraint's name on `.constraint`. */
+const ConstraintCauseSchema = z.object({ constraint: z.string().min(1) });
 function constraintName(cause) {
-    if (cause && typeof cause === "object" && "constraint" in cause) {
-        const name = cause.constraint;
-        if (typeof name === "string" && name.length > 0)
-            return name;
-    }
-    return "unknown";
+    const parsed = ConstraintCauseSchema.safeParse(cause);
+    return parsed.success ? parsed.data.constraint : "unknown";
 }
 /** A read throw → `connection_failed` for a connection SQLSTATE, else `query_failed`. */
 function readError(op, cause) {