@qawolf/api-contracts 0.20.0 → 0.22.0

package/dist/v1/runner/journal.d.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+/**
+ * The wire shapes of a runner's journal: what a read asks for and what it
+ * answers with. One definition serves the writer, the server and the client,
+ * so an entry cannot come to mean different things along the way.
+ */
+/** One appended line in one stream's NDJSON file. */
+export type JournalEntry<Payload> = {
+    payload: Payload;
+    /** Wall clock at append, ISO 8601 in UTC. */
+    recordedAt: string;
+    /** Monotonic per stream, starting at 1; the read cursor. */
+    sequence: number;
+};
+/**
+ * zod treats an `unknown` field as an optional key, so without the refinement a
+ * line missing `payload` would parse to an entry whose payload is undefined
+ * under a type promising one.
+ */
+export declare const journalEntrySchema: z.ZodPipe<z.ZodObject<{
+    payload: z.ZodUnknown;
+    recordedAt: z.ZodISODateTime;
+    sequence: z.ZodNumber;
+}, z.core.$strip>, z.ZodTransform<JournalEntry<unknown>, {
+    payload: unknown;
+    recordedAt: string;
+    sequence: number;
+}>>;
+export declare const knownJournalStreams: readonly ["console", "recorder", "run-events", "run-logs", "run-status"];
+export type KnownJournalStream = (typeof knownJournalStreams)[number];
+/**
+ * An open set, so a later change can add a stream without breaking consumers;
+ * the `string & {}` arm keeps the known names as completions. An unwritten
+ * stream reads as empty, never as an error.
+ */
+export type JournalStream = KnownJournalStream | (string & {});
+/**
+ * A stream name doubles as a directory name under the journal root, so it is
+ * bounded in shape and length: outside this, a name could address a path
+ * outside the journal or fail at the filesystem with ENAMETOOLONG.
+ */
+export declare const maxJournalStreamNameLength = 64;
+export declare const journalStreamSchema: z.ZodString;
+/**
+ * A wire type, so the filters are optional fields rather than our usual
+ * `| undefined`: JSON has no undefined, and omission is the only way a client
+ * can not-supply one.
+ *
+ * The filters compose in one order: `runId` restricts, `sinceSequence` cuts
+ * strictly-after, `tail` keeps the newest N of what remains. With neither
+ * `sinceSequence` nor `tail`, the read starts from the oldest available entry.
+ */
+export type ReadJournalRequest = {
+    /** Restrict run-scoped streams (run-events, run-logs, run-status) to one run. */
+    runId?: string;
+    /** Entries strictly after this sequence. Omitted: from the oldest available. */
+    sinceSequence?: number;
+    stream: JournalStream;
+    /** Keep only the newest N of whatever the other filters matched. */
+    tail?: number;
+};
+/** `runId` is compared against every scanned entry, so it is bounded. */
+export declare const readJournalRequestSchema: z.ZodObject<{
+    runId: z.ZodOptional<z.ZodString>;
+    sinceSequence: z.ZodOptional<z.ZodNumber>;
+    stream: z.ZodString;
+    tail: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReadJournalResponse = {
+    /** Exactly what {@link readJournalResponseSchema} parses to, so not readonly. */
+    entries: JournalEntry<unknown>[];
+    /**
+     * True when a `tail` read stopped at its scan budget with older history it
+     * never looked at: page forwards with `sinceSequence`, or narrow the filters.
+     * False means everything matching the request is in `entries`. Never set by
+     * the response's own entry cap, which `nextSequence` already reports.
+     */
+    hasUnsearchedHistory: boolean;
+    /**
+     * The cursor to continue from: the highest sequence this read examined, so a
+     * filtered read that matched nothing still advances.
+     */
+    nextSequence: number;
+    /**
+     * The oldest sequence still on disk, or 0 when the stream holds nothing. A
+     * `sinceSequence` below this means the size cap truncated history away.
+     */
+    oldestAvailableSequence: number;
+};
+export declare const readJournalResponseSchema: z.ZodObject<{
+    entries: z.ZodArray<z.ZodPipe<z.ZodObject<{
+        payload: z.ZodUnknown;
+        recordedAt: z.ZodISODateTime;
+        sequence: z.ZodNumber;
+    }, z.core.$strip>, z.ZodTransform<JournalEntry<unknown>, {
+        payload: unknown;
+        recordedAt: string;
+        sequence: number;
+    }>>>;
+    hasUnsearchedHistory: z.ZodBoolean;
+    nextSequence: z.ZodNumber;
+    oldestAvailableSequence: z.ZodNumber;
+}, z.core.$strip>;
+//# sourceMappingURL=journal.d.ts.map

package/dist/v1/runner/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AAEH,qDAAqD;AACrD,MAAM,MAAM,YAAY,CAAC,OAAO,IAAI;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;GAgB5B,CAAC;AAEJ,eAAO,MAAM,mBAAmB,0EAMtB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,eAAO,MAAM,mBAAmB,aAGE,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,wBAAwB;;;;;iBAKK,CAAC;AAE3C,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;IACjC;;;;;OAKG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;CACjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;iBAKK,CAAC"}

package/dist/v1/runner/journal.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * zod treats an `unknown` field as an optional key, so without the refinement a
+ * line missing `payload` would parse to an entry whose payload is undefined
+ * under a type promising one.
+ */
+export const journalEntrySchema = z
+    .object({
+    payload: z.unknown(),
+    recordedAt: z.iso.datetime(),
+    sequence: z.number().int().positive(),
+})
+    .refine((entry) => "payload" in entry, {
+    error: "A journal entry must carry a payload key.",
+    path: ["payload"],
+})
+    .transform((entry) => ({
+    payload: entry.payload,
+    recordedAt: entry.recordedAt,
+    sequence: entry.sequence,
+}));
+export const knownJournalStreams = [
+    "console",
+    "recorder",
+    "run-events",
+    "run-logs",
+    "run-status",
+];
+/**
+ * A stream name doubles as a directory name under the journal root, so it is
+ * bounded in shape and length: outside this, a name could address a path
+ * outside the journal or fail at the filesystem with ENAMETOOLONG.
+ */
+export const maxJournalStreamNameLength = 64;
+export const journalStreamSchema = z
+    .string()
+    .max(maxJournalStreamNameLength)
+    .regex(/^[a-z][a-z0-9-]{0,63}$/);
+/** `runId` is compared against every scanned entry, so it is bounded. */
+export const readJournalRequestSchema = z.object({
+    runId: z.string().min(1).max(128).optional(),
+    sinceSequence: z.number().int().nonnegative().optional(),
+    stream: journalStreamSchema,
+    tail: z.number().int().positive().optional(),
+});
+export const readJournalResponseSchema = z.object({
+    entries: z.array(journalEntrySchema),
+    hasUnsearchedHistory: z.boolean(),
+    nextSequence: z.number().int().nonnegative(),
+    oldestAvailableSequence: z.number().int().nonnegative(),
+});
+//# sourceMappingURL=journal.js.map

package/dist/v1/runner/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../../src/v1/runner/journal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,IAAI,KAAK,EAAE;IACrC,KAAK,EAAE,2CAA2C;IAClD,IAAI,EAAE,CAAC,SAAS,CAAC;CAClB,CAAC;KACD,SAAS,CACR,CAAC,KAAK,EAAyB,EAAE,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,CAAC,OAAO;IACtB,UAAU,EAAE,KAAK,CAAC,UAAU;IAC5B,QAAQ,EAAE,KAAK,CAAC,QAAQ;CACzB,CAAC,CACH,CAAC;AAEJ,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,SAAS;IACT,UAAU;IACV,YAAY;IACZ,UAAU;IACV,YAAY;CACJ,CAAC;AAWX;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,EAAE;KACR,GAAG,CAAC,0BAA0B,CAAC;KAC/B,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAqBnC,yEAAyE;AACzE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IACxD,MAAM,EAAE,mBAAmB;IAC3B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAyC,CAAC;AAwB3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IACpC,oBAAoB,EAAE,CAAC,CAAC,OAAO,EAAE;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACxD,CAA0C,CAAC"}

package/dist/v1/runner/payloadSize.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * How much file content one request may carry, counted as UTF-8 bytes of every
+ * path and content. A bound on content rather than on the encoded request,
+ * because it is the half a client can apply while collecting — escaping can
+ * inflate the encoding severalfold, which
+ * {@link maxRunnerRequestEncodedByteLength} bounds on the way out.
+ */
+export declare const maxRunFilesByteLength: number;
+/**
+ * The largest request, JSON-encoded, that may be sent to a runner. Checked
+ * against the fully assembled request, so an oversized one is refused with a
+ * reason rather than failing opaquely in transport.
+ */
+export declare const maxRunnerRequestEncodedByteLength: number;
+/** UTF-8 bytes these files would carry. Compare against {@link maxRunFilesByteLength}. */
+export declare function runFilesByteLength(files: RunFiles): number;
+/**
+ * The files of one request, keyed by path: each path shippable, and all of the
+ * contents together inside the content cap. A record rather than an array of
+ * `{ path, content }` pairs: duplicates become unrepresentable, and the CLI can
+ * derive a flag from a record of strings but not from an array of objects.
+ */
+export declare const runFilesSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/** Every file of one request, keyed by its path. */
+export type RunFiles = Record<string, string>;
+//# sourceMappingURL=payloadSize.d.ts.map

package/dist/v1/runner/payloadSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadSize.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,QAAkB,CAAC;AAEjE,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAM1D;AAOD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,uCAgBvB,CAAC;AAEL,oDAAoD;AACpD,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC"}

package/dist/v1/runner/payloadSize.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { isShippableRunFilePath, runFilePathRefusal } from "./files.js";
+/**
+ * How much file content one request may carry, counted as UTF-8 bytes of every
+ * path and content. A bound on content rather than on the encoded request,
+ * because it is the half a client can apply while collecting — escaping can
+ * inflate the encoding severalfold, which
+ * {@link maxRunnerRequestEncodedByteLength} bounds on the way out.
+ */
+export const maxRunFilesByteLength = 4 * 1024 * 1024;
+/**
+ * The largest request, JSON-encoded, that may be sent to a runner. Checked
+ * against the fully assembled request, so an oversized one is refused with a
+ * reason rather than failing opaquely in transport.
+ */
+export const maxRunnerRequestEncodedByteLength = 9 * 1024 * 1024;
+/** UTF-8 bytes these files would carry. Compare against {@link maxRunFilesByteLength}. */
+export function runFilesByteLength(files) {
+    return Object.entries(files).reduce((total, [path, content]) => total + utf8ByteLength(content) + utf8ByteLength(path), 0);
+}
+/** UTF-8 byte counts, so a non-Latin project is not undercounted severalfold. */
+function utf8ByteLength(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/**
+ * The files of one request, keyed by path: each path shippable, and all of the
+ * contents together inside the content cap. A record rather than an array of
+ * `{ path, content }` pairs: duplicates become unrepresentable, and the CLI can
+ * derive a flag from a record of strings but not from an array of objects.
+ */
+export const runFilesSchema = z
+    .record(z.string(), z.string())
+    // As a refinement, not a key schema: a key schema's message reaches the
+    // caller as a bare "invalid key in record".
+    .superRefine((files, refinementContext) => {
+    for (const path of Object.keys(files)) {
+        if (isShippableRunFilePath(path))
+            continue;
+        refinementContext.addIssue({
+            code: "custom",
+            message: runFilePathRefusal,
+            path: [path],
+        });
+    }
+})
+    .refine((files) => runFilesByteLength(files) <= maxRunFilesByteLength, {
+    error: `The files in one request may carry at most ${maxRunFilesByteLength} bytes in total.`,
+});
+//# sourceMappingURL=payloadSize.js.map

package/dist/v1/runner/payloadSize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloadSize.js","sourceRoot":"","sources":["../../../src/v1/runner/payloadSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjE,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,KAAe;IAChD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,CACjC,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CACzB,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,EACxD,CAAC,CACF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC/B,wEAAwE;IACxE,4CAA4C;KAC3C,WAAW,CAAC,CAAC,KAAK,EAAE,iBAAiB,EAAE,EAAE;IACxC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,IAAI,sBAAsB,CAAC,IAAI,CAAC;YAAE,SAAS;QAC3C,iBAAiB,CAAC,QAAQ,CAAC;YACzB,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,kBAAkB;YAC3B,IAAI,EAAE,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,qBAAqB,EAAE;IACrE,KAAK,EAAE,8CAA8C,qBAAqB,kBAAkB;CAC7F,CAAC,CAAC"}

package/dist/v1/runner/readJournal.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export declare const makeReadRunnerJournalContract: () => {
+    readonly description: "Read a window of one of an interactive runner's journal streams — the newest few, everything after a cursor, or everything belonging to one run. This is how a flow run's outcome and output are followed: `run-status` settles it, `run-logs` and `run-events` carry what it produced, and `recorder` carries the browser actions the runner recorded. A read counts as activity, so working through history does not get the runner reaped underneath you. `runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+    readonly input: z.ZodObject<{
+        runId: z.ZodOptional<z.ZodString>;
+        sinceSequence: z.ZodOptional<z.ZodNumber>;
+        tail: z.ZodOptional<z.ZodNumber>;
+        id: z.ZodString;
+        stream: z.ZodString;
+    }, z.core.$strip>;
+    readonly kind: "read";
+    readonly name: "runner.readJournal";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        entries: z.ZodArray<z.ZodPipe<z.ZodObject<{
+            payload: z.ZodUnknown;
+            recordedAt: z.ZodISODateTime;
+            sequence: z.ZodNumber;
+        }, z.core.$strip>, z.ZodTransform<import("./journal.js").JournalEntry<unknown>, {
+            payload: unknown;
+            recordedAt: string;
+            sequence: number;
+        }>>>;
+        hasUnsearchedHistory: z.ZodBoolean;
+        nextSequence: z.ZodNumber;
+        oldestAvailableSequence: z.ZodNumber;
+        outcome: z.ZodLiteral<"read">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"runner-unreachable">;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=readJournal.d.ts.map

package/dist/v1/runner/readJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readJournal.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyBzC,CAAC"}

package/dist/v1/runner/readJournal.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { runnerIdSchema } from "./identity.js";
+import { journalStreamSchema, knownJournalStreams, readJournalRequestSchema, readJournalResponseSchema, } from "./journal.js";
+import { retryableRunnerUnreachableDescription, runnerUnreachableSchema, } from "./unreachable.js";
+export const makeReadRunnerJournalContract = () => {
+    const input = readJournalRequestSchema.extend({
+        id: runnerIdSchema.describe("Id of the runner to read the journal of."),
+        stream: journalStreamSchema.describe(`The stream to read. QA Wolf writes ${knownJournalStreams.join(", ")}; an unwritten stream reads as empty rather than as an error.`),
+    });
+    const output = z.discriminatedUnion("outcome", [
+        readJournalResponseSchema.extend({ outcome: z.literal("read") }),
+        runnerUnreachableSchema,
+    ]);
+    return {
+        description: `Read a window of one of an interactive runner's journal streams — the newest few, everything after a cursor, or everything belonging to one run. This is how a flow run's outcome and output are followed: \`run-status\` settles it, \`run-logs\` and \`run-events\` carry what it produced, and \`recorder\` carries the browser actions the runner recorded. A read counts as activity, so working through history does not get the runner reaped underneath you. ${retryableRunnerUnreachableDescription}`,
+        input,
+        kind: "read",
+        name: "runner.readJournal",
+        output,
+    };
+};
+//# sourceMappingURL=readJournal.js.map

package/dist/v1/runner/readJournal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readJournal.js","sourceRoot":"","sources":["../../../src/v1/runner/readJournal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,qCAAqC,EACrC,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,EAAE;IAChD,MAAM,KAAK,GAAG,wBAAwB,CAAC,MAAM,CAAC;QAC5C,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,0CAA0C,CAAC;QACvE,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAClC,sCAAsC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,+DAA+D,CACpI;KACF,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,yBAAyB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChE,uBAAuB;KACxB,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EAAE,wcAAwc,qCAAqC,EAAE;QAC5f,KAAK;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,oBAAoB;QAC1B,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

package/dist/v1/runner/runFlow.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export declare const makeRunFlowOnRunnerContract: () => {
+    readonly description: "Run a flow on an interactive runner. Answers as soon as the run is accepted, with the id to follow it by — nothing waits for the run to finish. Which browser or device the run needs is read from the flow file's own execution target, so it is not supplied here; when it does not match what the runner is, the call answers `runner-target-mismatch` rather than failing partway through the run. `runner-unreachable` means the answer did not arrive, which is NOT the same as the run not having started: the runner may have accepted it and been too slow to say so, and resubmitting would start a second run that is billed and journalled alongside the first. Read the runner's `run-status` journal stream before resubmitting, and use the newest run id there if one appeared.";
+    readonly input: z.ZodObject<{
+        entryPointPath: z.ZodString;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        files: z.ZodRecord<z.ZodString, z.ZodString>;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    readonly kind: "write";
+    readonly name: "runner.runFlow";
+    readonly output: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        outcome: z.ZodLiteral<"submitted">;
+        runId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"runner-unreachable">;
+    }, z.core.$strip>, z.ZodObject<{
+        outcome: z.ZodLiteral<"runner-target-mismatch">;
+        requiredRunnerName: z.ZodEnum<{
+            node20Basic: "node20Basic";
+            node20WithAndroid: "node20WithAndroid";
+            node20WithIos: "node20WithIos";
+            node20WithPlaywright: "node20WithPlaywright";
+        }>;
+        runnerName: z.ZodEnum<{
+            node20Basic: "node20Basic";
+            node20WithAndroid: "node20WithAndroid";
+            node20WithIos: "node20WithIos";
+            node20WithPlaywright: "node20WithPlaywright";
+        }>;
+    }, z.core.$strip>], "outcome">;
+};
+//# sourceMappingURL=runFlow.d.ts.map

package/dist/v1/runner/runFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runFlow.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAUxB,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DvC,CAAC"}

package/dist/v1/runner/runFlow.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { runEnvironmentSchema } from "./environment.js";
+import { runFilePathSchema, runPackageJsonPath } from "./files.js";
+import { runnerIdSchema, runnerNameSchema } from "./identity.js";
+import { runFilesSchema } from "./payloadSize.js";
+import { runnerUnreachableSchema } from "./unreachable.js";
+export const makeRunFlowOnRunnerContract = () => {
+    const input = z
+        .object({
+        entryPointPath: runFilePathSchema.describe("Path of the flow file to run, as it appears in `files`."),
+        env: runEnvironmentSchema
+            .optional()
+            .describe("Environment variables to make available to the run."),
+        files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
+        id: runnerIdSchema.describe("Id of the runner to run the flow on."),
+    })
+        // Stated here rather than discovered when the runner cannot find a module.
+        .refine((request) => Object.hasOwn(request.files, request.entryPointPath), {
+        error: "The entry point must be one of the files.",
+        path: ["files"],
+    })
+        .refine((request) => Object.hasOwn(request.files, runPackageJsonPath), {
+        error: `The files must include ${runPackageJsonPath}; the run's npm dependencies are read from it.`,
+        path: ["files"],
+    });
+    const output = z.discriminatedUnion("outcome", [
+        z.object({
+            outcome: z.literal("submitted"),
+            runId: z
+                .string()
+                .describe("Id of the run, to follow it by. Read the `run-status` stream of the runner's journal for its outcome, and `run-logs` and `run-events` for its output."),
+        }),
+        runnerUnreachableSchema,
+        z.object({
+            outcome: z.literal("runner-target-mismatch"),
+            requiredRunnerName: runnerNameSchema.describe("The image this flow's execution target needs."),
+            runnerName: runnerNameSchema.describe("The image the runner is actually running."),
+        }),
+    ]);
+    return {
+        description: "Run a flow on an interactive runner. Answers as soon as the run is accepted, with the id to follow it by — nothing waits for the run to finish. Which browser or device the run needs is read from the flow file's own execution target, so it is not supplied here; when it does not match what the runner is, the call answers `runner-target-mismatch` rather than failing partway through the run. `runner-unreachable` means the answer did not arrive, which is NOT the same as the run not having started: the runner may have accepted it and been too slow to say so, and resubmitting would start a second run that is billed and journalled alongside the first. Read the runner's `run-status` journal stream before resubmitting, and use the newest run id there if one appeared.",
+        input,
+        kind: "write",
+        name: "runner.runFlow",
+        output,
+    };
+};
+//# sourceMappingURL=runFlow.js.map

package/dist/v1/runner/runFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runFlow.js","sourceRoot":"","sources":["../../../src/v1/runner/runFlow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,EAAE;IAC9C,MAAM,KAAK,GAAG,CAAC;SACZ,MAAM,CAAC;QACN,cAAc,EAAE,iBAAiB,CAAC,QAAQ,CACxC,yDAAyD,CAC1D;QACD,GAAG,EAAE,oBAAoB;aACtB,QAAQ,EAAE;aACV,QAAQ,CAAC,qDAAqD,CAAC;QAClE,KAAK,EAAE,cAAc,CAAC,QAAQ,CAC5B,uMAAuM,CACxM;QACD,EAAE,EAAE,cAAc,CAAC,QAAQ,CAAC,sCAAsC,CAAC;KACpE,CAAC;QACF,2EAA2E;SAC1E,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE;QACzE,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,CAAC,OAAO,CAAC;KAChB,CAAC;SACD,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,CAAC,EAAE;QACrE,KAAK,EAAE,0BAA0B,kBAAkB,gDAAgD;QACnG,IAAI,EAAE,CAAC,OAAO,CAAC;KAChB,CAAC,CAAC;IAEL,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,SAAS,EAAE;QAC7C,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;YAC/B,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,CACP,uJAAuJ,CACxJ;SACJ,CAAC;QACF,uBAAuB;QACvB,CAAC,CAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC;YAC5C,kBAAkB,EAAE,gBAAgB,CAAC,QAAQ,CAC3C,+CAA+C,CAChD;YACD,UAAU,EAAE,gBAAgB,CAAC,QAAQ,CACnC,2CAA2C,CAC5C;SACF,CAAC;KACH,CAAC,CAAC;IAEH,OAAO;QACL,WAAW,EACT,iwBAAiwB;QACnwB,KAAK;QACL,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,gBAAgB;QACtB,MAAM;KAMP,CAAC;AACJ,CAAC,CAAC"}

package/dist/v1/runner/unreachable.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * The one answer every verb that talks to a live runner can give instead of
+ * doing the work. One condition, because telling pod states apart would commit
+ * a published contract to a taxonomy of transient ones. Carries no advice —
+ * whether a retry is safe differs per verb, and each verb says so itself.
+ */
+export declare const runnerUnreachableSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"runner-unreachable">;
+}, z.core.$strip>;
+/**
+ * For verbs that change nothing when they fail. A verb that may already have
+ * taken effect must not use this — see `runner.runFlow`.
+ */
+export declare const retryableRunnerUnreachableDescription = "`runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+//# sourceMappingURL=unreachable.d.ts.map

