@zenera/gym 1.1.39 → 1.1.41

package/dist/prompt.d.ts

@@ -1,25 +1,38 @@
-import type { GeneratorInput } from './envelope.ts';
+import type { Catalog } from './catalog.ts';
+import type { HandlerRequest } from './runtime.ts';
 import { type Operation } from './spec.ts';
-export declare const SYSTEM: string;
-export declare function brief(operation: Operation): string;
-/**
- * Repeated in the file the model writes, so it is worth spelling out: the
- * schema it validates against must be the one it was shown, embedded, not
- * loaded from anywhere.
- */
-export declare function instruction(operation: Operation): string;
-export declare function retry(diagnostics: readonly string[]): string;
-export interface ExampleRequest {
-    input: GeneratorInput;
-    output?: unknown;
+export declare const SYSTEM = "You write the request handler for one operation of a simulated HTTP API.\n\nTHE HANDLER is one TypeScript module, run by Node.js as it is:\n\n    export default async function handle(req, ctx) { ... return body; }\n\n- `req`: { operationId, method, path, pathParams, query, headers, body, seed }.\n  pathParams and query values are strings, as on the wire.\n- Return the response body. It must match the response type exactly.\n- No imports of any kind. Only erasable TypeScript: type annotations, interfaces and\n  `type` aliases are fine; enums, namespaces and parameter properties are not.\n- No network, no files, no timers, no global state between calls.\n\nTHE WORLD. All content lives in a shared world of records, grouped by type. Several\nAPIs share it, so a message listed here is the message read there. Your handler owns\nthe mechanics \u2014 which type, which filter, what a write changes \u2014 and never invents\ncontent itself. Name records by their schema TYPE (a name with a capital: \"Message\",\n\"Tier0\"); the world knows which collection and id field each type has. When the world\nlacks what a request needs, ask for it and an agent writes it, consistent with\neverything else:\n\n  ctx.db.collection(Type)            sync: all(), get(id), has(id), find(fn), count(),\n                                     put(id, record), putMany([{id, value}]), delete(id)\n  await ctx.lookup(Type, id, { where?, hint?, idField? })\n                                     the record with that id, made if missing\n  await ctx.ensure(Type, { min?, count?, where?, hint? })\n                                     all records (matching where), making some if fewer than min\n  await ctx.synthesize({ collection: Type, count?, ids?, where?, hint? })\n                                     make new records now; returns them, already stored\n  await ctx.owner()                  the account the API is called as: { id, email, displayName, timeZone? }\n  ctx.page(items, { token?, offset?, size?, defaultSize? })\n                                     -> { items, nextToken, nextOffset, hasMore, total }\n  ctx.fail(status, body?)            answer with an HTTP error instead\n  ctx.newId(pattern?)  ctx.fromPattern(regex)  ctx.now()  ctx.random()  ctx.int(a, b)  ctx.pick(list)\n\n`idField` is for the first use of a type whose id property is not `id` (e.g. \"user_id\");\nafter that the binding remembers it. `where` pins values every made record must carry\n(e.g. { calendarId }); `hint` says in a sentence what the request is after (a search\nquery, a filter), so the made records actually answer it.\n\nHOW EACH KIND OF OPERATION WORKS\n- Read one (GET /things/{id}): `await ctx.lookup('Thing', req.pathParams.id)`.\n- List (GET /things): `await ctx.ensure('Thing', { where, hint })`, then filter by the\n  query parameters that describe content (search text, dates, labels, owner\u2026) in code,\n  sort as the API would, then `ctx.page`. If filtering leaves nothing for a query that\n  plainly expects results, `await ctx.synthesize({ collection: 'Thing', hint: <the query> })` and filter again.\n- Create (POST): build the stored record from the request body plus the server-assigned\n  fields (id via ctx.newId(<the id pattern>), timestamps via ctx.now(), status\u2026),\n  `put` it, return it. Later reads must see it.\n- Update (PUT/PATCH): lookup, merge, put, return. Delete: delete, return what the schema asks.\n- Actions and computed answers (free/busy, search, stats\u2026): derive the answer from the\n  collections they are about, ensuring those exist first.\n- Store whole records \u2014 the richest type the API has for the thing (e.g. a full\n  `Message`, not a `MessageRef`) \u2014 and project to the response shape. Use the type\n  sibling operations use: read their handlers first.\n- People come from the world, never from code. Ids that stand for the caller \u2014 \"me\",\n  \"primary\", \"self\", \"default\" \u2014 mean `await ctx.owner()`: resolve them to the owner's\n  email (or whatever id the other records use for that person) before you store or\n  filter by them, so \"primary\" and the owner's address are one calendar. Fields like\n  sender, organizer, author or owner on a record you create are the owner's.\n- Where a path parameter has the same name as a property of the response, the response\n  carries the request's value.\n- Paging: always through ctx.page, passing the client's token or offset as given.\n  The token is opaque and always advances; on the last page leave the next token out\n  (or null, if the schema allows) and set any has-more flag false.\n\nREFERENCE DOCUMENTS. When the brief quotes documentation, or search_docs is among your\ntools, the documents describe behaviour the schema cannot: what a write changes\nelsewhere, what is refused and with which status, defaults, state transitions.\nImplement what they say. Content still comes from the world, never from the documents.\n\nWORKFLOW\n1. Look before writing: read_handler for the related operations already built,\n   list_collections for what the world holds, describe_types for types you were not\n   shown. In a large API, trace_api on the record type finds every operation that\n   carries it, and grep_api / list_api find the rest. Read the reference documents\n   when the operation's behaviour is not obvious from its schema.\n2. test_handler with the whole module. It runs the handler against probe requests in a\n   copy of the world and reports every problem. Fix and test again until it passes.\n   A passing test is the end of the job.";
+export interface BriefOptions {
+    catalog: Catalog;
+    /** operations this one must agree with, closest first, and whether each has a handler */
+    siblings: readonly {
+        operation: Operation;
+        built: boolean;
+        type?: string;
+    }[];
+    collections: readonly {
+        name: string;
+        count: number;
+    }[];
+    /** where each type lives, fixed by the handlers before this one */
+    bindings: Readonly<Record<string, {
+        collection: string;
+        idField: string;
+    }>>;
+    /** reference passages about this operation, quoted; '' when there are none */
+    passages?: string;
 }
-export interface RegenerationPromptContext {
-    operation: Operation;
+export declare function brief(operation: Operation, opts: BriefOptions): string;
+export interface Repair {
     currentSource: string;
-    failingInput: GeneratorInput;
+    failingInput: HandlerRequest;
     fault: string;
     stderr?: string;
-    examples?: readonly ExampleRequest[];
+    examples?: readonly {
+        input: HandlerRequest;
+        output?: unknown;
+    }[];
 }
-export declare function regenerationInstruction(ctx: RegenerationPromptContext): string;
+export declare function repairBrief(repair: Repair): string;
+export declare function retryNudge(diagnostics: readonly string[]): string;
 //# sourceMappingURL=prompt.d.ts.map

package/dist/prompt.js

@@ -1,61 +1,97 @@
-import { AVAILABLE } from "./image.js";
 import { called } from "./spec.js";
 // ---------------------------------------------------------------------------
-// What the model is told
+// What the handler agent is told
 //
-// A contract, not a request. The generator is a program with a fixed calling
-// convention that this package depends on in three places — the entry point,
-// the input shape, the output file — so those are stated as rules rather than
-// as suggestions, and everything discretionary is stated as taste.
+// A contract, not a request. The handler is a module with a fixed shape that
+// this package runs in three places — the judge, the server, the repair loop —
+// so the shape is stated as rules; everything discretionary is taste.
 //
-// The one rule worth its own paragraph is the echo: a mock that answers
-// `GET /users/12324` with somebody else's id is worse than useless, because it
-// validates and quietly breaks whatever is being developed against it.
+// The rule that earns its paragraph is the split between mechanics and
+// content. A handler that writes `subject: 'Hello'` inline answers every story
+// the same way; one that asks `ctx.lookup` for the message answers with the
+// story's. So content is never written here, only fetched.
 // ---------------------------------------------------------------------------
-export const SYSTEM = [
-    'You write one Python 3 file that fabricates a plausible HTTP response body.',
-    '',
-    'CALLING CONVENTION',
-    '- `sys.argv[1]` is a path to a JSON file to read; `sys.argv[2]` is a path to write to.',
-    '- Write exactly one JSON document to `sys.argv[2]` and print nothing to stdout.',
-    '- Exit non-zero with a message on stderr if you cannot produce a valid body.',
-    '',
-    'THE INPUT FILE holds:',
-    '  operationId, method, path, pathParams, query, headers, body, seed',
-    '',
-    'ENVIRONMENT',
-    `- These libraries are installed: ${AVAILABLE.join(', ')}, plus the standard library.`,
-    '- There is no network and no pip. Importing anything else fails the file.',
-    '- Seed both `random.seed(seed)` and `Faker.seed(seed)` from the input, first thing.',
-    '',
-    'RULES',
-    '1. The output must validate against the response schema given below. Build the',
-    '   object, then check it with `jsonschema.validate` before writing, and fix it',
-    '   rather than emitting something that fails.',
-    '2. Echo the request. Where a path parameter has the same name as a property',
-    "   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. 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',
-    '   and must not be copied into the body; see PAGINATION below where the',
-    '   operation has one.',
-    '3. Every required property must be present. Optional ones may be omitted',
-    '   sometimes; that is what makes a mock useful.',
-    '4. Values must suit their names, not just their types. Use `faker` for anything',
-    '   a person would recognise — names, emails, addresses, companies, phone',
-    '   numbers, sentences. Use `exrex.getone(pattern)` when a string schema has a',
-    '   `pattern`. Respect `enum`, `format`, `minimum`, `maxLength` and friends.',
-    '5. Arrays get 1 to 5 items unless the schema says otherwise.',
-    '6. The file is run once per request and must be deterministic for a given seed.',
-    '',
-    'ANSWER WITH THE FILE AND NOTHING ELSE. No explanation, no markdown fence.',
-].join('\n');
-export function brief(operation) {
+export const SYSTEM = `You write the request handler for one operation of a simulated HTTP API.
+
+THE HANDLER is one TypeScript module, run by Node.js as it is:
+
+    export default async function handle(req, ctx) { ... return body; }
+
+- \`req\`: { operationId, method, path, pathParams, query, headers, body, seed }.
+  pathParams and query values are strings, as on the wire.
+- Return the response body. It must match the response type exactly.
+- No imports of any kind. Only erasable TypeScript: type annotations, interfaces and
+  \`type\` aliases are fine; enums, namespaces and parameter properties are not.
+- No network, no files, no timers, no global state between calls.
+
+THE WORLD. All content lives in a shared world of records, grouped by type. Several
+APIs share it, so a message listed here is the message read there. Your handler owns
+the mechanics — which type, which filter, what a write changes — and never invents
+content itself. Name records by their schema TYPE (a name with a capital: "Message",
+"Tier0"); the world knows which collection and id field each type has. When the world
+lacks what a request needs, ask for it and an agent writes it, consistent with
+everything else:
+
+  ctx.db.collection(Type)            sync: all(), get(id), has(id), find(fn), count(),
+                                     put(id, record), putMany([{id, value}]), delete(id)
+  await ctx.lookup(Type, id, { where?, hint?, idField? })
+                                     the record with that id, made if missing
+  await ctx.ensure(Type, { min?, count?, where?, hint? })
+                                     all records (matching where), making some if fewer than min
+  await ctx.synthesize({ collection: Type, count?, ids?, where?, hint? })
+                                     make new records now; returns them, already stored
+  await ctx.owner()                  the account the API is called as: { id, email, displayName, timeZone? }
+  ctx.page(items, { token?, offset?, size?, defaultSize? })
+                                     -> { items, nextToken, nextOffset, hasMore, total }
+  ctx.fail(status, body?)            answer with an HTTP error instead
+  ctx.newId(pattern?)  ctx.fromPattern(regex)  ctx.now()  ctx.random()  ctx.int(a, b)  ctx.pick(list)
+
+\`idField\` is for the first use of a type whose id property is not \`id\` (e.g. "user_id");
+after that the binding remembers it. \`where\` pins values every made record must carry
+(e.g. { calendarId }); \`hint\` says in a sentence what the request is after (a search
+query, a filter), so the made records actually answer it.
+
+HOW EACH KIND OF OPERATION WORKS
+- Read one (GET /things/{id}): \`await ctx.lookup('Thing', req.pathParams.id)\`.
+- List (GET /things): \`await ctx.ensure('Thing', { where, hint })\`, then filter by the
+  query parameters that describe content (search text, dates, labels, owner…) in code,
+  sort as the API would, then \`ctx.page\`. If filtering leaves nothing for a query that
+  plainly expects results, \`await ctx.synthesize({ collection: 'Thing', hint: <the query> })\` and filter again.
+- Create (POST): build the stored record from the request body plus the server-assigned
+  fields (id via ctx.newId(<the id pattern>), timestamps via ctx.now(), status…),
+  \`put\` it, return it. Later reads must see it.
+- Update (PUT/PATCH): lookup, merge, put, return. Delete: delete, return what the schema asks.
+- Actions and computed answers (free/busy, search, stats…): derive the answer from the
+  collections they are about, ensuring those exist first.
+- Store whole records — the richest type the API has for the thing (e.g. a full
+  \`Message\`, not a \`MessageRef\`) — and project to the response shape. Use the type
+  sibling operations use: read their handlers first.
+- People come from the world, never from code. Ids that stand for the caller — "me",
+  "primary", "self", "default" — mean \`await ctx.owner()\`: resolve them to the owner's
+  email (or whatever id the other records use for that person) before you store or
+  filter by them, so "primary" and the owner's address are one calendar. Fields like
+  sender, organizer, author or owner on a record you create are the owner's.
+- Where a path parameter has the same name as a property of the response, the response
+  carries the request's value.
+- Paging: always through ctx.page, passing the client's token or offset as given.
+  The token is opaque and always advances; on the last page leave the next token out
+  (or null, if the schema allows) and set any has-more flag false.
+
+REFERENCE DOCUMENTS. When the brief quotes documentation, or search_docs is among your
+tools, the documents describe behaviour the schema cannot: what a write changes
+elsewhere, what is refused and with which status, defaults, state transitions.
+Implement what they say. Content still comes from the world, never from the documents.
+
+WORKFLOW
+1. Look before writing: read_handler for the related operations already built,
+   list_collections for what the world holds, describe_types for types you were not
+   shown. In a large API, trace_api on the record type finds every operation that
+   carries it, and grep_api / list_api find the rest. Read the reference documents
+   when the operation's behaviour is not obvious from its schema.
+2. test_handler with the whole module. It runs the handler against probe requests in a
+   copy of the world and reports every problem. Fix and test again until it passes.
+   A passing test is the end of the job.`;
+export function brief(operation, opts) {
     const lines = [
         `OPERATION  ${operation.method.toUpperCase()} ${called(operation)}`,
         `operationId: ${operation.operationId}`,
@@ -64,125 +100,103 @@ export function brief(operation) {
         lines.push(`summary: ${operation.summary}`);
     }
     if (operation.description && operation.description !== operation.summary) {
-        lines.push(`description: ${operation.description.slice(0, 600)}`);
+        lines.push(`description: ${operation.description.slice(0, 800)}`);
     }
-    lines.push('', 'PARAMETERS');
-    if (operation.params.length === 0) {
-        lines.push('  (none)');
+    lines.push('', opts.catalog.describe(operation) || fallback(operation));
+    const record = opts.catalog.itemType(operation);
+    if (record) {
+        lines.push('', `This operation is about \`${record}\` records.`);
     }
-    for (const p of operation.params) {
-        const note = p.description ? `  # ${p.description.split('\n')[0].slice(0, 100)}` : '';
-        lines.push(`  ${p.name} (in ${p.in}${p.required ? ', required' : ''}): ${JSON.stringify(p.schema)}${note}`);
-    }
-    if (operation.requestBody) {
-        lines.push('', 'REQUEST BODY SCHEMA (arrives as `body`)', json(operation.requestBody.schema));
+    if (!operation.success.schema) {
+        lines.push('', 'This operation answers with no body: return null.');
     }
     if (operation.paging) {
         lines.push('', ...pagination(operation.paging));
     }
-    lines.push('', `RESPONSE SCHEMA (status ${operation.success.status})`);
-    lines.push(operation.success.schema ? json(operation.success.schema) : '  (no body)');
+    if (opts.siblings.length > 0) {
+        lines.push('', 'RELATED OPERATIONS (read the built ones with read_handler and reuse their collections)', ...opts.siblings.map(({ operation: o, built, type }) => `  ${built ? '[built]' : '[     ]'} ${o.method.toUpperCase()} ${called(o)}  ${o.operationId}` +
+            (type ? `  → ${type}` : '')));
+    }
+    const bound = Object.entries(opts.bindings).filter(([type]) => !type.startsWith('@'));
+    lines.push('', 'WHERE TYPES LIVE (fixed: name the type and the binding finds its collection)', ...(bound.length > 0
+        ? bound.map(([type, b]) => `  ${type} → ${b.collection} (keyed by ${b.idField})`)
+        : ['  (nothing yet — the first handler to use a type gives it its place)']));
+    if (opts.passages) {
+        lines.push('', 'FROM THE REFERENCE DOCUMENTS (what the API does, beyond its schema)', opts.passages.trimEnd());
+    }
+    lines.push('', 'THE WORLD SO FAR', ...(opts.collections.length > 0
+        ? opts.collections.map((c) => `  ${c.name}: ${c.count} records`)
+        : ['  (empty — collections are created by the first handler that asks for them)']));
     return lines.join('\n');
 }
+/** For an operation the catalog could not match: its JSON, cut to a sane length. */
+function fallback(operation) {
+    const out = ['REQUEST'];
+    for (const p of operation.params) {
+        out.push(`  ${p.in} ${p.name}${p.required ? '' : '?'}: ${JSON.stringify(p.schema)}`);
+    }
+    if (operation.requestBody) {
+        out.push(`  body: ${JSON.stringify(operation.requestBody.schema).slice(0, 4000)}`);
+    }
+    out.push('', `RESPONSE ${operation.success.status}: ${JSON.stringify(operation.success.schema ?? null).slice(0, 8000)}`);
+    return out.join('\n');
+}
 /**
- * Said only to the operations that page, and said in terms of their own
- * property names. The rule that earns the paragraph is the third one: a body
- * offering the token it was just given passes the schema, passes the echo rule,
- * and hangs every client that walks the list.
+ * Said only to the operations that page, in their own names. The rule that
+ * matters is that the token advances: a body offering back the token it was
+ * given passes the schema and hangs every client that walks the list.
  */
 function pagination(paging) {
-    const advance = paging.style === 'cursor'
-        ? 'the base64 of a small JSON object holding the next page index, such as {"p": 2}'
-        : "the offset of the next page — this page's offset plus its size";
-    const where = paging.paramIn === 'body' ? 'In the request `body`, ' : '';
-    const lines = [
-        'PAGINATION',
-        `  This operation is paged. ${where}\`${paging.param}\` asks for a page;`,
-        '  absent or empty means the first one.',
-        '  - Fabricate a random number of pages between 1 and 10 in total and no more.',
-    ];
+    const where = paging.paramIn === 'body' ? 'req.body' : 'req.query';
+    const from = paging.style === 'cursor'
+        ? `{ token: ${where}.${paging.param}`
+        : `{ offset: ${where}.${paging.param}`;
+    const size = paging.size ? `, size: ${where}.${paging.size}` : '';
+    const lines = ['PAGINATION', `  This operation pages: \`ctx.page(items, ${from}${size} })\`.`];
     if (paging.next) {
-        lines.push(`  - \`${paging.next}\` carries the token for the page after this one.`, `    Build it out of \`${paging.param}\`:`, `    ${advance}.`, '  - Never build it out of `seed`. Unpinned, the seed changes on every', '    request; pinned, it is a function of the query. A token made from it', '    either wanders or never changes.', '  - It must strictly advance. Answering with the token you were given is', '    the one failure that matters: a client following it loops forever.');
+        const end = paging.nextNullable
+            ? 'null'
+            : paging.nextRequired
+                ? 'still present (the schema requires it), with the items empty past the end'
+                : 'left out';
+        lines.push(`  \`${paging.next}\` carries ${paging.style === 'cursor' ? 'nextToken' : 'nextOffset'}; on the last page it is ${end}.`);
     }
-    if (paging.more && !stuck(paging)) {
-        lines.push(`  - \`${paging.more}\` is false on the last page and true before it.`);
+    if (paging.more) {
+        lines.push(`  \`${paging.more}\` is hasMore.`);
     }
-    if (paging.next) {
-        lines.push(...last(paging));
+    if (paging.items) {
+        lines.push(`  \`${paging.items}\` holds the page's items.`);
     }
-    lines.push('  - A token you cannot read, or one past the end, is the last page,', `    ended the same way and with ${paging.items ? `\`${paging.items}\` empty` : 'nothing listed'}.`, '    Never an error, and never the first page again.');
     return lines;
 }
-/**
- * How the last page says so. A token that is required and cannot be null has
- * nowhere to put the ending, so the ending has to be said some other way —
- * telling the model to null it anyway would only ask for an invalid body.
- */
-const stuck = (paging) => !paging.nextNullable && paging.nextRequired === true;
-function last(paging) {
-    if (paging.nextNullable) {
-        return [`  - On the last page set \`${paging.next}\` to null.`];
-    }
-    if (!stuck(paging)) {
-        return [`  - On the last page leave \`${paging.next}\` out.`];
-    }
-    const otherwise = [paging.more && `\`${paging.more}\` false`, paging.items && 'nothing listed']
-        .filter(Boolean)
-        .join(' and ');
-    return [
-        `  - The schema requires \`${paging.next}\` on every page, so the last page`,
-        `    ends the list the other way: ${otherwise || 'an empty page'} (e.g. \`${paging.items || 'results'}\` as an empty list \`[]\`).`,
-    ];
-}
-/**
- * Repeated in the file the model writes, so it is worth spelling out: the
- * schema it validates against must be the one it was shown, embedded, not
- * loaded from anywhere.
- */
-export function instruction(operation) {
-    return [
-        brief(operation),
-        '',
-        'Embed the response schema in the file as a literal and validate against it.',
-    ].join('\n');
-}
-export function retry(diagnostics) {
-    return [
-        'That file did not pass. Fix it and answer with the whole file again.',
-        '',
-        ...diagnostics,
-    ].join('\n');
-}
-export function regenerationInstruction(ctx) {
-    const { operation, currentSource, failingInput, fault, stderr, examples } = ctx;
+export function repairBrief(repair) {
     const lines = [
-        brief(operation),
+        'THE CURRENT HANDLER FAILED ON A REAL REQUEST. Fix it; keep what works.',
         '',
-        'Embed the response schema in the file as a literal and validate against it.',
-        '',
-        'CURRENT GENERATOR CODE:',
-        '```python',
-        currentSource.trim(),
+        'CURRENT HANDLER:',
+        '```ts',
+        repair.currentSource.trim(),
         '```',
         '',
-        'THE GENERATOR FAILED ON THIS REQUEST:',
-        'Input:',
-        json(failingInput),
+        'FAILING REQUEST:',
+        json(repair.failingInput),
         '',
-        `Fault: ${fault}`,
+        `FAULT: ${repair.fault}`,
     ];
-    if (stderr && stderr.trim()) {
-        lines.push('', 'Stderr / Traceback:', '```', stderr.trim(), '```');
+    if (repair.stderr?.trim()) {
+        lines.push('', 'STACK:', '```', repair.stderr.trim().split('\n').slice(0, 15).join('\n'), '```');
     }
-    if (examples && examples.length > 0) {
-        lines.push('', 'PREVIOUS SUCCESSFUL REQUESTS (use as examples):');
-        for (let i = 0; i < examples.length; i++) {
-            const ex = examples[i];
-            lines.push(`Example ${i + 1}:`, 'Input:', json(ex.input), 'Output produced:', json(ex.output), '');
-        }
+    for (const [i, ex] of (repair.examples ?? []).entries()) {
+        lines.push('', `EARLIER SUCCESSFUL REQUEST ${i + 1}:`, json(ex.input), 'answered:', json(ex.output).slice(0, 3000));
     }
-    lines.push('TASK:', 'Fix the generator code so that it handles the failing request without error, produces valid output that matches the schema, and continues to produce valid output for the previous example requests.', 'ANSWER WITH THE COMPLETE REVISED PYTHON FILE AND NOTHING ELSE. No explanation, no markdown fence.');
     return lines.join('\n');
 }
+export function retryNudge(diagnostics) {
+    return [
+        'The handler has not passed test_handler yet. Fix these and test again:',
+        '',
+        ...diagnostics,
+    ].join('\n');
+}
 const json = (value) => JSON.stringify(value, null, 1);
 //# sourceMappingURL=prompt.js.map

package/dist/quiet.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=quiet.d.ts.map

package/dist/quiet.js

@@ -0,0 +1,7 @@
+// LanceDB logs through env_logger, read once when its native module first
+// loads, and at its default level it narrates routine work — "No existing
+// dataset … it will be created" on every index gym builds. This runs before
+// anything imports it; an explicit setting in the environment still wins.
+process.env.LANCEDB_LOG ??= 'error';
+export {};
+//# sourceMappingURL=quiet.js.map

package/dist/router.js

@@ -10,7 +10,11 @@ export class Router {
             const id = `${operation.method} ${operation.path}${query(fixed)}`;
             const clash = seen.get(id);
             if (clash) {
-                throw new SpecError(`${id} is declared twice`, `${clash.source} and ${operation.source} both define it`);
+                throw new SpecError(`${id} is declared twice`, clash.source === operation.source
+                    ? `${operation.source} defines it twice`
+                    : `${clash.source} and ${operation.source} both define it — two versions ` +
+                        'of one API cannot be served by one process: name one of them, or run ' +
+                        'two processes on different ports with the same --world');
             }
             seen.set(id, operation);
             const segments = compile(operation.path);

package/dist/runtime.d.ts

@@ -0,0 +1,160 @@
+import type { Collection, WorldStore } from './store.ts';
+export interface HandlerRequest {
+    operationId: string;
+    method: string;
+    /** the template, `/users/{userId}/messages/{id}` */
+    path: string;
+    pathParams: Record<string, string>;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    body: unknown;
+    seed: number;
+}
+/** What a handler may ask the world agent to make up. */
+export interface SynthesisRequest {
+    collection: string;
+    /** the component schema every record must satisfy, e.g. `"Message"` */
+    type?: string;
+    /** how many to make when no ids are named. Default 5 */
+    count?: number;
+    /** nothing is made if this many records already match `where` */
+    min?: number;
+    /** ids that must exist afterwards */
+    ids?: (string | number)[];
+    /** the property that holds the id. Default `id` */
+    idField?: string;
+    /** values every new record must carry, e.g. `{ calendarId: 'primary' }` */
+    where?: Record<string, unknown>;
+    /** what the records are for, in a sentence: the query, the filter, the context */
+    hint?: string;
+    /** the first read of this collection (and `where`): fill it as the story has it */
+    populate?: boolean;
+}
+export type Synthesize = (request: SynthesisRequest) => Promise<Record<string, unknown>[]>;
+/** Where accounts live, and the id of the one the API is called as. */
+export declare const ACCOUNTS = "accounts";
+/**
+ * Whether a collection — or the part of it `where` selects — has ever been
+ * filled by the world agent. Counting records cannot tell: a mailbox whose
+ * only message is the one the client just sent is not an inbox yet.
+ */
+export declare function populatedKey(collection: string, where?: Record<string, unknown>): string;
+export declare const OWNER = "@me";
+export interface Account {
+    id: string;
+    email: string;
+    displayName?: string;
+    [key: string]: unknown;
+}
+export interface Page<T> {
+    items: T[];
+    /** the token for the next page, null on the last */
+    nextToken: string | null;
+    /** the offset of the next page, null on the last */
+    nextOffset: number | null;
+    hasMore: boolean;
+    total: number;
+}
+export interface PageOptions {
+    /** the token a previous page handed out, as the client sent it back */
+    token?: unknown;
+    /** for offset-style APIs, the offset the client asked for */
+    offset?: unknown;
+    /** page size the client asked for */
+    size?: unknown;
+    /** page size when the client did not say. Default 10 */
+    defaultSize?: number;
+}
+export interface HandlerContext {
+    /**
+     * The shared world, by type: `ctx.db.collection('Message').get(id)`. A
+     * lowercase name is taken as a collection name instead.
+     */
+    db: {
+        collection<T = Record<string, unknown>>(name: string): Collection<T>;
+    };
+    /** a record by id, made up by the world agent if the world does not have it */
+    lookup<T = Record<string, unknown>>(type: string, id: string | number, options?: Omit<SynthesisRequest, 'collection' | 'ids' | 'count'>): Promise<T>;
+    /**
+     * Every record in a collection, after making sure there are at least
+     * `min` (default 1) matching `where`. The way a list endpoint starts.
+     */
+    ensure<T = Record<string, unknown>>(type: string, options?: Omit<SynthesisRequest, 'collection' | 'ids'>): Promise<T[]>;
+    /** asks the world agent for new records directly; they are stored before this returns */
+    synthesize: Synthesize;
+    /**
+     * The account this API is called as — the person `me`, `primary` and
+     * `self` stand for. Made once, from the story, and shared by every API.
+     */
+    owner(): Promise<Account>;
+    /** a page of `items` with a token or offset that always advances and always ends */
+    page<T>(items: readonly T[], options?: PageOptions): Page<T>;
+    /** answers with an HTTP error instead of the success body */
+    fail(status: number, body?: unknown): never;
+    /** a string matching a regular expression, e.g. a schema `pattern` */
+    fromPattern(pattern: string): string;
+    /** a fresh id: hex by default, or matching `pattern` when given */
+    newId(pattern?: string): string;
+    /** seeded randomness, so one request answers the same way twice under `--seed` */
+    random(): number;
+    int(min: number, max: number): number;
+    pick<T>(items: readonly T[]): T;
+    /** the current time as RFC 3339 */
+    now(): string;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body?: unknown);
+}
+/** Where a type's records live, and which property holds their id. */
+export interface Binding {
+    collection: string;
+    idField: string;
+}
+export type Bindings = Readonly<Record<string, Binding>>;
+/** One collection a handler touched, and as which type. */
+export interface Use {
+    collection: string;
+    type?: string;
+    idField?: string;
+}
+/** The type gym gives the owner account; no document declares one. */
+export declare const OWNER_TYPE = "@owner";
+/** A name that starts with a capital is a type: `Message`, not `messages`. */
+export declare const isTypeName: (name: string) => boolean;
+/**
+ * The collection an unbound type gets: `Message` → `messages`,
+ * `PolicyTransportZone` → `policy_transport_zones`. Only ever a first guess —
+ * once bound, the binding is the answer.
+ */
+export declare function collectionFor(type: string): string;
+/**
+ * A name as a handler wrote it, made concrete. A type name finds its
+ * collection through the bindings; a collection name finds its type the same
+ * way, backwards. Whatever was asked is reported to `record`, which is how the
+ * judge learns which types a handler stores where.
+ */
+export declare function resolve(name: string, options: {
+    type?: string;
+    idField?: string;
+}, bindings: Bindings): Required<Pick<Use, 'collection'>> & Use;
+export declare function createContext(input: HandlerRequest, store: WorldStore, synthesize: Synthesize, bindings?: Bindings, record?: (use: Use) => void): HandlerContext;
+/** Every key in `where` present on the record with an equal value, compared as text. */
+/** Every key in `where` matched by the record: see `same`. */
+export declare function matches(record: Record<string, unknown>, where?: Record<string, unknown>): boolean;
+/**
+ * Whether a value is what was asked for. Scalars compare as text (a path
+ * segment is text, the stored id may be a number); an object asks for a subset
+ * of the same shape; a list asks for every item it names; and a scalar asked
+ * of a list asks whether the list holds it — `{ labelIds: 'INBOX' }` finds the
+ * messages labelled INBOX.
+ */
+export declare function same(actual: unknown, wanted: unknown): boolean;
+/**
+ * The one paging rule, written once rather than by every handler: the token is
+ * the next offset, it strictly advances, and it is absent on the last page. A
+ * token that cannot be read is the end of the list, never the start of it.
+ */
+export declare function page<T>(items: readonly T[], options: PageOptions): Page<T>;
+//# sourceMappingURL=runtime.d.ts.map