@zenera/gym 1.1.40 → 1.1.42

package/dist/inputs.js

@@ -0,0 +1,132 @@
+import { invalidError } from '@zenera/cli/lib';
+import { isGlob, wildcard } from '@zenera/neo';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, join, resolve, sep } from 'node:path';
+// ---------------------------------------------------------------------------
+// What the user named
+//
+// Three kinds of input, each a list of files, directories or patterns: the API
+// documents (`--schema`, or bare arguments), the story of the world
+// (`--story`), and reference material (`--docs`). Nobody is asked to know how
+// any of them is indexed; that is gym's business.
+//
+// A directory named for documents is walked and only the files that actually
+// declare `swagger:` or `openapi:` are kept, so pointing at a folder of mixed
+// JSON — a project, or an index somebody built — finds the APIs in it. A file
+// named outright is taken at its word.
+// ---------------------------------------------------------------------------
+const SPEC_EXTENSIONS = new Set(['.yaml', '.yml', '.json']);
+const TEXT_EXTENSIONS = new Set(['.md', '.markdown', '.txt', '.text']);
+/** Enough for any API collection; far short of a filesystem. */
+const MAX_FILES = 5000;
+/** `swagger: "2.0"` or `"openapi": "3.1.0"`, at the top of a line. */
+const DECLARES = /^\s*["']?(swagger|openapi)["']?\s*:/m;
+/**
+ * Every API document the arguments name, absolute, de-duplicated, in the order
+ * named (and sorted within a directory or a pattern, so a start is repeatable).
+ */
+export async function expandSchemas(args, cwd) {
+    const out = [];
+    const seen = new Set();
+    const add = (file) => {
+        if (!seen.has(file)) {
+            seen.add(file);
+            out.push(file);
+        }
+    };
+    for (const arg of args) {
+        const path = resolve(cwd, arg);
+        if (isGlob(arg)) {
+            const matched = await specsIn(await matching(path));
+            if (matched.length === 0) {
+                throw invalidError(`no API document matches ${arg}`, globHint(arg));
+            }
+            matched.forEach(add);
+            continue;
+        }
+        const info = await stat(path).catch(() => undefined);
+        if (!info) {
+            throw invalidError(`no such file or directory: ${arg}`);
+        }
+        if (info.isDirectory()) {
+            const found = await specsIn(await walk(path, SPEC_EXTENSIONS));
+            if (found.length === 0) {
+                throw invalidError(`${arg} holds no API document`, 'a document is a .yaml, .yml or .json file that declares `swagger:` or `openapi:`');
+            }
+            found.forEach(add);
+            continue;
+        }
+        if (TEXT_EXTENSIONS.has(extname(path).toLowerCase())) {
+            throw invalidError(`${arg} is not an API document`, 'pass the story of the world with --story, and reference material with --docs');
+        }
+        add(path);
+    }
+    return out;
+}
+/**
+ * Checks story and docs arguments before anything reads them. They are read by
+ * `@zenera/rag`, which takes a named file at its word — so an API document
+ * passed here by mistake would quietly become a very long story.
+ */
+export async function checkTexts(args, cwd, flag) {
+    for (const arg of args) {
+        if (isGlob(arg)) {
+            continue;
+        }
+        const path = resolve(cwd, arg);
+        const info = await stat(path).catch(() => undefined);
+        if (!info) {
+            throw invalidError(`no such file or directory: ${arg}`, `named by ${flag}`);
+        }
+        if (info.isFile() && SPEC_EXTENSIONS.has(extname(path).toLowerCase())) {
+            throw invalidError(`${arg} looks like an API document, not ${flag === '--story' ? 'a story' : 'reference material'}`, 'pass API documents with --schema, or as bare arguments');
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+/** The files that declare themselves OpenAPI or Swagger; the rest are not ours. */
+async function specsIn(files) {
+    const out = [];
+    for (const file of files) {
+        if (!SPEC_EXTENSIONS.has(extname(file).toLowerCase())) {
+            continue;
+        }
+        const text = await readFile(file, 'utf8').catch(() => '');
+        if (DECLARES.test(text)) {
+            out.push(file);
+        }
+    }
+    return out;
+}
+async function walk(root, extensions) {
+    const out = [];
+    const queue = [root];
+    while (queue.length > 0 && out.length < MAX_FILES) {
+        const dir = queue.shift();
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') {
+                continue;
+            }
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(path);
+            }
+            else if (extensions.has(extname(entry.name).toLowerCase())) {
+                out.push(path);
+            }
+        }
+    }
+    return out.sort();
+}
+/** Files under the deepest directory a pattern names outright, that match it. */
+async function matching(pattern) {
+    const parts = pattern.split(sep);
+    const at = parts.findIndex((part) => isGlob(part));
+    const anchor = (at === -1 ? parts : parts.slice(0, at)).join(sep) || sep;
+    const root = isAbsolute(anchor) ? anchor : dirname(pattern);
+    const match = wildcard(pattern, { caseSensitive: true });
+    return (await walk(root, SPEC_EXTENSIONS)).filter((file) => match(file));
+}
+const globHint = (arg) => `quote the pattern so gym expands it, e.g. --schema '${arg}'`;
+//# sourceMappingURL=inputs.js.map

package/dist/knowledge.d.ts

@@ -0,0 +1,50 @@
+import { type AnyTool, type Embedder } from '@zenera/neo';
+export interface KnowledgeOptions {
+    /** files, directories or patterns */
+    story: readonly string[];
+    docs: readonly string[];
+    cwd: string;
+    /** gym's workspace; indexes go under `<root>/indexes` */
+    root: string;
+    /** the model that embeds the docs, or none for full-text search only */
+    embedding?: {
+        ref: string;
+        embedder: Embedder;
+    };
+    onWarn?: (message: string) => void;
+    onProgress?: (phase: 'reading' | 'embedding', done: number, total: number) => void;
+}
+export type SearchMode = 'hybrid' | 'text';
+export interface DocsSummary {
+    files: number;
+    chunks: number;
+    search: SearchMode;
+    /** the embedding model, when search is hybrid */
+    embedding?: string;
+    /** whether the index was there already */
+    reused: boolean;
+}
+export interface Knowledge {
+    /** what the world agent is told about the world, whole */
+    readonly story: string;
+    /** a function of the story's content; '' when there is none */
+    readonly storyDigest: string;
+    readonly storyFiles: number;
+    readonly docs?: DocsSummary;
+    /** search, list, grep and read over the docs; none without docs */
+    readonly tools: AnyTool[];
+    /** the passages that best answer a question, quoted; '' when nothing does */
+    recall(query: string, limit?: number): Promise<string>;
+    close(): void;
+}
+/** No story: agents invent a plausible world, and are told so. */
+export declare const NO_STORY: string;
+export declare function openKnowledge(opts: KnowledgeOptions): Promise<Knowledge>;
+export declare function indexDir(root: string, content: string, ref: string | undefined): string;
+/**
+ * The store wants a vector per chunk, so a model-free index gets one: hashed
+ * words, which nothing searches. Cheap, deterministic, and shaped well enough
+ * for the store to build its vector index on a large corpus.
+ */
+export declare const TEXT_ONLY: Embedder;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/knowledge.js

@@ -0,0 +1,199 @@
+import { embeddingResponse } from '@zenera/neo';
+import { docs } from '@zenera/rag';
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { digest } from "./store.js";
+// ---------------------------------------------------------------------------
+// What the agents know about the world
+//
+// Two inputs, read two ways. The STORY is the state of this world — who is
+// who, what is happening, what has not happened yet — and it is authoritative,
+// so it is quoted whole in every world-agent prompt. The DOCS are reference
+// material — a knowledge base, runbooks, an admin guide — read when needed,
+// through search.
+//
+// The docs are indexed here, before the server listens, into a directory gym
+// owns and nobody is told about: keyed by what the documents say and by which
+// model embeds them, so a restart is a cache hit and an edit pays only for the
+// chunks that changed (`@zenera/rag` keeps the vectors). With no embedding
+// model the index is still built, for full-text search; the vectors it carries
+// then are hashed words, there only because the store wants a column.
+// ---------------------------------------------------------------------------
+/** Past this the story is still quoted whole, but it is probably reference material. */
+const STORY_WARN_BYTES = 50_000;
+/** No story: agents invent a plausible world, and are told so. */
+export const NO_STORY = 'There is no story for this world. Invent plausible, internally consistent data: a ' +
+    'small cast of people with stable names and email addresses, and content that reads ' +
+    'like real use of the API. Reuse what is already in the world before inventing anything new.';
+export async function openKnowledge(opts) {
+    const story = opts.story.length > 0 ? await readStory(opts) : undefined;
+    const index = opts.docs.length > 0 ? await openDocs(opts) : undefined;
+    const search = index?.tools.find((t) => t.name === 'search_docs');
+    return {
+        story: story?.text ?? NO_STORY,
+        storyDigest: story?.digest ?? '',
+        storyFiles: story?.files ?? 0,
+        docs: index?.summary,
+        tools: index?.tools ?? [],
+        async recall(query, limit = 4) {
+            if (!search || !query.trim()) {
+                return '';
+            }
+            try {
+                const found = (await search.execute({ query, limit, max_lines: 120 }, {}));
+                return found.passages ?? '';
+            }
+            catch {
+                // Recall is a head start, not a dependency: the agent can still search.
+                return '';
+            }
+        },
+        close: () => index?.close(),
+    };
+}
+// ---------------------------------------------------------------------------
+// The story
+// ---------------------------------------------------------------------------
+async function readStory(opts) {
+    const corpus = await docs.loadDocuments(opts.story, opts.cwd);
+    const bytes = corpus.docs.reduce((n, d) => n + d.bytes, 0);
+    if (bytes > STORY_WARN_BYTES) {
+        opts.onWarn?.(`the story is ${Math.round(bytes / 1000)} KB and is quoted whole in every prompt — ` +
+            'reference material belongs in --docs, where it is searched instead');
+    }
+    return {
+        text: [
+            'THE STORY OF THIS WORLD. Everything the API returns must agree with it.',
+            '',
+            ...corpus.docs.map((d) => `=== ${d.name} ===\n${d.text.trim()}`),
+        ].join('\n'),
+        digest: digest(JSON.stringify(corpus.docs.map((d) => [d.name, d.sha256]))),
+        files: corpus.docs.length,
+    };
+}
+async function openDocs(opts) {
+    // Read first to learn what the index would be called. The parse cache makes
+    // the second read, inside the build, free.
+    const corpus = await docs.loadDocuments(opts.docs, opts.cwd, {
+        onProgress: (done, total) => opts.onProgress?.('reading', done, total),
+    });
+    const content = digest(JSON.stringify(corpus.docs.map((d) => [d.name, d.sha256])));
+    let mode = opts.embedding ? 'hybrid' : 'text';
+    let dir = indexDir(opts.root, content, opts.embedding?.ref);
+    let reused = existsSync(dir);
+    if (!reused) {
+        try {
+            await build(opts, dir, opts.embedding);
+        }
+        catch (err) {
+            if (!opts.embedding) {
+                throw err;
+            }
+            // The docs are still worth searching by their wording.
+            opts.onWarn?.(`could not embed the docs with ${opts.embedding.ref} ` +
+                `(${err instanceof Error ? err.message.split('\n')[0] : String(err)}) — ` +
+                'searching them by wording only');
+            mode = 'text';
+            dir = indexDir(opts.root, content, undefined);
+            reused = existsSync(dir);
+            if (!reused) {
+                await build(opts, dir, undefined);
+            }
+        }
+    }
+    const index = await docs.DocsIndex.open(dir, mode === 'hybrid' ? opts.embedding.embedder : undefined);
+    const tools = docs.docsTools(index);
+    return {
+        summary: {
+            files: index.manifest.sources.length,
+            chunks: index.manifest.counts.chunks,
+            search: mode,
+            embedding: mode === 'hybrid' ? opts.embedding.ref : undefined,
+            reused,
+        },
+        tools: mode === 'hybrid' ? tools : tools.map(wordingOnly),
+        close: () => index.close(),
+    };
+}
+/**
+ * Built beside where it belongs and renamed into place, so a half-built index
+ * is never opened, and a second process building the same one at the same
+ * moment loses the rename instead of the index.
+ */
+async function build(opts, dir, embedding) {
+    mkdirSync(join(dir, '..'), { recursive: true });
+    const scratch = `${dir}.tmp-${randomUUID().slice(0, 8)}`;
+    try {
+        await docs.buildIndex({
+            files: opts.docs,
+            cwd: opts.cwd,
+            out: scratch,
+            embedder: embedding?.embedder ?? TEXT_ONLY,
+            embeddingRef: embedding?.ref ?? TEXT_ONLY.id,
+            indexer: '@zenera/gym',
+            onReading: (done, total) => opts.onProgress?.('reading', done, total),
+            onProgress: (done, total) => opts.onProgress?.('embedding', done, total),
+        });
+        try {
+            renameSync(scratch, dir);
+        }
+        catch {
+            if (!existsSync(dir)) {
+                throw new Error(`could not move the docs index into ${dir}`);
+            }
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}
+export function indexDir(root, content, ref) {
+    const model = ref ? ref.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-|-$/g, '') : 'text';
+    return join(root, 'indexes', `docs-${content}-${model}`);
+}
+/**
+ * `search_docs` with the vector half taken away. A question is asked of the
+ * full-text index as it stands; a vector wording becomes a text one.
+ */
+function wordingOnly(tool) {
+    if (tool.name !== 'search_docs') {
+        return tool;
+    }
+    return {
+        ...tool,
+        description: `${tool.description} Matches wording only: there is no embedding model, so use the words the documents would use.`,
+        execute: (raw, tc) => {
+            const { vector_query: vector, mode: _mode, ...args } = raw;
+            const text = args.text_query ?? (args.query ? undefined : vector);
+            return tool.execute(text !== undefined
+                ? { ...args, query: undefined, text_query: text }
+                : { ...args, mode: 'text' }, tc);
+        },
+    };
+}
+/**
+ * The store wants a vector per chunk, so a model-free index gets one: hashed
+ * words, which nothing searches. Cheap, deterministic, and shaped well enough
+ * for the store to build its vector index on a large corpus.
+ */
+export const TEXT_ONLY = {
+    id: 'gym-text-only',
+    embed: (req) => Promise.resolve(embeddingResponse(req.input.map(hashed), req)),
+};
+const DIMENSIONS = 32;
+function hashed(text) {
+    const v = new Array(DIMENSIONS).fill(0);
+    for (const word of text.toLowerCase().match(/[a-z0-9]+/g) ?? []) {
+        let h = 2166136261;
+        for (let i = 0; i < word.length; i++) {
+            h = Math.imul(h ^ word.charCodeAt(i), 16777619) >>> 0;
+        }
+        v[h % DIMENSIONS] += h & 0x100 ? 1 : -1;
+    }
+    if (!v.some((x) => x !== 0)) {
+        v[0] = 1;
+    }
+    return v;
+}
+//# sourceMappingURL=knowledge.js.map

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' | 'SANDBOX_UNAVAILABLE' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
+import type { HandlerRequest } from './runtime.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' | 'HANDLER_FAULT' | 'HANDLER_TIMEOUT' | 'HANDLER_SCHEMA_MISMATCH' | 'HANDLER_BUILD_FAILED' | 'WORKER_UNAVAILABLE' | 'WORLD_AGENT_FAILED' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
 export interface RequestDumpData {
     id: string;
     timestamp: Date;
@@ -19,10 +19,10 @@ export interface RequestDumpData {
     responseBody?: unknown;
     errorKind?: ErrorKind;
     errorMessage?: string;
-    /** what to do about it, when the fix is not in the generator */
+    /** what to do about it, when the fix is not in the handler */
     hint?: string;
     stderr?: string;
-    /** the build report, when the answer was "there is no generator" */
+    /** the build report, when the answer was "there is no handler" */
     buildDump?: string;
     cacheStatus?: 'hit' | 'miss' | 'regenerated';
     regenerated?: boolean;
@@ -55,12 +55,14 @@ export interface BuildDumpData {
     /** 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 */
+    /** rewriting a handler that already existed rather than writing the first */
     regeneration?: boolean;
     model?: string;
     attempts: readonly BuildAttempt[];
-    /** the attempts ran out — no generator was produced */
+    /** the attempts ran out — no handler was produced */
     gaveUp?: boolean;
+    /** the agent's HTML run report */
+    report?: string;
 }
 export declare function saveBuildDump(dir: string, data: BuildDumpData): Promise<string>;
 export declare function formatDumpPath(label: string, path: string): string;
@@ -69,13 +71,13 @@ export declare function formatRegenLimitHit(urlPath: string, limit: number, oper
 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;
+    input: HandlerRequest;
     output?: unknown;
 }
 export declare class RequestHistory {
     #private;
     constructor(maxExamples?: number);
-    recordSuccess(operationKey: string, input: GeneratorInput, output: unknown): void;
+    recordSuccess(operationKey: string, input: HandlerRequest, output: unknown): void;
     getSuccessful(operationKey: string, count?: number): ExampleRequest[];
 }
 export declare class RegenerationLimiter {

package/dist/logger.js

@@ -202,13 +202,14 @@ export async function saveBuildDump(dir, data) {
         `- **Started**: ${data.started.toISOString()}`,
         `- **Model**: ${data.model ? `\`${data.model}\`` : '_Unknown_'}`,
         `- **Outcome**: ${outcome}`,
+        ...(data.report ? [`- **Agent run**: [${data.report}](file://${data.report})`] : []),
         '',
     ];
     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, '```', '');
+            : ['_No diagnostics._']), '', '### Handler', '', '```ts', a.source, '```', '');
     }
     await writeFile(fullPath, lines.join('\n'), 'utf8');
     return resolve(fullPath);
@@ -266,14 +267,14 @@ export function formatRegenerating(urlPath, attempt, limit, operationId, reason,
     const ts = dim(`[${formatTimestamp(new Date())}]`);
     const op = operationId ? ` (${operationId})` : '';
     const r = reason ? ` [${reason}]` : '';
-    const head = `${ts} ${yellow(bold('[REGENERATING]'))} Error in generator for "${urlPath}"${op}${r}. Attempting regeneration (${attempt}/${limit})...`;
+    const head = `${ts} ${yellow(bold('[REGENERATING]'))} Error in handler 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())}]`);
     const op = operationId ? ` (${operationId})` : '';
-    return `${ts} ${green(bold('[REGENERATED]'))} Successfully regenerated generator for "${urlPath}"${op} in attempt ${attempt} (${durationMs}ms).`;
+    return `${ts} ${green(bold('[REGENERATED]'))} Successfully regenerated handler for "${urlPath}"${op} in attempt ${attempt} (${durationMs}ms).`;
 }
 export class RequestHistory {
     #successful = new Map();

package/dist/paging.d.ts

@@ -41,10 +41,10 @@ export declare function pagingSeen(params: readonly ParamSpec[], schema: Schema
 /** The token a body offers for the next page, or nothing when it offers none. */
 export declare function tokenOf(value: unknown, paging: Paging): string | undefined;
 /**
- * A last line of defence, for the generator that is already on disk: a body
+ * A last line of defence, for the handler that is already on disk: a body
  * offering the very token it was given is cut back to "no more pages".
  *
- * Deliberately timid. Nothing re-validates a generator's output on the way to
+ * Deliberately timid. Nothing re-validates a handler's output on the way to
  * the client, so writing `null` into a required, non-nullable property would
  * trade a client that hangs for a mock that lies — and a hang is at least
  * obvious. Where the schema leaves no room, this changes nothing and says so.

package/dist/paging.js

@@ -174,10 +174,10 @@ export function tokenOf(value, paging) {
     return typeof token === 'object' ? JSON.stringify(token) : String(token);
 }
 /**
- * A last line of defence, for the generator that is already on disk: a body
+ * A last line of defence, for the handler that is already on disk: a body
  * offering the very token it was given is cut back to "no more pages".
  *
- * Deliberately timid. Nothing re-validates a generator's output on the way to
+ * Deliberately timid. Nothing re-validates a handler's output on the way to
  * the client, so writing `null` into a required, non-nullable property would
  * trade a client that hangs for a mock that lies — and a hang is at least
  * obvious. Where the schema leaves no room, this changes nothing and says so.

package/dist/probe.d.ts

@@ -1,12 +1,12 @@
-import type { GeneratorInput } from './envelope.ts';
+import type { HandlerRequest } from './runtime.ts';
 import type { Paging } from './paging.ts';
 import { type Schema } from './schema.ts';
 import type { Operation } from './spec.ts';
 import type { Issue } from './validate.ts';
-export declare function probesFor(operation: Operation): GeneratorInput[];
+export declare function probesFor(operation: Operation): HandlerRequest[];
 /** The first page: an ordinary probe with the paging control taken back off. */
-export declare function walkStart(operation: Operation, paging: Paging): GeneratorInput;
+export declare function walkStart(operation: Operation, paging: Paging): HandlerRequest;
 /** The same request again, asking for whatever the last answer pointed at. */
-export declare function nextPage(previous: GeneratorInput, paging: Paging, token: string): GeneratorInput;
-export declare function echoIssues(input: GeneratorInput, value: unknown, schema: Schema | undefined): Issue[];
+export declare function nextPage(previous: HandlerRequest, paging: Paging, token: string): HandlerRequest;
+export declare function echoIssues(input: HandlerRequest, value: unknown, schema: Schema | undefined): Issue[];
 //# sourceMappingURL=probe.d.ts.map

package/dist/probe.js

@@ -2,14 +2,14 @@ import { properties } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Probes
 //
-// A generator is judged before it is trusted, and it is judged on inputs made
+// A handler is judged before it is trusted, and it is judged on inputs made
 // up here rather than on traffic. That is not only about cost: a probe built
 // from a request body would put whatever a caller sent into the next prompt,
 // and a mock server is exactly the kind of thing people point at with real
 // payloads by accident.
 //
 // Two probes, deliberately. One ordinary, one at the edges of whatever the
-// schema allows — a generator that hard-codes the first probe's id passes once
+// schema allows — a handler that hard-codes the first probe's id passes once
 // and fails the second, which is the mistake this catches.
 // ---------------------------------------------------------------------------
 /**
@@ -17,9 +17,8 @@ import { properties } from "./schema.js";
  *
  * 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
+ * probe ask for 999 fabricated objects, and a handler that was doing exactly
+ * what it was told was blamed for being slow. A page is judged on its
  * shape, and three rows show it.
  */
 const PROBE_PAGE_SIZE = 3;
@@ -39,28 +38,29 @@ export function probesFor(operation) {
     }));
 }
 function values(params, where, variant, size) {
+    // Text, as on the wire: a handler sees what a real request would give it.
     const out = {};
     for (const p of params) {
         if (p.in !== where) {
             continue;
         }
         // An optional query parameter is present in one probe and absent in the
-        // other, so a generator cannot assume either.
+        // other, so a handler cannot assume either.
         if (!p.required && variant === 1) {
             continue;
         }
-        out[p.name] =
-            p.name === size
-                ? bounded(p.schema, PROBE_PAGE_SIZE, true)
-                : sample(p.schema, variant, 0, p.schema);
+        const value = p.name === size
+            ? bounded(p.schema, PROBE_PAGE_SIZE, true)
+            : sample(p.schema, variant, 0, p.schema);
+        out[p.name] = Array.isArray(value) ? value.join(',') : String(value);
     }
     return out;
 }
 const NAMES = ['ada', 'grace', 'linus'];
 /**
  * A value the schema would accept. Not a faker — that job belongs to the
- * generator; this only has to be *valid*, so that a probe failure is the
- * generator's fault and never the probe's.
+ * handler; this only has to be *valid*, so that a probe failure is the
+ * handler's fault and never the probe's.
  */
 function sample(schema, variant, depth, root) {
     if (depth > 4) {
@@ -175,7 +175,7 @@ function text(schema, variant) {
             break;
     }
     // A `pattern` cannot be satisfied by guessing, so it is left to the
-    // parameter check to tell us the probe was wrong rather than the generator.
+    // parameter check to tell us the probe was wrong rather than the handler.
     const base = NAMES[variant % NAMES.length];
     const min = num(schema.minLength) ?? 0;
     return base.length >= min ? base : base.padEnd(min, 'x');
@@ -188,7 +188,7 @@ function text(schema, variant) {
 // means anything in the answer it arrived with, so the pages have to be asked
 // for in order.
 //
-// The seed is held still across the whole walk on purpose. A generator that
+// The seed is held still across the whole walk on purpose. A handler that
 // mints its token out of `seed` rather than out of the request is the exact
 // mistake being looked for, and a still seed makes it a fixed point — visible
 // on the second page here instead of on somebody's client.
@@ -227,7 +227,7 @@ export function nextPage(previous, paging, token) {
 // mismatch there is a broken mock. A query parameter is usually a control
 // rather than content — `?source=realtime`, `?page_size=50`, `?cursor=…` — and
 // real APIs collide those names with unrelated response properties all the
-// time. Enforcing on them rejected working generators for a rule they were
+// time. Enforcing on them rejected working handlers for a rule they were
 // right to ignore. The prompt still asks for query echo where it is meaningful;
 // it is simply not a reason to throw the file away.
 // ---------------------------------------------------------------------------