package/dist/v1/runner/unreachable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.d.ts","sourceRoot":"","sources":["../../../src/v1/runner/unreachable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;iBAElC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,qCAAqC,oPACiM,CAAC"}

package/dist/v1/runner/unreachable.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * The one answer every verb that talks to a live runner can give instead of
+ * doing the work. One condition, because telling pod states apart would commit
+ * a published contract to a taxonomy of transient ones. Carries no advice —
+ * whether a retry is safe differs per verb, and each verb says so itself.
+ */
+export const runnerUnreachableSchema = z.object({
+    outcome: z.literal("runner-unreachable"),
+});
+/**
+ * For verbs that change nothing when they fail. A verb that may already have
+ * taken effect must not use this — see `runner.runFlow`.
+ */
+export const retryableRunnerUnreachableDescription = "`runner-unreachable` if the runner could not be reached: it may still be starting, it may have terminated after inactivity, or it may be too busy to answer. Nothing was changed, so retrying is safe; if it persists, launch the runner again.";
+//# sourceMappingURL=unreachable.js.map

package/dist/v1/runner/unreachable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unreachable.js","sourceRoot":"","sources":["../../../src/v1/runner/unreachable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;CACzC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAChD,iPAAiP,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/api-contracts",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Versioned contracts for the QA Wolf public API",
   "repository": {
@@ -27,10 +27,10 @@
   },
   "scripts": {
     "build": "rm -rf ./dist && tsc -p tsconfig.build.json",
-    "lint:ci": "npm run lint:non-fixable; NON_FIXABLE_EXIT=$?; npm run lint:fixable && exit $NON_FIXABLE_EXIT",
-    "lint:dev": "npm run lint:fixable",
-    "lint:fixable": "eslint . --fix --quiet && oxfmt --write .",
-    "lint:non-fixable": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
+    "lint:ci": "npm run lint:first-half; FIRST_HALF_EXIT=$?; npm run lint:second-half && exit $FIRST_HALF_EXIT",
+    "lint:dev": "npm run lint:first-half",
+    "lint:first-half": "eslint . --fix --quiet && oxfmt --write .",
+    "lint:second-half": "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*'",
     "prepublishOnly": "npm run build",
     "test": "NODE_OPTIONS=\"--experimental-vm-modules\" NODE_NO_WARNINGS=1 jest",
     "tsc:check": "tsgo --noEmit -p tsconfig.typecheck.json"
@@ -47,6 +47,6 @@
     "zod": "^4.1.11"
   },
   "engines": {
-    "node": ">=22.22.0 <25"
+    "node": ">=20.19.0 <25"
   }
 }