@zenera/gym 1.1.39 → 1.1.41

package/dist/runtime.js

@@ -0,0 +1,229 @@
+import RandExp from 'randexp';
+/** Key order is an accident of how a handler wrote it; it must not change a key. */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonical);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.keys(value)
+            .sort()
+            .map((k) => [k, canonical(value[k])]);
+    }
+    return value;
+}
+/** Where accounts live, and the id of the one the API is called as. */
+export 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 function populatedKey(collection, where) {
+    return `populated:${collection}:${JSON.stringify(canonical(where ?? {}))}`;
+}
+export const OWNER = '@me';
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`HTTP ${status}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.body = body ?? { error: `HTTP ${status}` };
+    }
+}
+/** The type gym gives the owner account; no document declares one. */
+export const OWNER_TYPE = '@owner';
+/** A name that starts with a capital is a type: `Message`, not `messages`. */
+export const isTypeName = (name) => /^[A-Z]/.test(name);
+/**
+ * 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 function collectionFor(type) {
+    const snake = type
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .toLowerCase()
+        .replace(/^_+|_+$/g, '');
+    return /s$/.test(snake) ? snake : `${snake}s`;
+}
+/**
+ * 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 function resolve(name, options, bindings) {
+    if (name === ACCOUNTS) {
+        return { collection: ACCOUNTS, type: OWNER_TYPE, idField: 'id' };
+    }
+    if (isTypeName(name)) {
+        const bound = bindings[name];
+        return {
+            collection: bound?.collection ?? collectionFor(name),
+            type: name,
+            idField: options.idField ?? bound?.idField,
+        };
+    }
+    const type = options.type ?? Object.entries(bindings).find(([, b]) => b.collection === name)?.[0];
+    const bound = type ? bindings[type] : undefined;
+    return { collection: name, type, idField: options.idField ?? bound?.idField };
+}
+export function createContext(input, store, synthesize, bindings = {}, record = () => { }) {
+    const at = (name, options = {}) => {
+        const where = resolve(name, options, bindings);
+        record(where);
+        return where;
+    };
+    const random = mulberry32(input.seed || 1);
+    const int = (min, max) => min + Math.floor(random() * (max - min + 1));
+    const fromPattern = (pattern) => {
+        const gen = new RandExp(stripSlashes(pattern));
+        gen.max = 8;
+        gen.randInt = int;
+        return gen.gen();
+    };
+    const ctx = {
+        db: { collection: (name) => store.collection(at(name).collection) },
+        async lookup(name, id, options = {}) {
+            const { collection, type, idField } = at(name, options);
+            const col = store.collection(collection);
+            const found = col.get(id);
+            if (found !== undefined) {
+                return found;
+            }
+            await synthesize({ ...options, collection, type, idField, ids: [id] });
+            const made = col.get(id);
+            if (made === undefined) {
+                throw new Error(`the world agent did not create ${collection}/${String(id)}`);
+            }
+            return made;
+        },
+        async ensure(name, options = {}) {
+            const { collection, type, idField } = at(name, options);
+            const min = options.min ?? 1;
+            const col = store.collection(collection);
+            const matching = () => col.all().filter((r) => matches(r, options.where));
+            const have = matching().length;
+            const populate = !store.getMeta(populatedKey(collection, options.where));
+            if (populate || have < min) {
+                await synthesize({
+                    ...options,
+                    collection,
+                    type,
+                    idField,
+                    min,
+                    populate,
+                    count: options.count ?? (populate ? Math.max(min, 8) : Math.max(min - have, 5)),
+                });
+            }
+            return matching();
+        },
+        synthesize: (request) => {
+            const { collection, type, idField } = at(request.collection, request);
+            return synthesize({ ...request, collection, type, idField });
+        },
+        owner: () => ctx.lookup(ACCOUNTS, OWNER, {
+            hint: 'the person whose mailbox, calendar and data this API serves',
+        }),
+        page: (items, options = {}) => page(items, options),
+        fail(status, body) {
+            throw new HttpError(status, body);
+        },
+        fromPattern,
+        newId: (pattern) => pattern
+            ? fromPattern(pattern)
+            : Array.from({ length: 16 }, () => int(0, 15).toString(16)).join(''),
+        random,
+        int,
+        pick: (items) => items[int(0, items.length - 1)],
+        now: () => new Date().toISOString(),
+    };
+    return ctx;
+}
+/** 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 function matches(record, where) {
+    return !where || same(record, where);
+}
+/**
+ * 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 function same(actual, wanted) {
+    if (wanted !== null && typeof wanted === 'object') {
+        if (Array.isArray(wanted)) {
+            return Array.isArray(actual) && wanted.every((w) => actual.some((a) => same(a, w)));
+        }
+        return (actual !== null &&
+            typeof actual === 'object' &&
+            Object.entries(wanted).every(([k, v]) => same(actual[k], v)));
+    }
+    if (Array.isArray(actual)) {
+        return actual.some((a) => same(a, wanted));
+    }
+    return actual !== undefined && String(actual) === String(wanted);
+}
+/**
+ * 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 function page(items, options) {
+    const size = clampSize(options.size, options.defaultSize ?? 10);
+    let start = 0;
+    if (options.token !== undefined && options.token !== null && options.token !== '') {
+        const decoded = decodeToken(String(options.token));
+        start = decoded === undefined ? items.length : decoded;
+    }
+    else if (options.offset !== undefined && options.offset !== null && options.offset !== '') {
+        const n = Number(options.offset);
+        start = Number.isFinite(n) && n >= 0 ? Math.floor(n) : items.length;
+    }
+    start = Math.min(start, items.length);
+    const end = Math.min(start + size, items.length);
+    const hasMore = end < items.length;
+    return {
+        items: items.slice(start, end),
+        nextToken: hasMore ? encodeToken(end) : null,
+        nextOffset: hasMore ? end : null,
+        hasMore,
+        total: items.length,
+    };
+}
+function clampSize(asked, fallback) {
+    const n = Number(asked);
+    return Number.isFinite(n) && n >= 1 ? Math.min(Math.floor(n), 500) : fallback;
+}
+const encodeToken = (offset) => Buffer.from(JSON.stringify({ o: offset })).toString('base64url');
+function decodeToken(token) {
+    try {
+        const parsed = JSON.parse(Buffer.from(token, 'base64url').toString('utf8'));
+        return typeof parsed.o === 'number' && parsed.o >= 0 ? parsed.o : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Some documents write a pattern as a JavaScript literal, slashes and all. */
+const stripSlashes = (pattern) => {
+    const m = /^\/(.*)\/[a-z]*$/.exec(pattern);
+    return m ? m[1] : pattern;
+};
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/schema.js

@@ -5,8 +5,7 @@
 // OpenAPI 3.0 carries a Draft-4 derivative with its own `nullable`, and
 // OpenAPI 3.1 is honest 2020-12. Ajv can be asked to speak any of them, but
 // then every consumer downstream — the request check, the response check, the
-// prompt the model reads, the `jsonschema` call inside the generator — has to
-// be told which one it is looking at. So they are converted once, here, into
+// probes, the sampler — has to be told which one it is looking at. So they are converted once, here, into
 // 2020-12, and nothing below this file knows a dialect exists.
 //
 // The other job is cycles. `dereference` replaces every `$ref` with the object

package/dist/server.js

@@ -2,7 +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 { WorkerUnavailable } from "./box.js";
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
 import { formatLogLine, formatRegenerated, formatRegenerating, formatRegenLimitHit, RegenerationLimiter, RequestHistory, saveRequestDump, } from "./logger.js";
@@ -14,15 +14,16 @@ import { describeIssues, issues } from "./validate.js";
 //
 // `node:http` and a switch. A framework would earn its place if there were
 // middleware to compose, and there is not: one route table, one validation
-// step, one generator.
+// step, one handler.
 //
 // The rules that are not obvious from the code are the ones about what does not
-// travel. Request headers are filtered before the envelope is written, because
-// that envelope becomes a file inside a container. Request bodies never reach a
-// prompt at all — the build loop uses probes it made up. And the listener binds
-// to loopback unless somebody says otherwise in as many words.
+// travel. Request headers are filtered before a handler sees them, because the
+// request can be quoted to the world agent when it asks for content. Handlers
+// are written against probes the build loop made up, never against traffic.
+// And the listener binds to loopback unless somebody says otherwise in as many
+// words.
 // ---------------------------------------------------------------------------
-/** Headers that are none of a generator's business. */
+/** Headers that are none of a handler's business. */
 const REDACTED = /^(authorization|cookie|set-cookie|proxy-authorization)$/i;
 const SECRETISH = /key|token|secret|password|credential/i;
 const DEFAULT_MAX_BODY = 1024 * 1024;
@@ -184,12 +185,11 @@ async function handle(req, res, opts) {
     }
     const { operation, pathParams } = match;
     res.setHeader('x-gym-operation', operation.operationId);
-    /** The container could not run anything: say so, and never blame the generator. */
-    const sandboxDown = async (err, extra = {}) => {
+    /** The worker could not run anything: say so, and never blame the handler. */
+    const workerDown = async (err, extra = {}) => {
         const bodyObj = {
             error: err.message,
             hint: err.hint,
-            container: err.container,
             stderr: err.stderr,
         };
         res.setHeader('retry-after', '1');
@@ -199,12 +199,12 @@ async function handle(req, res, opts) {
             routePath: operation.path,
             pathParams,
             ...extra,
-            errorKind: 'SANDBOX_UNAVAILABLE',
+            errorKind: 'WORKER_UNAVAILABLE',
             errorMessage: err.message,
             hint: err.hint,
             stderr: err.stderr,
             responseBody: bodyObj,
-            note: 'container engine failed',
+            note: 'worker unavailable',
         });
         end();
     };
@@ -249,34 +249,23 @@ async function handle(req, res, opts) {
         end();
         return;
     }
-    if (!operation.success.schema) {
-        res.statusCode = operation.success.status;
-        await finish(operation.success.status, {
-            operationId: operation.operationId,
-            routePath: operation.path,
-            pathParams,
-            requestBody: body,
-            note: 'no body declared',
-        });
-        res.end();
-        return;
-    }
-    let generator;
+    let handler;
     try {
-        generator = await opts.cache.ensure(operation);
+        handler = await opts.cache.ensure(operation);
     }
     catch (err) {
-        if (err instanceof SandboxUnavailable) {
-            await sandboxDown(err, { requestBody: body });
+        if (err instanceof WorkerUnavailable) {
+            await workerDown(err, { requestBody: body });
             return;
         }
         const status = err instanceof BuildFailed ? 501 : 500;
         const detail = reason(err);
         const bodyObj = {
-            error: `no generator for ${operation.operationId}`,
+            error: `no handler for ${operation.operationId}`,
             detail,
             diagnostics: err instanceof BuildFailed ? err.diagnostics : undefined,
             report: err instanceof BuildFailed ? err.dump : undefined,
+            agentRun: err instanceof BuildFailed ? err.report : undefined,
         };
         const end = prepareSend(res, status, bodyObj);
         await finish(status, {
@@ -284,17 +273,17 @@ async function handle(req, res, opts) {
             routePath: operation.path,
             pathParams,
             requestBody: body,
-            errorKind: 'GENERATOR_BUILD_FAILED',
-            errorMessage: `no generator: ${detail}`,
+            errorKind: 'HANDLER_BUILD_FAILED',
+            errorMessage: `no handler: ${detail}`,
             buildDump: err instanceof BuildFailed ? err.dump : undefined,
             responseBody: bodyObj,
-            note: `no generator: ${detail}`,
+            note: `no handler: ${detail}`,
         });
         end();
         return;
     }
-    res.setHeader('x-gym-cache', generator.cached ? 'hit' : 'miss');
-    let cacheStatus = generator.cached ? 'hit' : 'miss';
+    res.setHeader('x-gym-cache', handler.cached ? 'hit' : 'miss');
+    let cacheStatus = handler.cached ? 'hit' : 'miss';
     const input = {
         operationId: operation.operationId,
         method: operation.method,
@@ -310,15 +299,18 @@ async function handle(req, res, opts) {
         outcome = await opts.box.run(operation.key, input);
     }
     catch (err) {
-        if (err instanceof SandboxUnavailable) {
-            await sandboxDown(err, { requestBody: body, cacheStatus });
+        if (err instanceof WorkerUnavailable) {
+            await workerDown(err, { requestBody: body, cacheStatus });
             return;
         }
         throw err;
     }
     const responseValidator = opts.checks.for(operation).response;
     let schemaMismatch = false;
-    if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
+    if (outcome.ok &&
+        outcome.status === undefined &&
+        responseValidator &&
+        !responseValidator(outcome.value)) {
         schemaMismatch = true;
         const desc = describeIssues(issues('', responseValidator.errors));
         outcome = {
@@ -329,18 +321,51 @@ async function handle(req, res, opts) {
             value: outcome.value,
         };
     }
+    // The handler chose an HTTP error with `ctx.fail`: that is an answer, not a fault.
+    if (outcome.ok && outcome.status !== undefined) {
+        const end = prepareSend(res, outcome.status, outcome.value);
+        await finish(outcome.status, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            responseBody: outcome.value,
+            cacheStatus,
+            note: 'answered by the handler',
+        });
+        end();
+        return;
+    }
+    // The world agent failed, not the handler: rewriting working code cannot help.
+    if (!outcome.ok && outcome.agentFault) {
+        const bodyObj = { error: outcome.fault, retryable: true };
+        const end = prepareSend(res, 502, bodyObj);
+        await finish(502, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            errorKind: 'WORLD_AGENT_FAILED',
+            errorMessage: outcome.fault,
+            responseBody: bodyObj,
+            cacheStatus,
+            note: 'world agent failed',
+        });
+        end();
+        return;
+    }
     if (!outcome.ok) {
         const urlKey = url.pathname;
         const errorKind = outcome.fault?.includes('longer than')
-            ? 'GENERATOR_TIMEOUT'
+            ? 'HANDLER_TIMEOUT'
             : schemaMismatch
-                ? 'GENERATOR_SCHEMA_MISMATCH'
-                : 'GENERATOR_FAULT';
+                ? 'HANDLER_SCHEMA_MISMATCH'
+                : 'HANDLER_FAULT';
         // Check regeneration limit for this URL
         if (opts.limiter.isLimitHit(urlKey)) {
             opts.onRequest?.(formatRegenLimitHit(urlKey, opts.limiter.limit, operation.operationId));
             const bodyObj = {
-                error: `the generator for ${operation.operationId} ${outcome.fault}`,
+                error: `the handler for ${operation.operationId} ${outcome.fault}`,
                 stderr: outcome.stderr || undefined,
                 regenerationLimitHit: true,
                 regenerationLimit: opts.limiter.limit,
@@ -357,7 +382,7 @@ async function handle(req, res, opts) {
                 responseBody: bodyObj,
                 cacheStatus,
                 regenLimitHit: true,
-                note: 'generator faulted (limit hit)',
+                note: 'handler faulted (limit hit)',
             });
             end();
             return;
@@ -365,7 +390,7 @@ async function handle(req, res, opts) {
         const attempt = opts.limiter.increment(urlKey);
         opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault, outcome.stderr));
         const regenStarted = Date.now();
-        let currentSource = generator.source;
+        let currentSource = handler.source;
         if (!currentSource?.trim()) {
             currentSource = (await opts.cache.getSource?.(operation.key)) ?? '';
         }
@@ -374,7 +399,7 @@ async function handle(req, res, opts) {
                 currentSource = await readFile(opts.box.sourceOf(operation.key), 'utf8');
             }
             catch {
-                currentSource = '# generator';
+                currentSource = '# handler';
             }
         }
         const examples = opts.history.getSuccessful(operation.key, 2);
@@ -382,16 +407,19 @@ async function handle(req, res, opts) {
             await opts.cache.regenerate(operation, {
                 currentSource,
                 failingInput: input,
-                fault: outcome.fault ?? 'generator faulted',
+                fault: outcome.fault ?? 'handler faulted',
                 stderr: outcome.stderr,
                 examples,
             });
             cacheStatus = 'regenerated';
             res.setHeader('x-gym-cache', 'regenerated');
             opts.onRequest?.(formatRegenerated(urlKey, attempt, Date.now() - regenStarted, operation.operationId));
-            // Re-run the request with the newly regenerated generator
+            // Re-run the request with the newly regenerated handler
             outcome = await opts.box.run(operation.key, input);
-            if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
+            if (outcome.ok &&
+                outcome.status === undefined &&
+                responseValidator &&
+                !responseValidator(outcome.value)) {
                 outcome = {
                     ok: false,
                     fault: 'output does not match response schema after regeneration',
@@ -401,8 +429,8 @@ async function handle(req, res, opts) {
             }
         }
         catch (regenErr) {
-            if (regenErr instanceof SandboxUnavailable) {
-                await sandboxDown(regenErr, { requestBody: body, cacheStatus });
+            if (regenErr instanceof WorkerUnavailable) {
+                await workerDown(regenErr, { requestBody: body, cacheStatus });
                 return;
             }
             const detail = reason(regenErr);
@@ -430,7 +458,7 @@ async function handle(req, res, opts) {
         }
         if (!outcome.ok) {
             const bodyObj = {
-                error: `the regenerated generator for ${operation.operationId} ${outcome.fault}`,
+                error: `the regenerated handler for ${operation.operationId} ${outcome.fault}`,
                 stderr: outcome.stderr || undefined,
                 regenerated: true,
             };
@@ -441,13 +469,13 @@ async function handle(req, res, opts) {
                 pathParams,
                 requestBody: body,
                 errorKind,
-                errorMessage: `regenerated generator ${outcome.fault}`,
+                errorMessage: `regenerated handler ${outcome.fault}`,
                 stderr: outcome.stderr,
                 responseBody: bodyObj,
                 cacheStatus,
                 regenerated: true,
                 regenAttempts: attempt,
-                note: 'regenerated generator faulted',
+                note: 'regenerated handler faulted',
             });
             end();
             return;
@@ -457,6 +485,19 @@ async function handle(req, res, opts) {
     const streamKey = `${operation.key}:${req.socket.remoteAddress || 'local'}`;
     const cutResult = cut(operation, outcome.value, url.searchParams, body, opts.paginationLimiter, streamKey);
     opts.history.recordSuccess(operation.key, input, outcome.value);
+    if (!operation.success.schema) {
+        res.statusCode = operation.success.status;
+        await finish(operation.success.status, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            cacheStatus,
+            note: `${note} · no body declared`,
+        });
+        res.end();
+        return;
+    }
     const end = prepareSend(res, operation.success.status, outcome.value);
     await finish(operation.success.status, {
         operationId: operation.operationId,
@@ -471,7 +512,7 @@ async function handle(req, res, opts) {
     end();
 }
 /**
- * The generator on disk was written before the pagination rule existed, and a
+ * The handler on disk was written before the pagination rule existed, and a
  * cache is not rebuilt just because the rule changed. A body offering back the
  * token it was handed is therefore still possible, and it is the one bug here
  * that costs the client rather than the mock: it hangs.
@@ -497,7 +538,7 @@ function check(operation, checks, pathParams, query, body) {
     const compiled = checks.for(operation);
     const out = [];
     // Coercion rewrites what it is given, so the copies are validated and the
-    // originals are what reach the generator.
+    // originals are what reach the handler.
     if (!compiled.path({ ...pathParams })) {
         out.push(...issues('path', compiled.path.errors));
     }
@@ -552,9 +593,9 @@ async function readBody(req, max) {
     }
 }
 /**
- * Headers reach the generator so it can vary on things like `accept-language`.
- * Credentials do not: the envelope is written to a file inside a container, and
- * a mock is exactly what people point a real bearer token at by accident.
+ * Headers reach the handler so it can vary on things like `accept-language`.
+ * Credentials do not: the request can be quoted to the world agent, and a mock
+ * is exactly what people point a real bearer token at by accident.
  */
 function safeHeaders(req) {
     const out = {};

package/dist/setup.d.ts

@@ -2,8 +2,11 @@ import { KeyStore } from '@zenera/cli/lib';
 import { type Model } from '@zenera/neo';
 import { Box } from './box.ts';
 import { Cache, type CacheOptions } from './cache.ts';
+import { Catalog } from './catalog.ts';
+import { type Knowledge, type KnowledgeOptions } from './knowledge.ts';
 import { Router } from './router.ts';
 import { SpecError } from './spec.ts';
+import { World, type WorldEvent } from './synth.ts';
 import { Checks } from './validate.ts';
 /** The variable a shell or a CI job names it with — a zen ref. */
 export declare const MODEL_ENV = "ZENERA_GYM_MODEL";
@@ -16,26 +19,57 @@ export interface ModelChoice {
 export interface GymFile {
     version: 1;
     model?: string;
+    /** an embedding ref, or `none` */
+    embedding?: string;
 }
 export declare const readSettings: () => Promise<GymFile>;
 export declare function writeSettings(file: GymFile): void;
 /** What `open` would run, and where it came from, so a command can say so too. */
 export declare function chooseModel(flag: string | undefined, keys: KeyStore): Promise<ModelChoice | undefined>;
+/** The variable that names the embedding model, or `none`. */
+export declare const EMBEDDING_ENV = "ZENERA_GYM_EMBEDDING";
+export interface EmbeddingChoice {
+    /** undefined: no embedding, search by wording only */
+    ref?: string;
+    from: ModelSource | 'none';
+}
+/**
+ * Which model embeds the docs, if any. Off unless the flag asks: a ref names
+ * the model outright; `on` (or `default`) takes the configured one — the
+ * variable, then the stored setting, then the first keyed provider that offers
+ * one. The variable and the setting only answer that question; on their own
+ * they turn nothing on.
+ */
+export declare function chooseEmbedding(flag: string | undefined, keys: KeyStore): Promise<EmbeddingChoice>;
+/** The model `--embedding on` would use; `none` at a link means off. */
+export declare function configuredEmbedding(keys: KeyStore): Promise<EmbeddingChoice>;
 export interface SetupOptions {
-    specs: readonly string[];
+    /** API documents: files, directories or patterns */
+    schemas: readonly string[];
+    /** the story of the world: files, directories or patterns */
+    story?: readonly string[];
+    /** reference material: files, directories or patterns */
+    docs?: readonly string[];
     cwd: string;
-    /** where generators and the container's workspace live */
+    /** where handlers, worlds, indexes and reports live */
     cache?: string;
     model?: string;
-    image?: string;
+    /** an embedding ref, or `none` */
+    embedding?: string;
+    /** a world name, or a path to its file; derived from the story when unset */
+    world?: string;
+    /** start from an empty world */
+    reset?: boolean;
     attempts?: number;
-    /** how many generators may be written at once */
+    /** how many handlers may be written at once */
     concurrency?: number;
     rebuild?: boolean;
     ephemeral?: boolean;
     timeout?: number;
-    onImageBuild?: (tag: string) => void;
     events?: Pick<CacheOptions, 'onStart' | 'onAttempt' | 'onReady' | 'onFail'>;
+    onWorld?: (event: WorldEvent) => void;
+    onWarn?: (message: string) => void;
+    onIndexing?: KnowledgeOptions['onProgress'];
 }
 export interface Setup {
     router: Router;
@@ -44,7 +78,14 @@ export interface Setup {
     box: Box;
     model: Model;
     choice: ModelChoice;
-    image: string;
+    catalog: Catalog;
+    knowledge: Knowledge;
+    embedding: EmbeddingChoice;
+    /** the API documents served, absolute */
+    files: string[];
+    world: World;
+    /** the world's SQLite file */
+    worldFile: string;
     root: string;
     close(): Promise<void>;
 }