@volter/twin-standard 1.0.30 → 1.0.32

package/src/clients/xai.ts

@@ -0,0 +1,25 @@
+// xAI through openai-node (its OpenAI-compatible API): the shared chat cases, and a reasoning turn streamed through the
+// SDK's Responses stream, whose accumulator takes each reasoning summary part the stream adds.
+import type { ClientCase } from './harness.ts';
+import { chatCases, openaiClient } from './openai-compatible.ts';
+
+const XAI = { key: 'XAI_API_KEY', base: (host: string) => `https://${host}/v1`, model: 'grok-4.7' };
+
+export const cases: ClientCase[] = [
+  ...chatCases(XAI),
+  {
+    id: 'responses-reasoning-stream',
+    asks: "a reasoning turn streamed through the SDK's Responses stream completes with its reasoning item and its message",
+    source: 'https://developers.openai.com/api/reference/resources/responses/streaming-events "response.reasoning_summary_part.added"',
+    async run(c) {
+      c.scenario({ handlers: [{ id: 'reasons', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words', reasoning: 'thinking it through' } }] });
+      const client = await openaiClient(c, XAI);
+      try {
+        const stream = client.responses.stream({ model: XAI.model, input: 'hello', reasoning: { summary: 'auto' } } as never);
+        for await (const _event of stream) { /* the accumulator reads each */ }
+        const types = (await stream.finalResponse()).output.map((o) => o.type);
+        return types.includes('reasoning') && types.includes('message') ? [] : [`the streamed response's output is ${JSON.stringify(types)}`];
+      } catch (e) { return [`the SDK's Responses stream failed: ${(e as Error).message}`]; }
+    },
+  },
+];

package/src/conformance.ts

@@ -0,0 +1,446 @@
+import { hasOwnSurface } from './lanes.ts';
+// CONFORMANCE — the deterministic half of the Protocol 3 standard that executes the pack: the contract it serves, run the
+// way an application calls it, and every rule a pack's author follows that a machine can decide (docs/contributing/
+// architecture.md, "Conformance"). One command, the same for a contributor, the catalog's admission and its regular
+// re-assessment:
+//
+//   twin-standard conform <pack dir>
+//
+// It imports the pack (its manifest, fetch, index and server.ts) and the kernel the pack itself resolves, serves it on
+// its own from a scratch directory, and reads every unit (the pack and its lanes). The form is the gate's; what a model
+// judges (the life's plausibility) is the proof section's. Each check names the defect it was written against: one
+// that escaped review once fails here when reintroduced.
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { connect } from 'node:net';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, matchesGlob, relative, resolve } from 'node:path';
+import type { TwinStream } from '@volter/world-core';
+import { citations, sourceHeld, type SourceRecord } from './check-sources.ts';
+
+export type ConformanceResult = { id: string; asks: string; failures: string[]; note?: string };
+
+type Manifest = {
+  vendor?: string;
+  resources?: Record<string, { refresh?: { list?: string; detail?: string; get?: string; none?: string } }>;
+  sockets?: Array<{ id: string; path: string; host?: string }>;
+  rateBudget?: { windowMs: number; ceiling: number; burstCeiling?: number; defaultWeight: number; rules?: Array<{ weight: number }>; reason?: string; allowance?: { perMinute: number; source: string } };
+  vendorBacked?: { none?: string };
+  events?: unknown;
+  ingest?: unknown;
+};
+
+const pascal = (s: string): string => s.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0]!.toUpperCase() + w.slice(1)).join('');
+const readJson = (p: string): unknown => (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). */
+function unitsIn(pack: string): string[] {
+  return [pack, ...readdirSync(pack).sort().map((n) => join(pack, n)).filter((d) => !existsSync(join(d, 'package.json')) && existsSync(join(d, 'src', 'manifest.ts')))];
+}
+const nameOf = (pack: string, unit: string): string => relative(resolve(pack, '..'), unit);
+
+/** The files conformance reads from a unit: its manifest, its spec's record, its vendor's life and its decision table
+ *  (a lane's journeys are its own `journeys/` or else its vendor's). A release publishes each (published()), and a
+ *  pack's standing counts it in the form only when every unit holds them (twin-world's scripts/pack-standing.ts, by
+ *  unitFilesMissing): the one list of both. */
+export const UNIT_FILES = ['src/manifest.ts', 'spec/SOURCE.md', 'journeys/customer-life.json', 'journeys/decisions.json'] as const;
+
+/** The published package must carry every conformance input its units hold, including lanes. */
+export function unpublishedUnitFiles(unit: string): string[] {
+  const vendor = existsSync(join(unit, 'package.json')) ? unit : dirname(unit);
+  const pkg = readJson(join(vendor, 'package.json')) as { files?: string[] } | undefined;
+  if (pkg?.files === undefined) return []; // npm's default includes the tree
+  const patterns = pkg.files.map((entry) => ({ exclude: entry.startsWith('!'), pattern: entry.replace(/^!/, '').replace(/^\.\//, '').replace(/\/+$/, '') }));
+  return UNIT_FILES.filter((f) => existsSync(join(unit, f))).map((f) => relative(vendor, join(unit, f)).replaceAll('\\', '/')).filter((f) => {
+    const matches = (pattern: string): boolean => matchesGlob(f, pattern) || matchesGlob(f, `${pattern}/**`);
+    return !patterns.some((p) => !p.exclude && matches(p.pattern)) || patterns.some((p) => p.exclude && matches(p.pattern));
+  }).map((f) => `${f} is absent from package.json files (conformance reads it)`);
+}
+
+/** Each of UNIT_FILES a unit lacks where conformance reads it: the manifest of every unit, the life at its vendor's root
+ *  (lifeServed), the spec's record and the decision table of a unit with a spec (decided()). */
+export function unitFilesMissing(unit: string): string[] {
+  const vendor = existsSync(join(unit, 'package.json')) ? unit : dirname(unit);
+  const spec = hasOwnSurface(unit);
+  const at: Record<(typeof UNIT_FILES)[number], string | undefined> = {
+    'src/manifest.ts': unit,
+    'spec/SOURCE.md': spec ? unit : undefined,
+    'journeys/customer-life.json': vendor,
+    'journeys/decisions.json': spec ? (existsSync(join(unit, 'journeys')) ? unit : vendor) : undefined,
+  };
+  return UNIT_FILES.filter((f) => at[f] !== undefined && !existsSync(join(at[f]!, f))).map((f) => `${relative(unit, join(at[f]!, f))} is missing (conformance reads it)`);
+}
+/** A unit's fetch export: a pack's `create<Vendor>Fetch`, a lane's `create<Lane>LaneFetch`. */
+const fetchName = (dir: string): string => (existsSync(join(dir, 'package.json')) ? `create${pascal(basename(dir))}Fetch` : `create${pascal(basename(dir))}LaneFetch`);
+const manifestOf = async (unit: string): Promise<Manifest> => ((await import(join(unit, 'src', 'manifest.ts'))) as { manifest: Manifest }).manifest;
+
+type Owners = Record<string, string>;
+type Decision = { operation: string; mechanism: string; demand?: string; lane?: string };
+
+/** The decision table read against one unit of a vendor (its own API, `''`, or a lane by name), each unit against its
+ *  own owners (a fetch's `ownersByUnit()`): a row decides the operation of the lane it names; a row naming none decides
+ *  the vendor's own API's operation of that id, or, when its own API has none, the one lane's that has it. So an id two
+ *  units share is two decisions, and a lane's operation its root serves stays the lane's gap (Clerk's Backend and
+ *  Frontend APIs both name `ListOrganizationMemberships`). A demanded operation (journeys/demand.json, the vendor's
+ *  backend calls) is the unit's a row naming no lane would decide. */
+export function decisionTableProblems(unit: string, byUnit: Record<string, Owners>, decisions: Decision[], demanded: string[] = [], doors: string[] = []): string[] {
+  const owners = { ...(byUnit[unit] ?? {}), ...Object.fromEntries(doors.map((id) => [`door:${id}`, 'door'])) };
+  const holders = (id: string): string[] => Object.keys(byUnit).filter((u) => id in byUnit[u]!);
+  const unnamedUnit = (id: string): string | undefined => (id in (byUnit[''] ?? {}) ? '' : holders(id).length === 1 ? holders(id)[0] : undefined);
+  const decides = (d: Decision): string | undefined => (d.lane !== undefined ? d.lane : d.operation.startsWith('door:') && doors.includes(d.operation.slice(5)) ? unit : unnamedUnit(d.operation));
+  const mine = decisions.filter((d) => decides(d) === unit);
+  const decision = new Map(mine.map((d) => [d.operation, d]));
+  const out: string[] = [];
+  for (const [id, o] of Object.entries(owners).filter(([, o]) => o !== 'gap')) {
+    const d = decision.get(id);
+    if (!d) out.push(`${id} is served (${o}) and not in the decision table${holders(id).length > 1 ? ` (an id ${holders(id).map((u) => u || 'the root').join(' and ')} share: its row names "lane": "${unit}")` : ''}`);
+    else if (d.mechanism !== o) out.push(`${id} is decided ${d.mechanism} and served by ${o}`);
+    else if (!d.demand) out.push(`${id}'s decision names no demand`);
+  }
+  for (const d of mine) {
+    if (!(d.operation in owners)) out.push(`${d.operation} is decided for ${unit || 'the root'}, which has no such operation`);
+    else if (owners[d.operation] === 'gap' && d.mechanism !== 'unmodeled') out.push(`${d.operation} is decided ${d.mechanism} and served by nothing`);
+  }
+  for (const op of demanded) if (op && unnamedUnit(op) === unit && owners[op] === 'gap') out.push(`${op} is demanded (journeys/demand.json) and served by nothing`);
+  return out;
+}
+
+/** Every operation a unit serves is decided, every operation demanded or refreshed is served (create-pack --index's
+ *  table, as the catalog reads it), each unit against its own operations. Escaped once: refresh scopes naming
+ *  operations the pack answered with the gap (discord, polar, github, elevenlabs, cloudflare), so a World rooted at a
+ *  second World's twin read nothing; and a root's handler counted as its lane's, hiding four Clerk Frontend API gaps. */
+async function decided(pack: string): Promise<string[]> {
+  const out: string[] = [];
+  const makeOf = async (unit: string) => ((await import(join(unit, 'src', 'fetch.ts'))) as Record<string, unknown>)[fetchName(unit)] as (() => { owners?: () => Owners; ownersByUnit?: () => Record<string, Owners> }) | undefined;
+  const root = (await makeOf(pack))?.();
+  // a kernel with no ownersByUnit names each unit's owners from the unit's own fetch, each unit read on its own
+  const byUnit: Record<string, Owners> | undefined = root?.ownersByUnit?.();
+  for (const unit of unitsIn(pack).filter(hasOwnSurface)) {
+    const name = nameOf(pack, unit);
+    const key = unit === pack ? '' : basename(unit);
+    const journeys = existsSync(join(unit, 'journeys')) ? join(unit, 'journeys') : join(unit, '..', 'journeys');
+    const owners = byUnit ? byUnit[key] ?? {} : (await makeOf(unit))?.().owners?.();
+    if (!owners) { out.push(`${name}: its fetch (${fetchName(unit)}) names no owners() to check the decision table against`); continue; }
+    const table = readJson(join(journeys, 'decisions.json')) as { decisions?: Decision[] } | undefined;
+    if (!table) { out.push(`${name}: journeys/decisions.json is missing`); continue; }
+    const demand = readJson(join(journeys, 'demand.json')) as { applications?: Array<{ backend?: Array<{ operation?: string }> }> } | undefined;
+    const demanded = (demand?.applications ?? []).flatMap((a) => a.backend ?? []).flatMap((b) => String(b.operation ?? '').split(/;\s*/));
+    out.push(...decisionTableProblems(key, byUnit ?? { [key]: owners }, table.decisions ?? [], demanded, ((await manifestOf(unit)) as { doors?: Array<{ id: string }> }).doors?.map((d) => d.id) ?? []).map((p) => `${name}: ${p}`));
+    for (const [resource, decl] of Object.entries((await manifestOf(unit)).resources ?? {})) {
+      for (const id of [decl.refresh?.list ?? decl.refresh?.get, decl.refresh?.detail]) {
+        // a refresh reads one of its own unit's operations: one the unit lacks (a typo, another lane's) is read nowhere
+        if (id && owners[id] === undefined) out.push(`${name}: ${resource}'s refresh reads ${id}, which is no operation of ${name}`);
+        else if (id && owners[id] === 'gap') out.push(`${name}: ${resource}'s refresh reads ${id}, which nothing serves`);
+      }
+    }
+  }
+  return out;
+}
+
+/** Every vendor-backed unit, the pack or a lane, reaches the registered pack's state system: its perform, asked to send
+ *  one of the unit's operations (to an executor that stops it before anything is sent), finds the unit; and a unit
+ *  that declares a refresh has one. Escaped once: the kernel's root packOf dropped the lanes beside a pack's own API, so
+ *  PlanetScale's and Clerk's lanes derived no perform and no refresh. */
+async function registered(pack: string, runtime: Runtime): Promise<string[]> {
+  const backed: Array<{ unit: string; lane?: string; op?: string; refreshed: boolean }> = [];
+  for (const unit of unitsIn(pack)) {
+    const m = await manifestOf(unit);
+    const resources = Object.values(m.resources ?? {});
+    if (m.vendorBacked?.none || !resources.length) continue;
+    const op = (readJson(join(unit, 'src', 'generated', 'surface.gen.json')) as { operations?: Array<{ id: string }> } | undefined)?.operations?.[0]?.id;
+    backed.push({ unit: nameOf(pack, unit), ...(unit === pack ? {} : { lane: basename(unit) }), ...(op ? { op } : {}), refreshed: resources.some((r) => r.refresh?.list || r.refresh?.get) });
+  }
+  if (!backed.length) return [];
+  await import(join(pack, 'src', 'index.ts'));
+  const vendor = (await manifestOf(pack)).vendor ?? basename(pack);
+  const system = runtime.getPack(vendor)?.stateSystem as { perform?: (execute: unknown, group: unknown[], ctx: unknown) => Promise<unknown>; refresh?: unknown } | undefined;
+  if (!system?.perform) return [`${backed.map((b) => b.unit).join(', ')} ${backed.length === 1 ? 'is' : 'are'} vendor-backed, and the registered ${vendor} pack has no ${system ? 'perform' : 'state system'} (its index passes every lane to packOf)`];
+  const out: string[] = [];
+  if (backed.some((b) => b.refreshed) && !system.refresh) out.push(`the registered ${vendor} pack has no refresh, and ${backed.filter((b) => b.refreshed).map((b) => b.unit).join(', ')} declare one`);
+  const REACHED = 'conformance: the unit was reached';
+  for (const b of backed.filter((x) => x.op)) {
+    // a lane is asked by its name alone, with an operation no unit has: only the lane itself can be found (a dropped lane
+    // would otherwise be found through another unit holding the same operation id)
+    const input = b.lane ? { operationId: '__conformance_probe__', lane: b.lane, path: {}, query: {} } : { operationId: b.op, path: {}, query: {} };
+    const why = await system.perform(() => { throw new Error(REACHED); }, [{ id: 'conformance', input }], { resolve: (_t: string, v: string) => v }).then(() => REACHED, (e: Error) => e.message);
+    if (/records no operation of the vendor's surface/.test(why)) out.push(`${b.unit}: the registered ${vendor} pack's perform does not know it (${b.op}): its index passes every lane to packOf`);
+  }
+  return out;
+}
+
+/** What a release publishes holds every unit as the checkout does: each unit's manifest, its vendored spec and its
+ *  journeys, read from the file list `npm pack` makes. Escaped once: seven packs published their lanes' src without
+ *  their spec, so the catalog's conformance of the tarball never read those lanes. */
+function published(pack: string): string[] {
+  const run = spawnSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], { cwd: pack, encoding: 'utf8' });
+  let files: Set<string>;
+  try { files = new Set(((JSON.parse(run.stdout) as Array<{ files: Array<{ path: string }> }>)[0]?.files ?? []).map((f) => f.path)); } catch { return [`npm pack lists no files (${String(run.stderr).trim().split('\n').at(-1) ?? ''})`]; }
+  const out: string[] = [];
+  for (const unit of unitsIn(pack)) {
+    const at = relative(pack, unit);
+    const of = (p: string): string => (at ? `${at}/${p}` : p);
+    for (const need of UNIT_FILES) {
+      if (existsSync(join(unit, need)) && !files.has(of(need))) out.push(`${nameOf(pack, unit)}: ${of(need)} is not published (package.json's files)`);
+    }
+  }
+  return out;
+}
+
+/** Every vendor fact cited (a handler's or a manifest's `// source:`, a patch's source) is recorded in spec/sources.json
+ *  as a page that answered, with each quoted line found on it: check-sources' record, read, never fetched again. */
+async function cited(pack: string): Promise<string[]> {
+  const out: string[] = [];
+  for (const unit of unitsIn(pack).filter(hasOwnSurface)) {
+    const record = (readJson(join(unit, 'spec', 'sources.json')) ?? {}) as Record<string, SourceRecord>;
+    for (const [url, quotes] of await citations(unit)) {
+      const r = record[url];
+      if (!r) { out.push(`${nameOf(pack, unit)}: ${url} is cited and not recorded (bun <twin-world>/scripts/check-sources.ts ${nameOf(pack, unit)})`); continue; }
+      if (!sourceHeld(url, r)) out.push(`${nameOf(pack, unit)}: ${url} did not answer with verified evidence when checked`);
+      for (const q of quotes) if (r.quotes?.[q] !== true) out.push(`${nameOf(pack, unit)}: "${q.slice(0, 80)}" is not on ${url}`);
+    }
+  }
+  return out;
+}
+
+/** Every stored resource of a vendor-backed unit says how a World rooted at the vendor reads it back: a list, a get, or
+ *  none with why (architecture, "The real-system adapters"). A lane's events are ingested by its own declaration or by
+ *  the one its vendor declares for all its lanes ("What a pack declares": `ingest` on the VendorManifest). */
+async function refreshDeclared(pack: string): Promise<string[]> {
+  const out: string[] = [];
+  const vendorIngest = (await manifestOf(pack)).ingest;
+  for (const unit of unitsIn(pack)) {
+    const m = await manifestOf(unit);
+    if (m.vendorBacked?.none) continue;
+    // a `_` resource is the pack's own bookkeeping, never the vendor's
+    for (const [name, r] of Object.entries(m.resources ?? {})) if (!name.startsWith('_') && !r.refresh) out.push(`${nameOf(pack, unit)}: ${name} declares no refresh (a list, a get, or none with why)`);
+    if (m.events && !m.ingest && !vendorIngest) out.push(`${nameOf(pack, unit)}: it sends events and declares no ingest of the vendor's`);
+  }
+  return out;
+}
+
+/** A budget more permissive than the fallback rests on the vendor's documented allowance, cited (rate-budget-check). */
+async function allowance(pack: string, runtime: Runtime): Promise<string[]> {
+  const out: string[] = [];
+  const perMinute = (d: NonNullable<Manifest['rateBudget']>): number => (d.windowMs <= 60_000 ? d.ceiling * (60_000 / d.windowMs) : (d.burstCeiling ?? d.ceiling)) / Math.min(d.defaultWeight, ...(d.rules ?? []).map((r) => r.weight));
+  const fallback = perMinute(runtime.DEFAULT_RATE_BUDGET);
+  for (const unit of unitsIn(pack)) {
+    const d = (await manifestOf(unit)).rateBudget;
+    if (!d) continue;
+    const name = nameOf(pack, unit);
+    if (d.windowMs < runtime.DEFAULT_RATE_BUDGET.windowMs) out.push(`${name}: its window (${d.windowMs} ms) is shorter than the fallback's`);
+    const admits = perMinute(d);
+    if (admits <= fallback) continue;
+    if (!d.allowance) { out.push(`${name}: admits ${admits} calls a minute, more than the fallback's ${fallback}, and declares no documented allowance`); continue; }
+    if (admits > d.allowance.perMinute) out.push(`${name}: admits ${admits} calls a minute, more than the documented ${d.allowance.perMinute}`);
+    // the page's own words state the number: a quote with a figure in it (`cited` finds it on the page)
+    const quotes = [...readFileSync(join(unit, 'src', 'manifest.ts'), 'utf8').matchAll(/\/\/ source: (\S+) "([^"]*)"/g)].filter((m) => m[1] === d.allowance!.source).map((m) => m[2]!);
+    if (!quotes.length) out.push(`${name}: its allowance's page (${d.allowance.source}) is cited on no // source: line of its manifest with the words it says`);
+    else if (!quotes.some((q) => /\d/.test(q))) out.push(`${name}: no quote of its allowance's page (${d.allowance.source}) states a number`);
+  }
+  return out;
+}
+
+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
+ *  its manifests declare takes an upgrade. Escaped twice: serveHttp never took the upgrade a pack's fetch carries, then
+ *  read it off the boot probe's wrapper of the fetch, so OpenAI Realtime's /v1/realtime answered 404, first everywhere
+ *  and then only in a World, while every walk (which drives the fetch directly) passed. */
+async function standalone(pack: string): Promise<string[]> {
+  const out: string[] = [];
+  const sockets: Array<{ unit: string; path: string; host?: string }> = [];
+  for (const unit of unitsIn(pack)) for (const s of (await manifestOf(unit)).sockets ?? []) sockets.push({ unit: nameOf(pack, unit), path: s.path, ...(s.host ? { host: s.host } : {}) });
+  // served the way a World runs it: the boot id set, so the seam wraps the fetch with the World's boot probe
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
+  const before = env.VOLTER_WORLD_BOOT_ID;
+  env.VOLTER_WORLD_BOOT_ID = 'conformance';
+  let server: Served;
+  try { server = await serve(pack, {}); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
+  try {
+    const http = await within(5000, fetch(`http://127.0.0.1:${(server.inspectPort ?? server.port)}/`).then((r) => r.status, (e: Error) => e.message));
+    if (http === 'timeout' || typeof http === 'string') out.push(`served as a World runs it, it answers no HTTP request (${http})`);
+    const boot = await within(5000, fetch(`http://127.0.0.1:${(server.inspectPort ?? server.port)}/__volter/world-boot`).then((r) => r.json() as Promise<{ boot?: string }>, (): { boot?: string } => ({})));
+    if (boot === 'timeout' || boot.boot !== 'conformance') out.push("served as a World runs it, it does not answer the World's boot probe (/__volter/world-boot)");
+    for (const s of sockets) {
+      const upgraded = await new Promise<string | undefined>((done) => {
+        const ws = new WebSocket(`ws://127.0.0.1:${server.port}${s.path}`, { headers: s.host ? { host: s.host } : {} } as unknown as string[]);
+        const timer = setTimeout(() => { ws.close(); done('no upgrade in 5 s'); }, 5000);
+        ws.onopen = () => { clearTimeout(timer); ws.close(); done(undefined); };
+        ws.onerror = () => { clearTimeout(timer); done('the upgrade was refused'); };
+      });
+      if (upgraded) out.push(`${s.unit}: the socket at ${s.host ?? ''}${s.path}: ${upgraded}`);
+    }
+  } finally { server.stop(); }
+  return out;
+}
+
+/** A line protocol's connection over TCP, in the walk's stream shape. A line drew its replies when bytes arrived and then
+ *  50 ms passed with no more (a multi-line reply arrives in pieces), or when 500 ms passed with none (a line that draws no
+ *  reply: a message's body before its end); 10 s bounds a server that keeps writing. The windows are timing, not protocol:
+ *  a reply slower than 500 ms is read with the next line's. */
+function lineConnection(port: number): TwinStream {
+  return (sink) => {
+    const socket = connect(port, '127.0.0.1');
+    let heard = 0;
+    socket.on('data', (bytes: Uint8Array) => { heard = Date.now(); sink.write(bytes); });
+    socket.on('close', () => sink.end());
+    socket.on('error', () => socket.destroy());
+    const opened = new Promise<void>((resolveOpen) => { socket.once('connect', () => resolveOpen()); socket.once('error', () => resolveOpen()); });
+    return {
+      data: (chunk) => { void opened.then(() => socket.write(chunk)); },
+      settled: async () => {
+        await opened;
+        const start = Date.now(); const since = heard;
+        while (Date.now() - start < 10_000) {
+          await new Promise((r) => setTimeout(r, 10));
+          if (socket.destroyed) return;
+          if (heard > since ? Date.now() - heard >= 50 : Date.now() - start >= 500) return;
+        }
+      },
+      close: () => socket.destroy(),
+    };
+  };
+}
+
+/** The life walked as an application calls the pack: its server.ts served as a World runs it (boot id set, the World's
+ *  root and the life's scenario its options), every step over HTTP with the vendor's host, every check of the walk held
+ *  (status, expectations, captures, SHAPE, LEAK over answers, events and frames). Slack's events once carried the
+ *  kernel's updatedAt; a request the served pack does not answer in 10 s fails its step. */
+async function lifeServed(pack: string): Promise<string[]> {
+  const lifePath = join(pack, 'journeys', 'customer-life.json');
+  if (!existsSync(lifePath)) return ['journeys/customer-life.json is missing'];
+  const { inMemoryWorld, usePacks, walk } = await import('./walk/behavior-journey.ts');
+  usePacks(dirname(pack));
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
+  const served = async (root: string, options: { scenarioPath?: string }) => {
+    const before = env.VOLTER_WORLD_BOOT_ID;
+    env.VOLTER_WORLD_BOOT_ID = 'conformance';
+    let server: Served;
+    try { server = await serve(pack, { root, ...options }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
+    const port = server.inspectPort ?? server.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> => {
+        const url = new URL(request.url);
+        const headers = new Headers(request.headers);
+        headers.set('host', url.host);
+        const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+        const answer = await within(10_000, fetch(`http://127.0.0.1:${port}${url.pathname}${url.search}`, { method: request.method, headers, redirect: 'manual', ...(body ? { body } : {}) }));
+        return answer === 'timeout' ? new Response(`no answer in 10 s from the served pack (${request.method} ${url.pathname})`, { status: 599 }) : answer;
+      },
+      // 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)
+      stream: lineConnection(server.port),
+      stop: () => server.stop(),
+    };
+  };
+  const world = inMemoryWorld(`conform-${basename(pack)}`);
+  const failures: Array<{ step: string; beat: string; detail: string }> = [];
+  try {
+    await walk(JSON.parse(readFileSync(lifePath, 'utf8')), world.root(), failures, { beats: true, served });
+  } finally { world.restore(); }
+  return failures.slice(0, 30).map((f) => `${f.beat} ${f.step}: ${f.detail}`.slice(0, 300)).concat(failures.length > 30 ? [`… ${failures.length - 30} more`] : []);
+}
+
+/** The pack driven by the vendor's own client (clients/<vendor>.ts): served as a World runs it, its credentials issued
+ *  by its credential door, the cases run in Node as an application runs the vendor's SDK (clients/run.ts), each the
+ *  vendor's documented behaviour. A vendor whose descriptor names npm clients and has no cases fails it, unless the
+ *  descriptor's clientCasesNone says why none is owed. */
+async function clientCases(pack: string, scratch: string): Promise<{ failures: string[]; note?: string }> {
+  const vendor = (await manifestOf(pack)).vendor ?? basename(pack);
+  if (!existsSync(join(import.meta.dir, 'clients', `${vendor}.ts`))) {
+    // a vendor whose descriptor names npm clients (adoption.sdks) is held to them: no case is no proof the SDK works,
+    // unless the descriptor says why none is owed (clientCasesNone: no official SDK, or none the demand's applications
+    // use); one an application calls with no SDK of the vendor's (a raw HTTP catalog) has no client to drive
+    const descriptor = ((await manifestOf(pack)) as { descriptor?: { adoption?: { sdks?: string[] }; clientCasesNone?: string } }).descriptor;
+    const sdks = descriptor?.adoption?.sdks ?? [];
+    if (descriptor?.clientCasesNone) return { failures: [], note: `${vendor} owes no client case: ${descriptor.clientCasesNone}` };
+    return sdks.length
+      ? { failures: [`${vendor} names npm clients (${sdks.join(', ')}) and has no client cases: add packages/twin-standard/src/clients/${vendor}.ts, the SDK driving the pack as an application does, or the descriptor's clientCasesNone saying why none is owed`] }
+      : { failures: [], note: `${vendor} declares no SDK of its own` };
+  }
+  const descriptor = ((await manifestOf(pack)) as { descriptor?: { hosts?: Array<{ host?: string; suffix?: string }>; credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> } } }).descriptor;
+  // the first host that names one: a descriptor may lead with a suffix (a region's hosts under one domain), which no
+  // request addresses; the case's client reaches whatever host its issued credentials name
+  const host = descriptor?.hosts?.find((h) => h.host)?.host;
+  if (!host) return { failures: ['the descriptor names no host for its client to address'] };
+  const scenarioPath = join(scratch, 'client-scenario.json');
+  writeFileSync(scenarioPath, '{"handlers":[]}');
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
+  const before = env.VOLTER_WORLD_BOOT_ID;
+  env.VOLTER_WORLD_BOOT_ID = 'conformance';
+  let server: Served;
+  try { server = await serve(pack, { root: join(scratch, 'client-world'), scenarioPath }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
+  try {
+    // the World's credentials: what the pack's credential door issues, by the variable a World sets each in
+    const issued: Record<string, string> = {};
+    const door = descriptor?.credentialDoor;
+    if (door) {
+      const answer = (await (await fetch(`http://127.0.0.1:${server.port}${door.path}`, { method: 'POST', headers: { host, 'content-type': 'application/json' }, body: JSON.stringify(door.body) })).json().catch(() => ({}))) as Record<string, unknown>;
+      for (const [name, field] of Object.entries(door.fill)) if (answer[field] !== undefined) issued[name] = String(answer[field]);
+    }
+    const job = join(scratch, 'client-job.json');
+    writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioPath }));
+    // Node, as an application runs its SDK (asynchronous: this process serves the pack meanwhile)
+    const out = await new Promise<string>((resolve) => {
+      const child = spawn('node', ['--experimental-strip-types', '--no-warnings', join(import.meta.dir, 'clients', 'run.ts'), job], { stdio: ['ignore', 'pipe', 'pipe'] });
+      let text = '';
+      let errors = '';
+      child.stdout.on('data', (d: Buffer) => { text += d; });
+      child.stderr.on('data', (d: Buffer) => { errors += d; });
+      const timer = setTimeout(() => child.kill(), 300_000);
+      child.on('close', (code) => { clearTimeout(timer); resolve(code === 0 ? text : `${text}\n${JSON.stringify({ id: 'runner', asks: 'the cases run', failures: [`node exited ${code}: ${errors.trim().split('\n').slice(-2).join(' ')}`] })}`); });
+    });
+    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(); }
+}
+
+/** Every check over the pack at `dir`, in order. */
+export async function conformance(dir: string): Promise<ConformanceResult[]> {
+  const pack = resolve(dir);
+  if (!existsSync(join(pack, 'package.json'))) throw new Error(`${dir} is no pack (no package.json): conformance takes a pack's directory`);
+  // the kernel the pack itself resolves: one registry, one serve seam, the pack's own
+  const runtime = (await import(createRequire(join(pack, 'package.json')).resolve('@volter/world-core/runtime'))) as Runtime;
+  const scratch = mkdtempSync(join(tmpdir(), 'conformance-'));
+  const here = process.cwd();
+  process.chdir(scratch);
+  const run = async (id: string, asks: string, check: () => Promise<string[]> | string[]): Promise<ConformanceResult> => {
+    try { return { id, asks, failures: await check() }; } catch (error) { return { id, asks, failures: [`the check could not run: ${(error as Error).message.split('\n')[0]}`] }; }
+  };
+  try {
+    return [
+      await run('decided', 'every served operation is decided with its demand; every demanded and every refreshed operation is served', () => decided(pack)),
+      await run('published', 'what a release publishes holds every unit: its manifest, its spec and its journeys', () => published(pack)),
+      await run('cited', 'every vendor fact cited is recorded as a page that answered, each quote found on it', () => cited(pack)),
+      await run('refresh', 'every stored resource of a vendor-backed unit declares how it is read back, and a unit that sends events ingests the vendor\'s', () => refreshDeclared(pack)),
+      await run('registered', 'a vendor-backed unit, lane or not, reaches the registered pack\'s state system', () => registered(pack, runtime)),
+      await run('allowance', 'a rate budget above the fallback rests on the vendor\'s documented allowance, cited in its manifest', () => allowance(pack, runtime)),
+      await (async (): Promise<ConformanceResult> => {
+        const asks = "driven by the vendor's own client (its official SDK), served as a World runs it, the vendor's documented behaviour holds";
+        try { const r = await clientCases(pack, scratch); return { id: 'client', asks, failures: r.failures, ...(r.note ? { note: r.note } : {}) }; } catch (error) { return { id: 'client', asks, failures: [`the check could not run: ${(error as Error).message.split('\n')[0]}`] }; }
+      })(),
+      await run('life', 'the life walked over HTTP against the pack served as a World runs it, with its scenario: every check held', () => lifeServed(pack)),
+      await run('standalone', 'served by its server.ts as a World runs it, the pack answers HTTP and the boot probe, and each declared socket upgrades', () => standalone(pack)),
+    ];
+  } finally {
+    process.chdir(here);
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}