@zenera/faker 1.1.23 → 1.1.25

package/README.md

@@ -57,8 +57,8 @@ zen faker cache clear                # throw it away
 
 `zen mock` is the same command under a shorter noun.
 
-A path key with a query string on it — `/x/{id}?action=retry`, which VMware NSX
-and others write when they need two `post`s under one path — is read for what
+A path key with a query string on it — `/x/{id}?action=retry`, which some
+vendors write when they need two `post`s under one path — is read for what
 it means rather than taken verbatim: the path is the part before the `?`, and
 each pair after it becomes a required query value that tells those operations
 apart. Call one without it and the 404 says which queries the path answers to.
@@ -75,11 +75,17 @@ for. `GET /users/12324` answering with somebody else's id validates perfectly
 and is still wrong.
 
 If it fails, the diagnostics go back to the model and it tries again, up to
-`--attempts`. If it passes, the generator is kept in this machine's shared cache
-under `~/.zenera/neo/cache/faker-generator/`, keyed by the operation's shape, and
-every later request is just `podman exec python3 gen.py in.json out.json` - no
-model, no tokens. The store is the machine's, so the same document served from
-another directory costs nothing the second time.
+`--attempts` (five by default). A build that does not come good leaves a
+**report** in `<cache>/builds/` - one markdown file per build, every rejected
+attempt in it with its diagnostics and its whole source, and the `501` that the
+request gets links to it, in the log line and in the body. The next attempt
+overwrites `gen.py`, and a generator that merely hung leaves no traceback, so
+the code is the only evidence there is. If it passes, the generator is kept in
+this machine's shared cache under `~/.zenera/neo/cache/faker-generator/`, keyed
+by the operation's shape, and every later request is just
+`podman exec python3 gen.py in.json out.json` - no model, no tokens. The store
+is the machine's, so the same document served from another directory costs
+nothing the second time.
 
 Generators run in a container with **no network**, on an image baked once with
 `faker`, `exrex`, `jsonschema` and `python-dateutil`.

package/dist/box.d.ts

@@ -1,5 +1,7 @@
 import { type Runner, type Sandbox } from '@zenera/neo';
 export declare const GENERATORS = "generators";
