@volter/twin-standard 1.0.82 → 1.0.84

package/dist/src/clients/openai.js

@@ -1,9 +1,10 @@
 import { chatCases } from "./openai-compatible.js";
 const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
 const REALTIME = 'https://developers.openai.com/api/reference/resources/realtime/server-events';
+const API = 'https://api.openai.com/v1';
 async function client(c) {
     const { default: OpenAI } = await import('openai');
-    return new OpenAI({ apiKey: c.env.OPENAI_API_KEY ?? '', baseURL: `https://${c.host}/v1`, fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+    return new OpenAI({ apiKey: c.env.OPENAI_API_KEY ?? '', baseURL: API, fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
 }
 const TOOLS = [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
 // a turn that calls the tool wherever one is offered, and one that answers in words
@@ -37,7 +38,7 @@ async function realtimeTurn(c, toolChoice) {
     });
 }
 export const cases = [
-    ...chatCases({ key: 'OPENAI_API_KEY', base: (host) => `https://${host}/v1`, model: 'gpt-4o' }),
+    ...chatCases({ key: 'OPENAI_API_KEY', base: () => API, model: 'gpt-4o' }),
     {
         id: 'realtime-connects',
         asks: 'a Realtime connection opens and its first event is session.created',

package/dist/src/conformance.js

@@ -27,6 +27,7 @@ import { basename, dirname, extname, join, matchesGlob, relative, resolve } from
 import { citations, sourceHeld } from "./check-sources.js";
 import { fileURLToPath } from 'node:url';
 import { servedHttpFetch } from "./clients/harness.js";
+import { servePack as serve } from "./walk/serve-pack.js";
 const pascal = (s) => s.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
 const readJson = (p) => (existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : undefined);
 /** The pack's units: the pack and each lane in it (a directory with its own src/manifest.ts and no package.json). */
@@ -268,15 +269,6 @@ async function allowance(pack, runtime) {
     }
     return out;
 }
-/** The pack served on its own, as a World's process or an application's test serves it: its server.ts, from a scratch
- *  working directory (a server keeps its World under it), with the options given. */
-async function serve(pack, options) {
-    const mod = (await import(__rewriteRelativeImportExtension(join(pack, 'src', 'server.ts'))));
-    const create = Object.entries(mod).find(([k, v]) => /^create\w+TwinServer$/.test(k) && typeof v === 'function')?.[1];
-    if (!create)
-        throw new Error('src/server.ts exports no create<Vendor>TwinServer');
-    return create({ port: 0, ...options });
-}
 const within = (ms, p) => Promise.race([p, new Promise((r) => setTimeout(() => r('timeout'), ms))]);
 /** Served by its server.ts as a World runs it (its boot id set), the pack answers HTTP and the boot probe, and every socket
  *  its manifests declare takes an upgrade. Escaped twice: serveHttp never took the upgrade a pack's fetch carries, then
@@ -321,7 +313,7 @@ async function standalone(pack) {
         }
     }
     finally {
-        server.stop();
+        await server.stop();
     }
     return out;
 }
@@ -383,7 +375,8 @@ async function lifeServed(pack) {
         const http = servedHttpFetch(port);
         return {
             // the vendor's URL as the application called it, sent to the served pack: its host carried in the Host header
-            fetch: async (request) => {
+            fetch: Object.assign(async (request) => {
+                await server.managedDatabaseUrl?.();
                 const abort = new AbortController();
                 try {
                     const answer = await within(10_000, http(request, { signal: abort.signal }));
@@ -392,7 +385,7 @@ async function lifeServed(pack) {
                 finally {
                     abort.abort();
                 }
-            },
+            }, server.managedDatabaseUrl ? { managedDatabaseUrl: server.managedDatabaseUrl } : {}),
             // a socket opened as an application opens it: a WebSocket to the served port, the vendor's host in its Host header
             socket: (url, headers) => new WebSocket(`ws://127.0.0.1:${port}${url}`, { headers }),
             // a line connection opened as an application's client opens it: TCP to the protocol listener (the primary port)
@@ -477,7 +470,7 @@ async function clientCases(pack, scratch) {
         return { failures: results.flatMap((r) => r.failures.map((f) => `${r.id} (${r.asks}): ${f}`)), note: `${results.length} case(s) through the vendor's client` };
     }
     finally {
-        server.stop();
+        await server.stop();
     }
 }
 /** Every check over the pack at `dir`, in order. */

package/dist/src/walk/behavior-journey.js

@@ -1174,11 +1174,15 @@ export async function walk(journey, root, collect, opts) {
         await Promise.allSettled([...pending.values()].map((request) => request.answer));
         setDeliveryObserver(previousObserver);
         setInProcessTwins(previousTwins);
-        await served?.stop();
-        if (sqlSession)
-            await sqlSession.then((session) => session.end(), () => { });
-        // a World's managed database ends with its walk (vendor-fetch.ts), so the next World declares it at the same port
-        await twin.stopDatabase?.();
+        try {
+            if (sqlSession)
+                await sqlSession.then((session) => session.end(), () => { });
+        }
+        finally {
+            await served?.stop();
+            // a World's managed database ends with its walk (vendor-fetch.ts), so the next World declares it at the same port
+            await twin.stopDatabase?.();
+        }
         if (clockFile && startedAt !== undefined)
             store.write(clockFile, startedAt);
     }

package/dist/src/walk/serve-pack.d.ts

@@ -0,0 +1,7 @@
+export type ServedPack = {
+    port: number;
+    inspectPort?: number;
+    stop: () => void | Promise<void>;
+    managedDatabaseUrl?: () => Promise<string>;
+};
+export declare function servePack(pack: string, options: Record<string, unknown>): Promise<ServedPack>;

package/dist/src/walk/serve-pack.js

@@ -0,0 +1,39 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// The standard serves a pack with its declared backing, as the runtime binds it in a World.
+import { join } from 'node:path';
+import { worldNow } from '@volter/world-core/runtime';
+import { startPgliteHost } from "./walk-database.js";
+export async function servePack(pack, options) {
+    const mod = await import(__rewriteRelativeImportExtension(join(pack, 'src', 'server.ts')));
+    const create = Object.entries(mod).find(([name, value]) => /^create\w+TwinServer$/.test(name) && typeof value === 'function')?.[1];
+    if (!create)
+        throw new Error('src/server.ts exports no create<Vendor>TwinServer');
+    const descriptor = (await import(__rewriteRelativeImportExtension(join(pack, 'src', 'index.ts')))).pack;
+    let database;
+    if (descriptor?.managedDatabase?.kind === 'postgres' && options.database === undefined)
+        database = await startPgliteHost();
+    let server;
+    try {
+        server = await create({ port: 0, ...options, ...(database ? { database: database.url } : {}) });
+    }
+    catch (error) {
+        await database?.stop();
+        throw error;
+    }
+    if (!database)
+        return server;
+    const backing = database;
+    let stopping;
+    return {
+        ...server,
+        managedDatabaseUrl: async () => { backing.clock(worldNow()); return backing.url; },
+        stop: () => stopping ??= (async () => { await server.stop(); await backing.stop(); })(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.82",
+  "version": "1.0.84",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.90",
+    "@volter/world-core": "3.0.92",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/clients/openai.ts

@@ -5,10 +5,11 @@ import { chatCases } from './openai-compatible.ts';
 
 const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
 const REALTIME = 'https://developers.openai.com/api/reference/resources/realtime/server-events';
+const API = 'https://api.openai.com/v1';
 
 async function client(c: ClientContext) {
   const { default: OpenAI } = await import('openai');
-  return new OpenAI({ apiKey: c.env.OPENAI_API_KEY ?? '', baseURL: `https://${c.host}/v1`, fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+  return new OpenAI({ apiKey: c.env.OPENAI_API_KEY ?? '', baseURL: API, fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
 }
 const TOOLS = [{ type: 'function' as const, function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
 // a turn that calls the tool wherever one is offered, and one that answers in words
@@ -40,7 +41,7 @@ async function realtimeTurn(c: ClientContext, toolChoice: 'auto' | 'none'): Prom
 }
 
 export const cases: ClientCase[] = [
-  ...chatCases({ key: 'OPENAI_API_KEY', base: (host) => `https://${host}/v1`, model: 'gpt-4o' }),
+  ...chatCases({ key: 'OPENAI_API_KEY', base: () => API, model: 'gpt-4o' }),
   {
     id: 'realtime-connects',
     asks: 'a Realtime connection opens and its first event is session.created',

package/src/conformance.ts

@@ -20,6 +20,7 @@ import type { TwinStream } from '@volter/world-core';
 import { citations, sourceHeld, type SourceRecord } from './check-sources.ts';
 import { fileURLToPath } from 'node:url';
 import { servedHttpFetch } from './clients/harness.ts';
+import { servePack as serve, type ServedPack as Served } from './walk/serve-pack.ts';
 
 export type ConformanceResult = { id: string; asks: string; failures: string[]; note?: string };
 
@@ -247,16 +248,6 @@ type Runtime = {
   getPack: (vendor: string) => { stateSystem?: { perform?: unknown; refresh?: unknown } } | undefined;
   DEFAULT_RATE_BUDGET: NonNullable<Manifest['rateBudget']>;
 };
-type Served = { port: number; inspectPort?: number; stop: () => void };
-
-/** The pack served on its own, as a World's process or an application's test serves it: its server.ts, from a scratch
- *  working directory (a server keeps its World under it), with the options given. */
-async function serve(pack: string, options: Record<string, unknown>): Promise<Served> {
-  const mod = (await import(join(pack, 'src', 'server.ts'))) as Record<string, unknown>;
-  const create = Object.entries(mod).find(([k, v]) => /^create\w+TwinServer$/.test(k) && typeof v === 'function')?.[1] as ((o: Record<string, unknown>) => Promise<Served>) | undefined;
-  if (!create) throw new Error('src/server.ts exports no create<Vendor>TwinServer');
-  return create({ port: 0, ...options });
-}
 const within = <T>(ms: number, p: Promise<T>): Promise<T | 'timeout'> => Promise.race([p, new Promise<'timeout'>((r) => setTimeout(() => r('timeout'), ms))]);
 
 /** Served by its server.ts as a World runs it (its boot id set), the pack answers HTTP and the boot probe, and every socket
@@ -287,7 +278,7 @@ async function standalone(pack: string): Promise<string[]> {
       });
       if (upgraded) out.push(`${s.unit}: the socket at ${s.host ?? ''}${s.path}: ${upgraded}`);
     }
-  } finally { server.stop(); }
+  } finally { await server.stop(); }
   return out;
 }
 
@@ -338,13 +329,14 @@ async function lifeServed(pack: string): Promise<string[]> {
     const http = servedHttpFetch(port);
     return {
       // the vendor's URL as the application called it, sent to the served pack: its host carried in the Host header
-      fetch: async (request: Request): Promise<Response> => {
+      fetch: Object.assign(async (request: Request): Promise<Response> => {
+        await server.managedDatabaseUrl?.();
         const abort = new AbortController();
         try {
           const answer = await within(10_000, http(request, { signal: abort.signal }));
           return answer === 'timeout' ? new Response(`no answer in 10 s from the served pack (${request.method} ${new URL(request.url).pathname})`, { status: 599 }) : answer;
         } finally { abort.abort(); }
-      },
+      }, server.managedDatabaseUrl ? { managedDatabaseUrl: server.managedDatabaseUrl } : {}),
       // a socket opened as an application opens it: a WebSocket to the served port, the vendor's host in its Host header
       socket: (url: string, headers: Record<string, string>) => new WebSocket(`ws://127.0.0.1:${port}${url}`, { headers } as unknown as string[]),
       // a line connection opened as an application's client opens it: TCP to the protocol listener (the primary port)
@@ -413,7 +405,7 @@ async function clientCases(pack: string, scratch: string): Promise<{ failures: s
     });
     const results = out.split('\n').filter((l) => l.startsWith('{')).map((l) => JSON.parse(l) as { id: string; asks: string; failures: string[] });
     return { failures: results.flatMap((r) => r.failures.map((f) => `${r.id} (${r.asks}): ${f}`)), note: `${results.length} case(s) through the vendor's client` };
-  } finally { server.stop(); }
+  } finally { await server.stop(); }
 }
 
 /** Every check over the pack at `dir`, in order. */

package/src/walk/behavior-journey.ts

@@ -819,10 +819,13 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     await Promise.allSettled([...pending.values()].map((request) => request.answer));
     setDeliveryObserver(previousObserver);
     setInProcessTwins(previousTwins);
-    await served?.stop();
-    if (sqlSession) await sqlSession.then((session) => session.end(), () => {});
-    // a World's managed database ends with its walk (vendor-fetch.ts), so the next World declares it at the same port
-    await (twin as { stopDatabase?: () => Promise<void> }).stopDatabase?.();
+    try {
+      if (sqlSession) await sqlSession.then((session) => session.end(), () => {});
+    } finally {
+      await served?.stop();
+      // a World's managed database ends with its walk (vendor-fetch.ts), so the next World declares it at the same port
+      await (twin as { stopDatabase?: () => Promise<void> }).stopDatabase?.();
+    }
     if (clockFile && startedAt !== undefined) store.write(clockFile, startedAt);
   }
 }

package/src/walk/serve-pack.ts

@@ -0,0 +1,31 @@
+// The standard serves a pack with its declared backing, as the runtime binds it in a World.
+import { join } from 'node:path';
+import { worldNow } from '@volter/world-core/runtime';
+import { startPgliteHost, type PgliteHost } from './walk-database.ts';
+
+export type ServedPack = {
+  port: number;
+  inspectPort?: number;
+  stop: () => void | Promise<void>;
+  managedDatabaseUrl?: () => Promise<string>;
+};
+
+export async function servePack(pack: string, options: Record<string, unknown>): Promise<ServedPack> {
+  const mod = await import(join(pack, 'src', 'server.ts')) as Record<string, unknown>;
+  const create = Object.entries(mod).find(([name, value]) => /^create\w+TwinServer$/.test(name) && typeof value === 'function')?.[1] as ((options: Record<string, unknown>) => Promise<ServedPack>) | undefined;
+  if (!create) throw new Error('src/server.ts exports no create<Vendor>TwinServer');
+  const descriptor = (await import(join(pack, 'src', 'index.ts'))).pack as { managedDatabase?: { kind: string } } | undefined;
+  let database: PgliteHost | undefined;
+  if (descriptor?.managedDatabase?.kind === 'postgres' && options.database === undefined) database = await startPgliteHost();
+  let server: ServedPack;
+  try { server = await create({ port: 0, ...options, ...(database ? { database: database.url } : {}) }); }
+  catch (error) { await database?.stop(); throw error; }
+  if (!database) return server;
+  const backing = database;
+  let stopping: Promise<void> | undefined;
+  return {
+    ...server,
+    managedDatabaseUrl: async () => { backing.clock(worldNow()); return backing.url; },
+    stop: () => stopping ??= (async () => { await server.stop(); await backing.stop(); })(),
+  };
+}