@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/lib/eyes.d.ts

@@ -26,20 +26,20 @@ import { type ChromeConfig } from "./chrome.js";
  * page navigation reads a `file://` URL of the host tree. The caller resolves the root already, thus the
  * scope hands it over and a realization holds no second resolver.
  */
-export interface EyesScope {
+export type EyesScope = {
     readonly analysisId: string;
     readonly workspaceRoot: string;
-}
+};
 /**
  * One acquired browser, and the end of the lease.
  *
  * `browserUrl` is the endpoint that a capture connects to. `release` ends the lease of the caller. The shape
  * binds no duration, thus one look and a longer interactive hold read the same.
  */
-export interface EyesLease {
+export type EyesLease = {
     readonly browserUrl: string;
     release(): Promise<void>;
-}
+};
 /**
  * The eyes seam. One call gives one lease over one scope.
  *

package/dist/lib/eyes.js

@@ -36,7 +36,7 @@ export function createStaticEyes(chrome) {
         throw new Error("static eyes need a browser endpoint, and the chrome config names none");
     }
     const browserUrl = chrome.browserUrl;
-    return async (_scope) => ({
+    return (_scope) => Promise.resolve({
         browserUrl,
         release: async () => {
             // The standing sidecar outlives every look, thus nothing ends here.

package/dist/lib/fs-helpers.js

@@ -5,6 +5,8 @@ import { createHash } from "node:crypto";
 import { constants as fsConstants, createReadStream } from "node:fs";
 import { access, mkdir, open, realpath } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
+import { isAllHex } from "./text.js";
+import { errorOf } from "./thrown.js";
 /**
  * Compute SHA-256 hash of in-memory content.
  * Returns `sha256:<hex>` format.
@@ -34,7 +36,14 @@ export async function computeSha256File(filePath) {
  * an attestation invariant violation, not something to paper over.
  */
 export function hasValidContentHash(hash) {
-    return !!hash && /^[a-z0-9]+:[0-9a-f]+$/i.test(hash);
+    if (!hash)
+        return false;
+    const colon = hash.indexOf(":");
+    if (colon === -1)
+        return false;
+    const algorithm = hash.slice(0, colon).toLowerCase();
+    const isAlgorithmChar = (char) => (char >= "a" && char <= "z") || (char >= "0" && char <= "9");
+    return algorithm.length > 0 && Array.from(algorithm).every(isAlgorithmChar) && colon + 1 < hash.length && isAllHex(hash.slice(colon + 1));
 }
 /**
  * Check whether a file exists (access-based, no stat overhead).
@@ -73,7 +82,10 @@ export async function classifyWithinRoot(confinementRoot, absPath) {
         real = await realpath(absPath);
     }
     catch (cause) {
-        const code = cause.code;
+        // Node's fs rejects with an `ErrnoException`, so the code read covers every real rejection;
+        // a non-Error throw carries no errno code and propagates.
+        const causeError = errorOf(cause);
+        const code = causeError !== undefined && "code" in causeError ? causeError.code : undefined;
         // A path (or symlink target) that does not resolve leaks nothing; let the
         // caller's own not-found/fallback path handle it. Genuine faults (e.g.
         // EACCES traversing a directory) propagate.
@@ -105,10 +117,10 @@ export async function writeFileWithinRoot(workspaceRoot, absPath, data) {
     if (realDir !== realRoot && !realDir.startsWith(realRoot + sep)) {
         throw new Error(`writeFileWithinRoot: parent directory escapes the workspace root via a symlink: ${absPath}`);
     }
-    // `O_NOFOLLOW ?? 0`: the flag is defined on Linux/macOS (the harness host
-    // platforms); the `?? 0` keeps the open valid on a platform that lacks it
-    // rather than NaN-ing the flag mask.
-    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | (fsConstants.O_NOFOLLOW ?? 0);
+    // A platform may lack `O_NOFOLLOW` — absent at runtime even though the
+    // constants type says number. The bitwise OR coerces an absent flag to 0,
+    // so the open stays valid without a nullish guard on the flag.
+    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | fsConstants.O_NOFOLLOW;
     const fh = await open(target, flags, 0o644);
     try {
         await fh.writeFile(data);

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

@@ -64,6 +64,7 @@ export type FsError = {
     readonly path?: string;
     readonly cause: unknown;
 };
+export declare function errnoOf(cause: unknown): string | undefined;
 /** True when the throw is a plain "this path isn't here" — `ENOENT`/`ENOTDIR`. */
 export declare function isAbsent(cause: unknown): boolean;
 /** A one-line, user-facing description of an `FsError` for logs and error bodies. */