+/** Every faker container's name starts with this; `cache clear` relies on it. */
+export declare const CONTAINER_PREFIX = "zn-faker-";
 export interface BoxOptions {
     /** host directory mounted at /workspace; holds generators/ and io/ */
     root: string;
@@ -8,6 +10,23 @@ export interface BoxOptions {
     timeout?: number;
     engine?: string;
     exec?: Runner;
+    /** the process the container belongs to; defaults to this one */
+    owner?: number;
+}
+/**
+ * The container engine could not run the generator at all. Nothing is known
+ * about the generator from this, so it must never be fed back to a model as a
+ * fault in the code: rewriting a working file cannot bring a container back.
+ */
+export declare class SandboxUnavailable extends Error {
+    readonly hint: string;
+    readonly container: string;
+    readonly stderr?: string;
+    constructor(message: string, opts: {
+        hint: string;
+        container: string;
+        stderr?: string;
+    });
 }
 export interface Outcome {
     ok: boolean;
@@ -24,9 +43,11 @@ export declare class Box {
     constructor(opts: BoxOptions);
     get sandbox(): Sandbox;
     /**
-     * Removes a container of this name left behind by a process that did not
-     * get to clean up. Belt to `persist: false`'s braces: a hard kill never
-     * runs `dispose`, and the leftover is exactly the stale-mount trap above.
+     * Removes this process's container if a previous owner of the pid left one,
+     * and every faker container whose owning process is gone. Belt to
+     * `persist: false`'s braces: a hard kill never runs `dispose`, and the
+     * leftover is exactly the stale-mount trap above. A container whose owner
+     * is alive is another server's, and is never touched.
      */
     fresh(): Promise<void>;
     /** Host path of a generator's source file. */
@@ -36,6 +57,8 @@ export declare class Box {
      * One generator, one input, one output. The io directory is removed
      * afterwards whatever happened — a mock server left alone for a week must
      * not fill a disk with request envelopes.
+     *
+     * Throws `SandboxUnavailable` when the engine, not the generator, failed.
      */
     run(key: string, input: unknown): Promise<Outcome>;
     dispose(): Promise<void>;

package/dist/box.js

@@ -1,8 +1,8 @@
+import { SANDBOX_MOUNT, SandboxError, SandboxPool, pidAlive, runProcess, } from '@zenera/neo';
 import { randomUUID } from 'node:crypto';
 import { mkdirSync, rmSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { SANDBOX_MOUNT, SandboxPool, runProcess } from '@zenera/neo';
 // ---------------------------------------------------------------------------
 // Where generators run
 //
@@ -19,22 +19,51 @@ import { SANDBOX_MOUNT, SandboxPool, runProcess } from '@zenera/neo';
 export const GENERATORS = 'generators';
 const IO = 'io';
 const ENTRY = 'gen.py';
+/** Every faker container's name starts with this; `cache clear` relies on it. */
+export const CONTAINER_PREFIX = 'zn-faker-';
+/** `zn-faker-<pid>-<digest>`; a name without the pid predates per-process containers. */
+const OWNED_BY = /^zn-faker-(\d+)-[0-9a-f]+$/;
+/** Pause before the one retry of an engine failure, long enough for a concurrent rm to finish. */
+const ENGINE_RETRY_MS = 300;
+/**
+ * The container engine could not run the generator at all. Nothing is known
+ * about the generator from this, so it must never be fed back to a model as a
+ * fault in the code: rewriting a working file cannot bring a container back.
+ */
+export class SandboxUnavailable extends Error {
+    hint;
+    container;
+    stderr;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'SandboxUnavailable';
+        this.hint = opts.hint;
+        this.container = opts.container;
+        this.stderr = opts.stderr;
+    }
+}
 export class Box {
     root;
     #pool;
     #timeout;
     #engine;
     #exec;
+    #owner;
     constructor(opts) {
         this.root = opts.root;
         this.#timeout = opts.timeout ?? 30;
         this.#engine = opts.engine ?? 'podman';
         this.#exec = opts.exec ?? runProcess;
+        this.#owner = opts.owner ?? process.pid;
         mkdirSync(join(opts.root, GENERATORS), { recursive: true });
         mkdirSync(join(opts.root, IO), { recursive: true });
         this.#pool = new SandboxPool({
             root: opts.root,
-            key: 'faker',
+            // One container per process. The name is otherwise a pure function
+            // of the configuration, so two servers on the same --cache shared
+            // one container, and each start (`fresh`) or exit (`dispose`)
+            // removed it from under the other: `exited 125, no such container`.
+            key: `faker-${this.#owner}`,
             image: opts.image,
             // The one line that keeps model-written code from calling home.
             network: 'none',
@@ -62,14 +91,21 @@ export class Box {
         return this.#pool.for();
     }
     /**
-     * Removes a container of this name left behind by a process that did not
-     * get to clean up. Belt to `persist: false`'s braces: a hard kill never
-     * runs `dispose`, and the leftover is exactly the stale-mount trap above.
+     * Removes this process's container if a previous owner of the pid left one,
+     * and every faker container whose owning process is gone. Belt to
+     * `persist: false`'s braces: a hard kill never runs `dispose`, and the
+     * leftover is exactly the stale-mount trap above. A container whose owner
+     * is alive is another server's, and is never touched.
      */
     async fresh() {
-        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name], {
-            timeoutMs: 60_000,
-        }).catch(() => undefined);
+        const listed = await this.#exec(this.#engine, ['ps', '--all', '--filter', `name=^${CONTAINER_PREFIX}`, '--format', '{{.Names}}'], { timeoutMs: 60_000 }).catch(() => undefined);
+        const orphans = (listed?.code === 0 ? listed.stdout.split('\n') : [])
+            .map((n) => n.trim())
+            .filter((name) => {
+            const pid = Number(OWNED_BY.exec(name)?.[1]);
+            return Number.isInteger(pid) && pid !== this.#owner && !pidAlive(pid);
+        });
+        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name, ...orphans], { timeoutMs: 60_000 }).catch(() => undefined);
     }
     /** Host path of a generator's source file. */
     sourceOf(key) {
@@ -83,6 +119,8 @@ export class Box {
      * One generator, one input, one output. The io directory is removed
      * afterwards whatever happened — a mock server left alone for a week must
      * not fill a disk with request envelopes.
+     *
+     * Throws `SandboxUnavailable` when the engine, not the generator, failed.
      */
     async run(key, input) {
         const id = randomUUID();
@@ -96,7 +134,17 @@ export class Box {
                 inside(IO, id, 'input.json'),
                 inside(IO, id, 'output.json'),
             ].join(' ');
-            const res = await this.sandbox.exec(script, { timeout: this.#timeout });
+            let res = await this.#exec1(script);
+            if (engineFault(res)) {
+                // `exec` already brought a vanished container back once; a
+                // second fault is usually a concurrent rm still settling.
+                await new Promise((settle) => setTimeout(settle, ENGINE_RETRY_MS));
+                res = await this.#exec1(script);
+            }
+            const fault = engineFault(res);
+            if (fault) {
+                throw this.#unavailable(fault, res.stderr.trim() || res.stdout.trim());
+            }
             const stderr = res.stderr.trim();
             if (res.timed_out) {
                 return {
@@ -150,6 +198,59 @@ export class Box {
     async dispose() {
         await this.#pool.dispose();
     }
+    async #exec1(script) {
+        try {
+            return await this.sandbox.exec(script, { timeout: this.#timeout });
+        }
+        catch (err) {
+            if (err instanceof SandboxError) {
+                throw new SandboxUnavailable(`${this.#engine} could not run the generator: ${err.message}`, {
+                    hint: err.hint ??
+                        `check \`${this.#engine} ps -a --filter name=${CONTAINER_PREFIX}\``,
+                    container: this.sandbox.name,
+                });
+            }
+            throw err;
+        }
+    }
+    #unavailable(fault, stderr) {
+        const name = this.sandbox.name;
+        const first = stderr.split('\n')[0] ?? '';
+        const hint = fault === 'missing-file'
+            ? `the generator is on the host but not inside ${name}, so its bind mount is stale ` +
+                `(the --cache directory was deleted and recreated while the server ran). ` +
+                `Restart \`zen faker serve\`.`
+            : fault === 'no-python'
+                ? `the image has no python3. Rebuild it: \`zen faker serve --rebuild …\`, or pass a working --image.`
+                : `${name} was removed or stopped while this server was using it, twice in a row. ` +
+                    `Usual causes: \`zen sandbox clean\` or \`zen faker cache clear\` run meanwhile, ` +
+                    `a ${this.#engine} machine restart, or an older \`zen faker\` (before per-process ` +
+                    `containers) started on the same --cache. Check \`${this.#engine} ps -a --filter ` +
+                    `name=${CONTAINER_PREFIX}\` and \`${this.#engine} machine list\`; the next request ` +
+                    `recreates the container.`;
+        return new SandboxUnavailable(`${this.#engine} could not run the generator in ${name} — ${first || fault} ` +
+            `(an engine failure, not a fault in the generator; nothing was regenerated)`, { hint, container: name, stderr: stderr || undefined });
+    }
+}
+/**
+ * A failure of the container rather than of the code in it. 125 is podman's
+ * own exit code for "could not exec at all"; the other two are our command
+ * line failing before a line of the generator ran.
+ */
+function engineFault(res) {
+    if (res.timed_out) {
+        return undefined;
+    }
+    if (res.exit_code === 125) {
+        return 'engine';
+    }
+    if (res.exit_code === 2 && /can't open file '\/workspace\/generators\//.test(res.stderr)) {
+        return 'missing-file';
+    }
+    if (res.exit_code === 127 && /python3: (not found|No such file)/.test(res.stderr)) {
+        return 'no-python';
+    }
+    return undefined;
 }
 /** A path inside the container. Every segment is derived here, never given. */
 function inside(...parts) {

package/dist/cache.d.ts

@@ -27,6 +27,8 @@ export interface CacheEvent {
     operation: Operation;
     attempt?: number;
     diagnostics?: readonly string[];
+    /** where the rejected generator was written down, when it was */
+    dump?: string;
 }
 export interface CacheOptions {
     box: Box;
@@ -46,6 +48,8 @@ export interface CacheOptions {
     ephemeral?: boolean;
     /** keep them somewhere other than the shared store */
     cacheDir?: string;
+    /** where rejected generators are written down. Default `<box root>/builds` */
+    dumpDir?: string;
     onStart?: (e: CacheEvent) => void;
     onAttempt?: (e: CacheEvent) => void;
     onReady?: (e: CacheEvent & {

package/dist/cache.js

@@ -1,5 +1,7 @@
 import { Cache as Store } from '@zenera/cli/lib';
+import { join } from 'node:path';
 import { build, BuildFailed, regenerate } from "./generate.js";
+import { saveBuildDump } from "./logger.js";
 import { GENERATOR_RULES_VERSION } from "./spec.js";
 // ---------------------------------------------------------------------------
 // The cache
@@ -24,6 +26,8 @@ const DEFAULT_CONCURRENCY = 4;
 export class Cache {
     #opts;
     #store;
+    #dumpDir;
+    #records = new Map();
     #live = new Map();
     #settled = new Set();
     #slots;
@@ -32,6 +36,7 @@ export class Cache {
     constructor(opts) {
         this.#opts = opts;
         this.#store = new Store(FAKER_KIND, { dir: opts.cacheDir, mode: 0o600 });
+        this.#dumpDir = opts.dumpDir ?? join(opts.box.root, 'builds');
         this.#slots = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
     }
     /**
@@ -87,7 +92,7 @@ export class Cache {
                 fault: ctx.fault,
                 stderr: ctx.stderr,
                 examples: ctx.examples,
-                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+                onAttempt: (attempt, diagnostics, source, limit) => this.#rejected(operation, attempt, diagnostics, source, limit, true),
             });
             if (!ephemeral) {
                 this.#store.put(operation.key, {
@@ -108,11 +113,15 @@ export class Cache {
             const gen = { key: operation.key, source: built.source, cached: false };
             this.#settled.add(operation.key);
             this.#live.set(operation.key, Promise.resolve(gen));
+            await this.#finished(operation);
             return gen;
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            this.#opts.onFail?.({ operation, error });
+            // The box holds the last rejected attempt; the next request must run the old file.
+            await box.write(operation.key, ctx.currentSource).catch(() => undefined);
+            const dump = await this.#finished(operation, error);
+            this.#opts.onFail?.({ operation, error, dump });
             throw error;
         }
         finally {
@@ -136,7 +145,7 @@ export class Cache {
                 box,
                 checks,
                 attempts: this.#opts.attempts,
-                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+                onAttempt: (attempt, diagnostics, source, limit) => this.#rejected(operation, attempt, diagnostics, source, limit, false),
             });
             if (!ephemeral) {
                 this.#store.put(operation.key, {
@@ -154,17 +163,78 @@ export class Cache {
                 });
             }
             this.#opts.onReady?.({ operation, cached: false, attempts: built.attempts });
+            await this.#finished(operation);
             return { key: operation.key, source: built.source, cached: false };
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
-            this.#opts.onFail?.({ operation, error });
+            const dump = await this.#finished(operation, error);
+            this.#opts.onFail?.({ operation, error, dump });
             throw error;
         }
         finally {
             this.#leave();
         }
     }
+    /**
+     * An attempt the judge threw out. The report is rewritten with the file
+     * still in it before the next attempt overwrites `gen.py` — for a timeout
+     * that source is the only evidence there will ever be, since a generator
+     * that hangs leaves no traceback behind.
+     */
+    async #rejected(operation, attempt, diagnostics, source, limit, regeneration) {
+        let record = this.#records.get(operation.key);
+        if (!record || attempt === 1) {
+            record = {
+                operation,
+                started: new Date(),
+                limit,
+                regeneration,
+                attempts: [],
+            };
+            this.#records.set(operation.key, record);
+        }
+        record.attempts.push({ attempt, at: new Date(), diagnostics, source });
+        await this.#report(record);
+        this.#opts.onAttempt?.({ operation, attempt, diagnostics, dump: record.path });
+    }
+    /** A report that cannot be written is not worth failing a build over. */
+    async #report(record, gaveUp = false) {
+        try {
+            record.path = await saveBuildDump(this.#dumpDir, {
+                started: record.started,
+                operationId: record.operation.operationId,
+                method: record.operation.method,
+                path: record.operation.path,
+                key: record.operation.key,
+                limit: record.limit,
+                regeneration: record.regeneration,
+                model: this.#opts.model.id,
+                attempts: record.attempts,
+                gaveUp,
+            });
+        }
+        catch {
+            // no report, then — the narration still says what failed
+        }
+    }
+    /**
+     * The end of a build, either way. A failure is stamped as such and its
+     * report handed to the error, so the request that gets the 501 can say
+     * where to read about it.
+     */
+    async #finished(operation, error) {
+        const record = this.#records.get(operation.key);
+        this.#records.delete(operation.key);
+        if (!record) {
+            return undefined;
+        }
+        if (error instanceof BuildFailed) {
+            await this.#report(record, true);
+            error.dump = record.path;
+        }
+        return record.path;
+    }
     /**
      * A hit is written into the box before it is returned. The container runs
      * files under its mount and nothing else, and the mount is scratch that any

package/dist/command.js

@@ -2,9 +2,10 @@ import { bold, cacheItems, clearCache, CliError, cyan, dim, EXIT, green, json, K
 import { createModel } from '@zenera/neo';
 import { rmSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { GENERATORS } from "./box.js";
+import { CONTAINER_PREFIX, GENERATORS } from "./box.js";
 import { FAKER_KIND } from "./cache.js";
 import { reason } from "./generate.js";
+import { formatDumpPath } from "./logger.js";
 import { listen } from "./server.js";
 import { chooseModel, MODEL_ENV, open, readSettings, SOURCE_LABELS, writeSettings, } from "./setup.js";
 import { called } from "./spec.js";
@@ -60,7 +61,7 @@ export const command = {
             ['  --image <ref>', dim('Skip the baked image and use this one.')],
             ['  --cache <dir>', dim("The container's workspace. Default ~/.zenera/neo/faker.")],
             ['  --seed <n>', dim('Answer the same request the same way every time.')],
-            ['  --attempts <n>', dim('Tries per generator before giving up. Default 3.')],
+            ['  --attempts <n>', dim('Tries per generator before giving up. Default 5.')],
             ['  --concurrency <n>', dim('Generators written at once. Default 4.')],
             ['  --timeout <s>', dim('Seconds one generator may take. Default 30.')],
             ['  --max-body <n>', dim('Largest request body accepted, in bytes.')],
@@ -125,6 +126,7 @@ async function serve(args, ctx) {
         }
         note(dim(`generators: ${setup.root}/${GENERATORS}`));
         note(dim(`request logs: ${requestsDir ?? `${setup.root}/requests`}`));
+        note(dim(`failed builds: ${setup.root}/builds`));
     }
     // The address is the answer; the rest was narration.
     write(`http://${host}:${listener.port}`);
@@ -236,7 +238,7 @@ async function cache(args, ctx) {
         // The container is named after its configuration, so a stale one would
         // otherwise sit there stopped forever with nothing pointing at it.
         // `zn-<key>-<digest>` is the shape, and this one's key is `faker`.
-        const mine = (await ownedContainers()).filter((c) => c.name.startsWith('zn-faker-'));
+        const mine = (await ownedContainers()).filter((c) => c.name.startsWith(CONTAINER_PREFIX));
         if (mine.length > 0) {
             await removeContainers(mine.map((c) => c.name));
         }
@@ -385,7 +387,12 @@ async function start(values, specs, ctx, what) {
                     : note(`  ${green('ready')} ${dim(operation.operationId)}`)
                 : undefined,
             onFail: loud
-                ? ({ operation, error }) => note(`  ${red('gave up')} ${dim(operation.operationId)} ${reason(error)}`)
+                ? ({ operation, error, dump }) => {
+                    note(`  ${red('gave up')} ${dim(operation.operationId)} ${reason(error)}`);
+                    if (dump) {
+                        note(formatDumpPath('report', dump));
+                    }
+                }
                 : undefined,
         },
     });

package/dist/generate.d.ts

@@ -10,13 +10,20 @@ export interface BuildOptions {
     checks: Checks;
     /** how many times the model may be asked before giving up */
     attempts?: number;
-    onAttempt?: (attempt: number, diagnostics: readonly string[]) => void;
+    onAttempt?: (attempt: number, diagnostics: readonly string[], source: string, limit: number) => void | Promise<void>;
     signal?: AbortSignal;
 }
 export interface Built {
     source: string;
     attempts: number;
 }
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export declare const DEFAULT_ATTEMPTS = 5;
 export interface RegenerateOptions extends BuildOptions {
     currentSource: string;
     failingInput: GeneratorInput;
@@ -27,6 +34,8 @@ export interface RegenerateOptions extends BuildOptions {
 export declare class BuildFailed extends Error {
     readonly operation: Operation;
     readonly diagnostics: readonly string[];
+    /** the build report on disk, filled in by whoever was writing one */
+    dump?: string;
     constructor(operation: Operation, diagnostics: readonly string[]);
 }
 /**

package/dist/generate.js

@@ -3,9 +3,18 @@ import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
 import { instruction, regenerationInstruction, retry, SYSTEM, } from "./prompt.js";
 import { called } from "./spec.js";
 import { describeIssues, issues } from "./validate.js";
+/**
+ * Tries per generator. Each one carries the previous file and what was wrong
+ * with it, so the later attempts are the informed ones — a model that has seen
+ * its own traceback usually needs two or three goes at a fiddly schema, and the
+ * whole loop costs nothing once the file is cached.
+ */
+export const DEFAULT_ATTEMPTS = 5;
 export class BuildFailed extends Error {
     operation;
     diagnostics;
+    /** the build report on disk, filled in by whoever was writing one */
+    dump;
     constructor(operation, diagnostics) {
         super(`could not write a generator for ${operation.method.toUpperCase()} ${called(operation)}`);
         this.name = 'BuildFailed';
@@ -38,10 +47,14 @@ export function reason(err) {
         }
         at = e.cause;
     }
+    const hint = err?.hint;
+    if (typeof hint === 'string' && hint) {
+        parts.push(hint);
+    }
     return parts.join(' — ') || String(err);
 }
 export async function build(operation, opts) {
-    const limit = Math.max(1, opts.attempts ?? 3);
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
     const probes = probesFor(operation);
     const response = opts.checks.for(operation).response;
     const messages = [
@@ -66,13 +79,13 @@ export async function build(operation, opts) {
                 return { source, attempts: attempt };
             }
         }
-        opts.onAttempt?.(attempt, last);
+        await opts.onAttempt?.(attempt, last, source, limit);
         messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
     }
     throw new BuildFailed(operation, last);
 }
 export async function regenerate(operation, opts) {
-    const limit = Math.max(1, opts.attempts ?? 3);
+    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
     const exampleInputs = opts.examples?.map((e) => e.input) ?? [];
     const probes = [opts.failingInput, ...exampleInputs, ...probesFor(operation)];
     const response = opts.checks.for(operation).response;
@@ -113,7 +126,7 @@ export async function regenerate(operation, opts) {
                 return { source, attempts: attempt };
             }
         }
-        opts.onAttempt?.(attempt, last);
+        await opts.onAttempt?.(attempt, last, source, limit);
         messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
     }
     throw new BuildFailed(operation, last);

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 import type { GeneratorInput } from './envelope.ts';
-export type ErrorKind = 'CLIENT_ERROR: NOT_FOUND' | 'CLIENT_ERROR: METHOD_NOT_ALLOWED' | 'CLIENT_ERROR: BAD_REQUEST' | 'CLIENT_ERROR: VALIDATION_FAILED' | 'CLIENT_ERROR: PAYLOAD_TOO_LARGE' | 'GENERATOR_FAULT' | 'GENERATOR_TIMEOUT' | 'GENERATOR_SCHEMA_MISMATCH' | 'GENERATOR_BUILD_FAILED' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
+export type ErrorKind = 'CLIENT_ERROR: NOT_FOUND' | 'CLIENT_ERROR: METHOD_NOT_ALLOWED' | 'CLIENT_ERROR: BAD_REQUEST' | 'CLIENT_ERROR: VALIDATION_FAILED' | 'CLIENT_ERROR: PAYLOAD_TOO_LARGE' | 'GENERATOR_FAULT' | 'GENERATOR_TIMEOUT' | 'GENERATOR_SCHEMA_MISMATCH' | 'GENERATOR_BUILD_FAILED' | 'SANDBOX_UNAVAILABLE' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
 export interface RequestDumpData {
     id: string;
     timestamp: Date;
@@ -19,7 +19,11 @@ export interface RequestDumpData {
     responseBody?: unknown;
     errorKind?: ErrorKind;
     errorMessage?: string;
+    /** what to do about it, when the fix is not in the generator */
+    hint?: string;
     stderr?: string;
+    /** the build report, when the answer was "there is no generator" */
+    buildDump?: string;
     cacheStatus?: 'hit' | 'miss' | 'regenerated';
     regenerated?: boolean;
     regenAttempts?: number;
@@ -37,9 +41,32 @@ export declare function colorForErrorKind(kind: ErrorKind): (s: string) => strin
  * Returns the absolute path of the generated markdown file.
  */
 export declare function saveRequestDump(dir: string, data: RequestDumpData): Promise<string>;
+export interface BuildAttempt {
+    attempt: number;
+    at: Date;
+    diagnostics: readonly string[];
+    source: string;
+}
+export interface BuildDumpData {
+    started: Date;
+    operationId?: string;
+    method: string;
+    path: string;
+    /** the operation's cache key, which is also its directory in the box */
+    key: string;
+    limit: number;
+    /** rewriting a generator that already existed rather than writing the first */
+    regeneration?: boolean;
+    model?: string;
+    attempts: readonly BuildAttempt[];
+    /** the attempts ran out — no generator was produced */
+    gaveUp?: boolean;
+}
+export declare function saveBuildDump(dir: string, data: BuildDumpData): Promise<string>;
+export declare function formatDumpPath(label: string, path: string): string;
 export declare function formatLogLine(data: RequestDumpData, dumpPath: string): string;
 export declare function formatRegenLimitHit(urlPath: string, limit: number, operationId?: string): string;
-export declare function formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string): string;
+export declare function formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string, stderr?: string): string;
 export declare function formatRegenerated(urlPath: string, attempt: number, durationMs: number, operationId?: string): string;
 export interface ExampleRequest {
     input: GeneratorInput;

package/dist/logger.js

@@ -44,6 +44,8 @@ export function statusText(status) {
             return 'Not Implemented';
         case 502:
             return 'Bad Gateway';
+        case 503:
+            return 'Service Unavailable';
         case 504:
             return 'Gateway Timeout';
         default:
@@ -102,6 +104,9 @@ export async function saveRequestDump(dir, data) {
     if (data.note) {
         lines.push(`- **Note**: ${data.note}`);
     }
+    if (data.buildDump) {
+        lines.push(`- **Build report**: [${data.buildDump}](file://${data.buildDump})`);
+    }
     lines.push('', '---', '', '## Request Info', '');
     lines.push('### URL & Method', '```http', `${data.method.toUpperCase()} ${data.url}`, '```', '');
     lines.push('### Path Parameters');
@@ -166,6 +171,9 @@ export async function saveRequestDump(dir, data) {
         if (data.errorMessage) {
             lines.push(`### Error Message`, `\`${data.errorMessage}\``, '');
         }
+        if (data.hint) {
+            lines.push(`### What to do`, data.hint, '');
+        }
         if (data.issues && data.issues.length > 0) {
             lines.push('### Validation Issues', '```json', JSON.stringify(data.issues, null, 2), '```', '');
         }
@@ -176,6 +184,38 @@ export async function saveRequestDump(dir, data) {
     await writeFile(fullPath, lines.join('\n'), 'utf8');
     return resolve(fullPath);
 }
+export async function saveBuildDump(dir, data) {
+    mkdirSync(dir, { recursive: true });
+    const safePath = data.path.replace(/[^a-zA-Z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'root';
+    const isoPrefix = data.started.toISOString().replace(/[:.]/g, '-');
+    const what = data.regeneration ? 'regen' : 'build';
+    const fullPath = join(dir, `${isoPrefix}-${what}-${data.method.toUpperCase()}-${safePath}.md`);
+    const outcome = data.gaveUp
+        ? `gave up after ${data.attempts.length} of ${data.limit}`
+        : `attempt ${data.attempts.length} of ${data.limit} rejected`;
+    const lines = [
+        `# ${data.regeneration ? 'Regeneration' : 'Build'}: ` +
+            `${data.method.toUpperCase()} ${data.path}`,
+        '',
+        `- **Operation ID**: ${data.operationId ? `\`${data.operationId}\`` : '_None_'}`,
+        `- **Key**: \`${data.key}\``,
+        `- **Started**: ${data.started.toISOString()}`,
+        `- **Model**: ${data.model ? `\`${data.model}\`` : '_Unknown_'}`,
+        `- **Outcome**: ${outcome}`,
+        '',
+    ];
+    for (const a of data.attempts) {
+        const elapsed = Math.max(0, a.at.getTime() - data.started.getTime());
+        lines.push('---', '', `## Attempt ${a.attempt} of ${data.limit}`, '', `_Rejected ${a.at.toISOString()}, ${elapsed}ms into the build._`, '', '### Why it was rejected', '', ...(a.diagnostics.length > 0
+            ? a.diagnostics.map((d) => (d.trimStart().startsWith('-') ? d : `- ${d}`))
+            : ['_No diagnostics._']), '', '### Generator', '', '```python', a.source, '```', '');
+    }
+    await writeFile(fullPath, lines.join('\n'), 'utf8');
+    return resolve(fullPath);
+}
+export function formatDumpPath(label, path) {
+    return `  ${dim(`↳ ${label}:`)} ${cyan(`file://${resolve(path)}`)}`;
+}
 // ---------------------------------------------------------------------------
 // Log Line Formatter
 // ---------------------------------------------------------------------------
@@ -202,10 +242,16 @@ export function formatLogLine(data, dumpPath) {
         const lastStderr = data.stderr.trim().split('\n').slice(-4).join('\n    ');
         lines.push(`  ${dim('stderr:')} ${red(lastStderr)}`);
     }
+    if (data.hint) {
+        lines.push(`  ${dim('↳ fix:')} ${yellow(data.hint)}`);
+    }
     if (dumpPath) {
         const fileUrl = `file://${resolve(dumpPath)}`;
         lines.push(`  ${dim('↳ dump:')} ${cyan(fileUrl)}`);
     }
+    if (data.buildDump) {
+        lines.push(formatDumpPath('build', data.buildDump));
+    }
     return lines.join('\n');
 }
 // ---------------------------------------------------------------------------
@@ -216,11 +262,13 @@ export function formatRegenLimitHit(urlPath, limit, operationId) {
     const op = operationId ? ` (${operationId})` : '';
     return `${ts} ${red(bold('[REGENERATION_LIMIT_HIT]'))} Maximum regeneration limit (${limit}) reached for URL "${urlPath}"${op}. Halting further regeneration attempts.`;
 }
-export function formatRegenerating(urlPath, attempt, limit, operationId, reason) {
+export function formatRegenerating(urlPath, attempt, limit, operationId, reason, stderr) {
     const ts = dim(`[${formatTimestamp(new Date())}]`);
     const op = operationId ? ` (${operationId})` : '';
     const r = reason ? ` [${reason}]` : '';
-    return `${ts} ${yellow(bold('[REGENERATING]'))} Error in generator for "${urlPath}"${op}${r}. Attempting regeneration (${attempt}/${limit})...`;
+    const head = `${ts} ${yellow(bold('[REGENERATING]'))} Error in generator for "${urlPath}"${op}${r}. Attempting regeneration (${attempt}/${limit})...`;
+    const tail = stderr?.trim().split('\n').slice(-3).join('\n    ');
+    return tail ? `${head}\n  ${dim('stderr:')} ${red(tail)}` : head;
 }
 export function formatRegenerated(urlPath, attempt, durationMs, operationId) {
     const ts = dim(`[${formatTimestamp(new Date())}]`);

package/dist/probe.js

@@ -1,4 +1,4 @@
-import { propertyNames } from "./schema.js";
+import { properties } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Probes
 //
@@ -12,13 +12,25 @@ import { propertyNames } from "./schema.js";
 // schema allows — a generator that hard-codes the first probe's id passes once
 // and fails the second, which is the mistake this catches.
 // ---------------------------------------------------------------------------
+/**
+ * How many items a probe asks a paged operation for.
+ *
+ * Not the schema's maximum. `bounded` below answers an unbounded want with
+ * `maximum - 1`, so a `page_size` declared `maximum: 1000` used to make every
+ * probe ask for 999 fabricated objects — minutes of Faker inside a container
+ * with a 30s budget, reported as "the file took longer than 30s" and blamed on
+ * a generator that was doing exactly what it was told. A page is judged on its
+ * shape, and three rows show it.
+ */
+const PROBE_PAGE_SIZE = 3;
 export function probesFor(operation) {
+    const size = operation.paging?.size;
     return [0, 1].map((variant) => ({
         operationId: operation.operationId,
         method: operation.method,
         path: operation.path,
-        pathParams: values(operation.params, 'path', variant),
-        query: values(operation.params, 'query', variant),
+        pathParams: values(operation.params, 'path', variant, size),
+        query: values(operation.params, 'query', variant, size),
         headers: {},
         body: operation.requestBody
             ? sample(operation.requestBody.schema, variant, 0, operation.requestBody.schema)
@@ -26,7 +38,7 @@ export function probesFor(operation) {
         seed: variant === 0 ? 1 : 2,
     }));
 }
-function values(params, where, variant) {
+function values(params, where, variant, size) {
     const out = {};
     for (const p of params) {
         if (p.in !== where) {
@@ -37,7 +49,10 @@ function values(params, where, variant) {
         if (!p.required && variant === 1) {
             continue;
         }
-        out[p.name] = sample(p.schema, variant, 0, p.schema);
+        out[p.name] =
+            p.name === size
+                ? bounded(p.schema, PROBE_PAGE_SIZE, true)
+                : sample(p.schema, variant, 0, p.schema);
     }
     return out;
 }
@@ -220,10 +235,18 @@ export function echoIssues(input, value, schema) {
     if (!schema) {
         return [];
     }
-    const declared = propertyNames(schema);
+    const declared = new Map();
+    for (const p of properties(schema)) {
+        declared.set(p.name, [...(declared.get(p.name) ?? []), p.schema]);
+    }
     const out = [];
     for (const [name, expected] of Object.entries(input.pathParams)) {
-        if (!declared.has(name) || expected === undefined || expected === null) {
+        const subs = declared.get(name);
+        if (!subs || expected === undefined || expected === null) {
+            continue;
+        }
+        // A value the response may not hold cannot be echoed: the schema check wins.
+        if (!subs.some((s) => admits(s, expected))) {
             continue;
         }
         if (!carries(value, name, expected)) {
@@ -235,6 +258,17 @@ export function echoIssues(input, value, schema) {
     }
     return out;
 }
+function admits(schema, value) {
+    if (typeof schema.pattern !== 'string') {
+        return true;
+    }
+    try {
+        return new RegExp(schema.pattern, 'u').test(String(value));
+    }
+    catch {
+        return true;
+    }
+}
 /** Whether `name` anywhere in the value holds something equal to `expected`. */
 function carries(value, name, expected) {
     const stack = [value];

package/dist/prompt.js

@@ -36,7 +36,9 @@ export const SYSTEM = [
     "   in the response schema, that property must carry the request's value,",
     '   converted to the type the schema declares. `GET /users/{user_id}` called',
     '   with `user_id=12324` answers with `user_id` 12324, not a random one. Do',
-    '   this generically, by looking the names up at run time. Do the same for a',
+    '   this generically, by looking the names up at run time. If the value would',
+    "   break that property's schema (it fails a `pattern`, say), the schema wins:",
+    '   generate a valid value instead, and do not exit non-zero. Do the same for a',
     '   query parameter where it plainly describes the content rather than',
     '   controlling the call. A paging control — a cursor, page, offset or',
     '   page-size parameter (whether in query or request body) — is never content',

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from 'node:http';
-import type { Box } from './box.ts';
+import { type Box } from './box.ts';
 import { type Cache } from './cache.ts';
 import { RegenerationLimiter, RequestHistory } from './logger.ts';
 import { PaginationLimiter } from './paging.ts';

package/dist/server.js

@@ -2,6 +2,7 @@ import { createHash, randomInt, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { join } from 'node:path';
+import { SandboxUnavailable } from "./box.js";
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
 import { formatLogLine, formatRegenerated, formatRegenerating, formatRegenLimitHit, RegenerationLimiter, RequestHistory, saveRequestDump, } from "./logger.js";
@@ -39,7 +40,7 @@ export function build(opts) {
     };
     return createServer((req, res) => {
         handle(req, res, enriched).catch((err) => {
-            const message = err instanceof Error ? err.message : String(err);
+            const message = reason(err);
             send(res, 500, { error: message });
             opts.onRequest?.(`${req.method ?? 'GET'} ${req.url ?? '/'} 500 [SERVER_INTERNAL_ERROR] ${message}`);
         });
@@ -93,7 +94,9 @@ async function handle(req, res, opts) {
             responseBody: meta.responseBody,
             errorKind: meta.errorKind,
             errorMessage: meta.errorMessage,
+            hint: meta.hint,
             stderr: meta.stderr,
+            buildDump: meta.buildDump,
             cacheStatus: meta.cacheStatus,
             regenerated: meta.regenerated,
             regenAttempts: meta.regenAttempts,
@@ -181,6 +184,30 @@ async function handle(req, res, opts) {
     }
     const { operation, pathParams } = match;
     res.setHeader('x-faker-operation', operation.operationId);
+    /** The container could not run anything: say so, and never blame the generator. */
+    const sandboxDown = async (err, extra = {}) => {
+        const bodyObj = {
+            error: err.message,
+            hint: err.hint,
+            container: err.container,
+            stderr: err.stderr,
+        };
+        res.setHeader('retry-after', '1');
+        const end = prepareSend(res, 503, bodyObj);
+        await finish(503, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            ...extra,
+            errorKind: 'SANDBOX_UNAVAILABLE',
+            errorMessage: err.message,
+            hint: err.hint,
+            stderr: err.stderr,
+            responseBody: bodyObj,
+            note: 'container engine failed',
+        });
+        end();
+    };
     let body;
     try {
         body = await readBody(req, opts.maxBody ?? DEFAULT_MAX_BODY);
@@ -239,12 +266,17 @@ async function handle(req, res, opts) {
         generator = await opts.cache.ensure(operation);
     }
     catch (err) {
+        if (err instanceof SandboxUnavailable) {
+            await sandboxDown(err, { requestBody: body });
+            return;
+        }
         const status = err instanceof BuildFailed ? 501 : 500;
         const detail = reason(err);
         const bodyObj = {
             error: `no generator for ${operation.operationId}`,
             detail,
             diagnostics: err instanceof BuildFailed ? err.diagnostics : undefined,
+            report: err instanceof BuildFailed ? err.dump : undefined,
         };
         const end = prepareSend(res, status, bodyObj);
         await finish(status, {
@@ -254,6 +286,7 @@ async function handle(req, res, opts) {
             requestBody: body,
             errorKind: 'GENERATOR_BUILD_FAILED',
             errorMessage: `no generator: ${detail}`,
+            buildDump: err instanceof BuildFailed ? err.dump : undefined,
             responseBody: bodyObj,
             note: `no generator: ${detail}`,
         });
@@ -272,7 +305,17 @@ async function handle(req, res, opts) {
         body,
         seed: seedFor(opts.seed, operation, pathParams, url.searchParams),
     };
-    let outcome = await opts.box.run(operation.key, input);
+    let outcome;
+    try {
+        outcome = await opts.box.run(operation.key, input);
+    }
+    catch (err) {
+        if (err instanceof SandboxUnavailable) {
+            await sandboxDown(err, { requestBody: body, cacheStatus });
+            return;
+        }
+        throw err;
+    }
     const responseValidator = opts.checks.for(operation).response;
     let schemaMismatch = false;
     if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
@@ -320,7 +363,7 @@ async function handle(req, res, opts) {
             return;
         }
         const attempt = opts.limiter.increment(urlKey);
-        opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault));
+        opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault, outcome.stderr));
         const regenStarted = Date.now();
         let currentSource = generator.source;
         if (!currentSource?.trim()) {
@@ -358,6 +401,10 @@ async function handle(req, res, opts) {
             }
         }
         catch (regenErr) {
+            if (regenErr instanceof SandboxUnavailable) {
+                await sandboxDown(regenErr, { requestBody: body, cacheStatus });
+                return;
+            }
             const detail = reason(regenErr);
             const bodyObj = {
                 error: `regeneration failed for ${operation.operationId}: ${detail}`,

package/dist/setup.js

@@ -19,7 +19,7 @@ import { Checks } from "./validate.js";
 // ---------------------------------------------------------------------------
 /**
  * The model each provider gets when none is named — the same picks `zen meta`
- * recommends (`RECOMMENDED` in `packages/cli/src/meta.ts`). Every ref names its
+ * recommends (`RECOMMENDED` in `packages/cli/src/meta/model.ts`). Every ref names its
  * provider: the shorthand reads the first segment as a *provider name*, so a
  * bare `gemini-3.8-flash` would be asked of OpenAI.
  */

package/dist/spec.js

@@ -97,7 +97,7 @@ function join(prefix, template) {
 /** The path as it has to be called — what a person needs to see. */
 export const called = (op) => op.fixed ? `${op.path}?${new URLSearchParams(op.fixed).toString()}` : op.path;
 /**
- * A path template has no query string, but VMware, Oracle and others write one
+ * A path template has no query string, but some vendors write one
  * anyway — `/x/{id}?action=retry` — because they need two `post`s under one
  * path and the object model gives them one. Taken verbatim the key matches
  * nothing, since a request path never contains a `?`. So it is read for what

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/faker",
-    "version": "1.1.23",
+    "version": "1.1.25",
     "description": "Mock HTTP server for swagger/OpenAPI documents, with response bodies generated by a model.",
     "keywords": [
         "openapi",
@@ -45,7 +45,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
-        "@zenera/cli": "^1.1.23",
-        "@zenera/neo": "^1.1.23"
+        "@zenera/cli": "^1.1.25",
+        "@zenera/neo": "^1.1.25"
     }
 }