package/dist/lib/fs-result.js

@@ -29,6 +29,7 @@
  * (`card-builders`) `.unwrapOr(null)` / `.match` to preserve their "any failure
  * → fall back to a chip" behaviour.
  */
+import { z } from "zod";
 import { ResultAsync, err, ok } from "neverthrow";
 const _assertDomainError = true;
 /** errno codes that mean "the path is absent" — the caller's concern, mapped to
@@ -36,12 +37,10 @@ const _assertDomainError = true;
 const ABSENT_CODES = new Set(["ENOENT", "ENOTDIR"]);
 /** errno codes that mean "permission denied". */
 const PERMISSION_CODES = new Set(["EACCES", "EPERM"]);
-function errnoOf(cause) {
-    if (cause && typeof cause === "object" && "code" in cause) {
-        const code = cause.code;
-        return typeof code === "string" ? code : undefined;
-    }
-    return undefined;
+const ErrnoCauseSchema = z.object({ code: z.string() });
+export function errnoOf(cause) {
+    const parsed = ErrnoCauseSchema.safeParse(cause);
+    return parsed.success ? parsed.data.code : undefined;
 }
 /** True when the throw is a plain "this path isn't here" — `ENOENT`/`ENOTDIR`. */
 export function isAbsent(cause) {

package/dist/lib/hooks.d.ts

@@ -20,16 +20,32 @@
  */
 import { ResultAsync } from "neverthrow";
 import type { Logger } from "./logger.js";
-export interface GateFailure {
+export type GateFailure = {
     readonly reason: string;
     /** True when the host asks the harness to suspend the work in place of a failure. */
     readonly suspend: boolean;
-}
-export interface NoticeFailure {
+};
+/**
+ * The settlement a gate's `ResultAsync` resolves to, read structurally. An embedder whose neverthrow is
+ * a second package copy resolves a settlement that holds the same members without the harness class,
+ * and `passGate` reads it the same way.
+ */
+export type GateSettlement<T> = {
+    isOk(): true;
+    readonly value: T;
+} | {
+    isOk(): false;
+    readonly error: GateFailure;
+};
+/** A gate result that an embedder's own neverthrow copy produced: a thenable over the settlement. */
+export type ForeignGateResult<T> = {
+    then(onfulfilled: (settled: GateSettlement<T>) => unknown): unknown;
+};
+export type NoticeFailure = {
     readonly reason: string;
-}
-export type GateName = "RunAuthorizer.authorize" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
-export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByJti" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record" | "notifyDataProfileSettled";
+};
+export type GateName = "RunAuthorizer.authorize" | "RunAuthorizer.renew" | "RunCharge.open" | "ArtifactRegistry.register" | "resolveRequestHeaders" | "resolveSandboxLabels";
+export type NoticeName = "RunAuthorizer.revoke" | "RunAuthorizer.revokeByMandateId" | "RunAuthorizer.suspend" | "RunCharge.close" | "ArtifactRegistry.sync" | "UsageRecorder.record" | "notifyDataProfileSettled";
 export type GateRefusal = {
     readonly kind: "failed";
     readonly gate: GateName;
@@ -45,5 +61,5 @@ export type GateRefusal = {
  * checkpoint recipes (`runtime/result-serialization.ts`) recognize the class,
  * and a replay reads the same outcome.
  */
-export declare function passGate<T>(gate: GateName, result: ResultAsync<T, GateFailure>): ResultAsync<T, GateRefusal>;
+export declare function passGate<T>(gate: GateName, result: ResultAsync<T, GateFailure> | ForeignGateResult<T>): ResultAsync<T, GateRefusal>;
 export declare function deliverNotice(log: Logger, notice: NoticeName, result: ResultAsync<void, NoticeFailure>): Promise<boolean>;

package/dist/lib/hooks.js

@@ -19,6 +19,17 @@
  * branches on it.
  */
 import { err, ok, ResultAsync } from "neverthrow";
+function settlementOk(settled) {
+    return settled.isOk();
+}
+/** Await the gate result and read it as one settlement, whichever package copy produced it. */
+async function settlementOf(result) {
+    if (result instanceof ResultAsync) {
+        const settled = await result;
+        return settled.isOk() ? { isOk: () => true, value: settled.value } : { isOk: () => false, error: settled.error };
+    }
+    return await result;
+}
 /**
  * The host can build its `Result` with its own copy of neverthrow. The helper
  * gives the outcome again as a `Result` of the copy of the harness. Thus the
@@ -26,9 +37,12 @@ import { err, ok, ResultAsync } from "neverthrow";
  * and a replay reads the same outcome.
  */
 export function passGate(gate, result) {
-    return new ResultAsync(Promise.resolve(result).then((settled) => settled.isOk()
-        ? ok(settled.value)
-        : err({ kind: settled.error.suspend ? "suspended" : "failed", gate, reason: settled.error.reason })));
+    return new ResultAsync((async () => {
+        const settled = await settlementOf(result);
+        if (settlementOk(settled))
+            return ok(settled.value);
+        return err({ kind: settled.error.suspend ? "suspended" : "failed", gate, reason: settled.error.reason });
+    })());
 }
 export async function deliverNotice(log, notice, result) {
     const delivered = await result;

package/dist/lib/host-concurrency.js

@@ -12,6 +12,7 @@
  *   import { withHost } from "../../lib/host-concurrency.js";
  *   const result = await withHost("chembl", () => chembl.getMechanism(id));
  */
+const DEFAULT_HOST_LIMIT = 4;
 const DEFAULT_LIMITS = {
     chembl: 4,
     openfda: 4,
@@ -31,13 +32,13 @@ const DEFAULT_LIMITS = {
     ema: 2,
     pubchem: 4,
     "annotation-llm": 4,
-    default: 4,
+    default: DEFAULT_HOST_LIMIT,
 };
 const budgets = new Map();
 function getBudget(host) {
     let b = budgets.get(host);
     if (!b) {
-        b = { limit: DEFAULT_LIMITS[host] ?? DEFAULT_LIMITS.default, inUse: 0, queue: [] };
+        b = { limit: DEFAULT_LIMITS[host] ?? DEFAULT_HOST_LIMIT, inUse: 0, queue: [] };
         budgets.set(host, b);
     }
     return b;

package/dist/lib/logger.d.ts

@@ -34,7 +34,7 @@ export type LogFields = Record<string, unknown>;
  * this contract to match one of them would model the published surface on a
  * single consumer's choice.
  */
-export interface Logger {
+export type Logger = {
     debug(msg: string, fields?: LogFields): void;
     info(msg: string, fields?: LogFields): void;
     warn(msg: string, fields?: LogFields): void;
@@ -74,7 +74,7 @@ export interface Logger {
      * implementation — a realization with no opinion just references it.
      */
     errorFields(err: unknown): LogFields;
-}
+};
 /**
  * The default `Logger.errorFields`: `err` carries the message, `stack` rides as
  * its own field when there is one.

package/dist/lib/logger.js

@@ -19,6 +19,7 @@
  * when something has gone wrong. `createConsoleLogger` (`./console-logger.ts`)
  * is the one sanctioned console site.
  */
+import { textOf } from "./unknown-text.js";
 /**
  * The default `Logger.errorFields`: `err` carries the message, `stack` rides as
  * its own field when there is one.
@@ -33,5 +34,5 @@ export function defaultErrorFields(err) {
     if (err instanceof Error) {
         return err.stack ? { err: err.message, stack: err.stack } : { err: err.message };
     }
-    return { err: String(err) };
+    return { err: textOf(err) };
 }

package/dist/lib/metrics.d.ts

@@ -33,7 +33,7 @@
  */
 import type { StepExecutionStatus } from "../state/schema.js";
 /** Terminal status of a run, the same as the run ledger. */
-export type RunOutcome = "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds";
+export type RunOutcome = "completed" | "partial" | "failed" | "canceled";
 /** The workflow family a run belongs to. */
 export type RunWorkflow = "analysis" | "data_profile";
 /** Terminal status of an executed step. A blocker is a failure to deliver, so `blocked` maps here to `failed`. */

package/dist/lib/null-proto.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A record with a null prototype, for maps whose keys come from outside the
+ * process (stored snapshots, ledger paths). A key such as `__proto__` stays an
+ * ordinary entry and never reaches a prototype slot, on writes and on reads.
+ */
+export declare function nullProtoRecord<T>(): Record<string, T>;

package/dist/lib/null-proto.js

@@ -0,0 +1,17 @@
+/**
+ * A record with a null prototype, for maps whose keys come from outside the
+ * process (stored snapshots, ledger paths). A key such as `__proto__` stays an
+ * ordinary entry and never reaches a prototype slot, on writes and on reads.
+ */
+export function nullProtoRecord() {
+    const created = Object.create(null);
+    // Object.create(null) always yields an object, so the guard never refuses;
+    // it moves the parser's `any` out of the returned record. The empty record
+    // holds no member, so it is a `Record<string, T>` for every `T`.
+    if (!isRecordOf(created))
+        throw new Error("Object.create(null) did not yield an object");
+    return created;
+}
+function isRecordOf(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/lib/otel-spans.d.ts

@@ -74,7 +74,7 @@ export declare function stableSpan(dbosName: string, name: string, attributes: A
  * writes no client span. Sandbox-server records no spans, and the step span
  * around the call already covers it.
  */
-export declare function untracedFetch(fetchImpl: typeof fetch, url: string, init: RequestInit & {
+export declare function untracedFetch(fetchImpl: typeof fetch, url: string, init: Omit<RequestInit, "headers"> & {
     headers?: Record<string, string>;
 }): Promise<Response>;
 /**

package/dist/lib/otel-spans.js

@@ -96,7 +96,7 @@ export function stableSpan(dbosName, name, attributes) {
     if (span === undefined || !span.isRecording())
         return;
     // The API `Span` has no name accessor; the SDK span the provider hands out does.
-    if (span.name !== dbosName)
+    if (!("name" in span) || span.name !== dbosName)
         return;
     span.updateName(name);
     span.setAttributes(attributes);
@@ -124,6 +124,10 @@ export function untracedFetch(fetchImpl, url, init) {
 export function passThroughTracer(tracer, passesThrough) {
     return new PassThroughTracer(tracer, passesThrough);
 }
+/** Run `fn(span)` under `contextWithSpan`, so the callback's own result type survives the context switch. */
+function runWithSpan(contextWithSpan, span, fn) {
+    return context.with(contextWithSpan, () => fn(span));
+}
 class PassThroughTracer {
     inner;
     passesThrough;
@@ -140,11 +144,11 @@ class PassThroughTracer {
     }
     // The inner tracer cannot take this call: its own `startActiveSpan` calls its own `startSpan`, past the rule.
     startActiveSpan(name, ...rest) {
-        const fn = rest[rest.length - 1];
-        const options = rest.length > 1 ? rest[0] : {};
-        const parentContext = (rest.length > 2 ? rest[1] : undefined) ?? context.active();
+        const parentContext = rest.length === 3 ? (rest[1] ?? context.active()) : context.active();
+        const options = rest.length === 1 ? {} : rest[0];
+        const fn = rest.length === 3 ? rest[2] : rest.length === 2 ? rest[1] : rest[0];
         const span = this.startSpan(name, options, parentContext);
-        return context.with(trace.setSpan(parentContext, span), () => fn(span));
+        return runWithSpan(trace.setSpan(parentContext, span), span, fn);
     }
 }
 /** The name of the span that the enclosing `passThroughSpan` declared. */

package/dist/lib/otel.d.ts

@@ -39,14 +39,14 @@
 import type { Logger } from "./logger.js";
 /** The SDK's own default when neither the host nor the environment says otherwise. */
 export declare const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60000;
-export interface InitOtelOptions {
+export type InitOtelOptions = {
     /** Diagnostics sink; omitted falls back to no-op. */
     readonly logger?: Logger;
     /** `service.name` when `OTEL_SERVICE_NAME` is unset. Default `cortex`. */
     readonly serviceName?: string;
     /** `service.version` — the host's package version. Omitted leaves the attribute unset. */
     readonly serviceVersion?: string;
-}
+};
 /**
  * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
  * stays set for traces. Any other value (including unset) keeps the OTLP
@@ -79,3 +79,5 @@ export declare function shutdownOtel(): Promise<void>;
 export declare function __resetOtelForTest(): Promise<void>;
 /** Test hook: whether `initOtel` registered a metric-exporting MeterProvider. Test-only. */
 export declare function __otelMeterProviderRegisteredForTest(): boolean;
+/** Test hook: the attributes of the resource the registered TracerProvider carries. Test-only. */
+export declare function __otelTracerResourceForTest(): Record<string, unknown> | undefined;

package/dist/lib/otel.js

@@ -38,6 +38,7 @@
  */
 import { context, propagation, metrics, trace } from "@opentelemetry/api";
 import { createNoopLogger } from "./console-logger.js";
+import { trimTrailingOf } from "./text.js";
 import { createHarnessSampler, DbosSpanProcessor, HarnessTracerProvider } from "./otel-spans.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
@@ -50,6 +51,7 @@ import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic
 export const DEFAULT_METRIC_EXPORT_INTERVAL_MS = 60_000;
 let initialized = false;
 let registeredTracerProvider;
+let registeredTracerResource;
 let registeredMeterProvider;
 /**
  * `OTEL_METRICS_EXPORTER=none` turns metric export off while the OTLP endpoint
@@ -108,7 +110,7 @@ export function initOtel(options = {}) {
     {
         const spanProcessors = [];
         if (endpoint) {
-            const base = endpoint.replace(/\/+$/, "");
+            const base = trimTrailingOf(endpoint, "/");
             spanProcessors.push(new DbosSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({ url: `${base}/v1/traces` }))));
         }
         const tracerProvider = new HarnessTracerProvider({
@@ -118,6 +120,7 @@ export function initOtel(options = {}) {
         });
         tracerProvider.register();
         registeredTracerProvider = tracerProvider;
+        registeredTracerResource = resource.attributes;
         // Debug: verify registration actually worked
         const testTracer = trace.getTracer("otel-init-check");
         const testSpan = testTracer.startSpan("init-check");
@@ -140,7 +143,7 @@ export function initOtel(options = {}) {
     // With no MeterProvider registered the API's global no-op provider serves
     // every instrument, so the record sites stay valid when export is off.
     if (endpoint && !metricsExportDisabled()) {
-        const base = endpoint.replace(/\/+$/, "");
+        const base = trimTrailingOf(endpoint, "/");
         const metricExporter = new OTLPMetricExporter({
             url: `${base}/v1/metrics`,
         });
@@ -178,6 +181,7 @@ export async function shutdownOtel() {
 export async function __resetOtelForTest() {
     await shutdownOtel();
     registeredTracerProvider = undefined;
+    registeredTracerResource = undefined;
     registeredMeterProvider = undefined;
     trace.disable();
     metrics.disable();
@@ -189,3 +193,7 @@ export async function __resetOtelForTest() {
 export function __otelMeterProviderRegisteredForTest() {
     return registeredMeterProvider !== undefined;
 }
+/** Test hook: the attributes of the resource the registered TracerProvider carries. Test-only. */
+export function __otelTracerResourceForTest() {
+    return registeredTracerResource;
+}

package/dist/lib/page-capture.d.ts

@@ -30,19 +30,19 @@
  */
 import { type ChromeConfig } from "./chrome.js";
 /** One request that the page could not load, with the reason that the browser gave. */
-export interface FailedRequest {
+export type FailedRequest = {
     url: string;
     reason: string;
-}
+};
 /** One picture of a capture: the base64 bytes, and the document rows that a slice holds. */
-export interface CapturedShot {
+export type CapturedShot = {
     readonly base64: string;
     /** The vertical document range of a slice, in CSS pixels. Absent on a whole-document or window picture. */
     readonly range?: {
         readonly fromY: number;
         readonly toY: number;
     };
-}
+};
 /**
  * What the pictures hold together. `full` is one shot of the whole document. `tiled` is consecutive vertical
  * slices in document order; `capturedPx` is the height the slices cover and `totalPx` is the document height,
@@ -69,7 +69,7 @@ export type CaptureCoverage = {
     readonly kind: "no-block";
 };
 /** The pictures and the faults of one page capture. */
-export interface PageCapture {
+export type PageCapture = {
     /**
      * The pictures in document order: one shot under `full` and `viewport`, the slices under `tiled` and
      * `block`, and none under `no-block`.
@@ -78,7 +78,7 @@ export interface PageCapture {
     coverage: CaptureCoverage;
     consoleErrors: string[];
     failedRequests: FailedRequest[];
-}
+};
 /**
  * The capture seam. It navigates to a page URL, and it gives back the screenshots and the faults. The seam
  * speaks the throw protocol, because the chrome connection does. A test injects a seam that reads no
@@ -86,14 +86,14 @@ export interface PageCapture {
  */
 export type CapturePage = (url: string, options?: CaptureOptions) => Promise<PageCapture>;
 /** The extra settle steps and the target of one capture. A call site that needs none passes nothing. */
-export interface CaptureOptions {
+export type CaptureOptions = {
     /** A CSS selector to wait for after the readiness signal. The wait is best-effort. */
     readonly waitForSelector?: string;
     /** An extra settle time in milliseconds after the readiness signal, for a late paint. */
     readonly waitMs?: number;
     /** The id of the one block to capture. Absent, the capture takes the whole document. */
     readonly blockId?: string;
-}
+};
 /**
  * Capture one page: the screenshots, the console errors, and the failed requests.
  *

package/dist/lib/page-capture.js

@@ -28,6 +28,8 @@
  * The capture speaks the throw protocol, because the chrome connection does. A caller that needs a typed
  * outcome guards the call.
  */
+import { setTimeout as sleep } from "node:timers/promises";
+import { errorOf } from "./thrown.js";
 import { withPage } from "./chrome.js";
 import { PAGE_NAV_TIMEOUT_MS, PAGE_READY_TIMEOUT_MS, THEME_READY_EVENT, THEME_READY_SENTINEL } from "../report-render/page.js";
 import { BLOCK_ID_ATTRIBUTE } from "../report-render/views/block-mark.js";
@@ -69,10 +71,11 @@ const BLOCK_MARGIN_PX = 16;
 function waitForThemeReady(sentinel, event, timeout) {
     return new Promise((resolve) => {
         // The sentinel name arrives as a value, thus no declared property of the global object describes it.
-        if (window[sentinel]) {
+        if (Reflect.get(window, sentinel)) {
             resolve();
             return;
         }
+        // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the browser runs this body as page source, so the node timers module does not exist here; the timer bounds a page that never signals.
         const timer = setTimeout(() => {
             resolve();
         }, timeout);
@@ -98,6 +101,7 @@ async function measureTotalHeight(page) {
     const measured = await page.evaluate(measureScrollHeight).catch(() => undefined);
     return typeof measured === "number" && Number.isFinite(measured) ? measured : 0;
 }
+/** A document area of one capture, in CSS pixels: the columns from `x`, and the rows from `fromY` to `toY`. */
 /**
  * Capture the rows of one area as slices, in document order. Each slice clips {@link TILE_HEIGHT_PX} rows,
  * and the last slice ends at the area or at the budget, whichever comes first.
@@ -181,8 +185,9 @@ async function captureShots(page) {
         catch (refusedViewport) {
             // The two refusals together are the account of a dead look, and the caller reports the second one
             // alone. Thus the first one rides as the cause, and no reader of that report loses half of it.
-            if (refusedViewport instanceof Error && refusedViewport.cause === undefined) {
-                refusedViewport.cause = refused;
+            const refusedViewportError = errorOf(refusedViewport);
+            if (refusedViewportError !== undefined && refusedViewportError.cause === undefined) {
+                refusedViewportError.cause = refused;
             }
             throw refusedViewport;
         }
@@ -229,7 +234,7 @@ export function capturePage(chrome, url, options = {}) {
         }
         if (options.waitMs !== undefined && options.waitMs > 0) {
             const settle = options.waitMs;
-            await new Promise((resolve) => setTimeout(resolve, settle));
+            await sleep(settle);
         }
         // The pictures must show the whole document at the layout that a reader gets. Thus a defect below the
         // fold is visible, and a question about content that never appeared has an answer.

package/dist/lib/parse-json.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** Parse `text` and validate it with `schema`: malformed text throws the parse's `SyntaxError`, a schema failure throws the `ZodError`. */
+export declare function parseJsonAs<T>(text: string, schema: z.ZodType<T>): T;
+/** Parse `text`, validate it with `schema`, and give the zod result. A malformed text still throws the parse's `SyntaxError`; only the schema outcome is a result. */
+export declare function safeParseJsonAs<T>(text: string, schema: z.ZodType<T>): z.ZodSafeParseResult<T>;

package/dist/lib/parse-json.js

@@ -0,0 +1,12 @@
+function parseJsonText(text) {
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the one JSON.parse of the tree: every caller states the schema its boundary assumes.
+    return JSON.parse(text);
+}
+/** Parse `text` and validate it with `schema`: malformed text throws the parse's `SyntaxError`, a schema failure throws the `ZodError`. */
+export function parseJsonAs(text, schema) {
+    return schema.parse(parseJsonText(text));
+}
+/** Parse `text`, validate it with `schema`, and give the zod result. A malformed text still throws the parse's `SyntaxError`; only the schema outcome is a result. */
+export function safeParseJsonAs(text, schema) {
+    return schema.safeParse(parseJsonText(text));
+}

package/dist/lib/present.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A positional or keyed read whose construction guarantees presence, replacing
+ * a non-null assertion with a failure that names the read. A helper serves only
+ * a guaranteed read — a lookup that can miss takes its module's absence path,
+ * because a throw there would turn a handled absence into a crash.
+ */
+export declare function presentFirst<T>(values: readonly T[], what?: string): T;
+export declare function presentAt<T>(values: readonly T[], index: number, what?: string): T;
+export declare function presentLast<T>(values: readonly T[], what?: string): T;
+export declare function presentFind<T>(values: readonly T[], matches: (value: T) => boolean, what?: string): T;
+export declare function presentGet<V>(source: Map<string, V> | Readonly<Record<string, V>>, key: string, what?: string): V;
+export declare function presentGet<K, V>(source: Map<K, V>, key: K, what?: string): V;

package/dist/lib/present.js

@@ -0,0 +1,39 @@
+/**
+ * A positional or keyed read whose construction guarantees presence, replacing
+ * a non-null assertion with a failure that names the read. A helper serves only
+ * a guaranteed read — a lookup that can miss takes its module's absence path,
+ * because a throw there would turn a handled absence into a crash.
+ */
+function absent(what) {
+    return new Error(`${what} is absent`);
+}
+export function presentFirst(values, what) {
+    const first = values[0];
+    if (first === undefined)
+        throw absent(what ?? "the first element");
+    return first;
+}
+export function presentAt(values, index, what) {
+    const value = values[index];
+    if (value === undefined)
+        throw absent(what ?? `the element at index ${index}`);
+    return value;
+}
+export function presentLast(values, what) {
+    const last = values[values.length - 1];
+    if (last === undefined)
+        throw absent(what ?? "the last element");
+    return last;
+}
+export function presentFind(values, matches, what) {
+    const found = values.find(matches);
+    if (found === undefined)
+        throw absent(what ?? "the matching element");
+    return found;
+}
+export function presentGet(source, key, what) {
+    const value = source instanceof Map ? source.get(key) : source[key];
+    if (value === undefined)
+        throw absent(what ?? `the entry for "${key}"`);
+    return value;
+}

package/dist/lib/rate-limit.d.ts

@@ -1,4 +1,4 @@
-export interface RateLimitConfig {
+export type RateLimitConfig = {
     readonly maxConcurrency: number;
     readonly requestsPerSecond: number;
     /**
@@ -8,11 +8,11 @@ export interface RateLimitConfig {
      */
     readonly maxRetries: number;
     readonly maxRetryDelayMs: number;
-}
-export interface RateLimitRuntime {
+};
+export type RateLimitRuntime = {
     readonly now?: () => number;
     readonly sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
-}
+};
 export declare function sleepWithSignal(milliseconds: number, signal?: AbortSignal): Promise<void>;
 export declare class BoundedRateLimiter {
     private readonly config;