@volter/twin-standard 1.0.149 → 1.0.151

package/src/clients/x.ts

@@ -0,0 +1,66 @@
+// twitter-api-v2 1.29, unmodified (one of the SDKs the x descriptor's adoption names),
+// with an OAuth 2.0 user access token made at the pack's doors for an account made there, as a person's sign-in at
+// x.com and an App's authorize leg make them. The client sends through node's https with the agent it is given, so the
+// World's routed agent is its httpAgent.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const CREATE = 'https://docs.x.com/x-api/posts/create-post';
+const ME = 'https://docs.x.com/x-api/users/get-my-user';
+const README = 'https://www.npmjs.com/package/twitter-api-v2/v/1.29.1';
+
+/** An account named `username` and an access token for it with `scopes`; the client on that token. */
+async function signedIn(c: ClientContext, username: string, scopes: string[], token = `case-${username}-token`) {
+  const door = async (path: string, body: unknown) => {
+    const answer = await c.fetch(`https://${c.host}${path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    if (answer.status >= 300) throw new Error(`${path} answered ${answer.status}`);
+    return ((await answer.json()) as { data: Record<string, string> }).data;
+  };
+  const account = await door('/_twin/accounts', { username, name: 'Case Account' });
+  await door('/_twin/tokens', { token, account_id: account.id, scopes });
+  const { TwitterApi } = await import('twitter-api-v2');
+  return { client: new TwitterApi(token, { httpAgent: c.agent }), account };
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'post-and-read-back',
+    asks: "a post made through the SDK answers its id and text, and reads back by id with that text, its author the signed-in account",
+    source: `${CREATE} "Create Posts"`,
+    async run(c) {
+      const { client, account } = await signedIn(c, 'case_poster', ['tweet.read', 'tweet.write', 'users.read']);
+      const made = await client.v2.tweet('Shipping the case today');
+      const failures: string[] = [];
+      if (!made.data?.id || made.data.text !== 'Shipping the case today') failures.push(`tweet answered ${JSON.stringify(made)}`);
+      const read = await client.v2.singleTweet(made.data.id, { 'tweet.fields': ['author_id'] });
+      if (read.data?.text !== 'Shipping the case today') failures.push(`the post reads back text ${JSON.stringify(read.data?.text)}`);
+      if (read.data?.author_id !== account.id) failures.push(`the post reads back author ${String(read.data?.author_id)}, not ${account.id}`);
+      return failures;
+    },
+  },
+  {
+    id: 'me-is-the-signed-in-account',
+    asks: "v2.me answers the account the token was issued to, by its id and username (an app's account check after sign-in)",
+    source: `${ME} "Get Users Me"`,
+    async run(c) {
+      const { client, account } = await signedIn(c, 'case_me', ['tweet.read', 'users.read']);
+      const me = await client.v2.me();
+      return me.data?.id === account.id && me.data.username === 'case_me' ? [] : [`me answered ${JSON.stringify(me)}`];
+    },
+  },
+  {
+    id: 'unknown-token-api-response-error',
+    asks: 'a token X never issued is refused, and the client throws its ApiResponseError carrying the 401',
+    source: `${README} "Typed errors, meaningful error messages, error enumerations for both v1.1 and v2"`,
+    async run(c) {
+      const { TwitterApi, ApiResponseError } = await import('twitter-api-v2');
+      const client = new TwitterApi('case-never-issued-token', { httpAgent: c.agent });
+      try {
+        await client.v2.me();
+        return ['the never-issued token was accepted'];
+      } catch (error) {
+        if (!(error instanceof ApiResponseError)) return [`the refusal is not an ApiResponseError: ${String(error).slice(0, 160)}`];
+        return error.code === 401 ? [] : [`the refusal's code is ${error.code}, not 401`];
+      }
+    },
+  },
+];

package/src/conformance.ts

@@ -317,6 +317,131 @@ async function standalone(pack: string): Promise<string[]> {
   return out;
 }
 
+type SweptOperation = {
+  id: string; method: string; path: string; basePath?: string; pathParams?: string[];
+  query?: Array<{ name: string; type?: string; required?: boolean }>; body?: Array<{ name: string; required?: boolean }>;
+  bodyEncoding?: string; headers?: Record<string, string | null>; discriminator?: Record<string, string | null>;
+  responseMedia?: Record<string, string[]>; answers?: unknown;
+};
+
+/** The request an application's first call of an operation sends when it knows nothing yet: every path parameter, every
+ *  required query parameter and every header the operation is routed by holding a placeholder, its discriminator's
+ *  values, and an empty body in the operation's encoding. What it measures is the twin's answer to a call it did not
+ *  script: a refusal in the vendor's form, or a result in the vendor's shape, and never a crash, a hang or a row. */
+function sweepRequest(op: SweptOperation, basePath: string, host: string, credential: Record<string, string>): Request {
+  const fill = (name: string, type?: string): string => (type === 'integer' || type === 'number' ? '1' : type === 'boolean' ? 'true' : `conformance-${name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`);
+  const path = `${op.basePath ?? basePath}${op.path}`.replace(/\{([^}+]+)\+?\}/g, (_m, name: string) => fill(name));
+  const url = new URL(`https://${host}${path}`);
+  for (const q of op.query ?? []) if (q.required) url.searchParams.set(q.name, fill(q.name, q.type));
+  for (const [name, value] of Object.entries(op.discriminator ?? {})) url.searchParams.set(name, value ?? fill(name));
+  const headers = new Headers(credential);
+  for (const [name, value] of Object.entries(op.headers ?? {})) headers.set(name, value ?? fill(name));
+  const method = op.method.toUpperCase();
+  let body: string | undefined;
+  if (op.bodyEncoding === 'form') { headers.set('content-type', 'application/x-www-form-urlencoded'); body = ''; }
+  else if (op.bodyEncoding === 'xml') { headers.set('content-type', 'application/xml'); body = ''; }
+  else if (op.bodyEncoding === 'json' || op.bodyEncoding === 'multipart') { headers.set('content-type', 'application/json'); body = '{}'; }
+  return new Request(url, { method, headers, ...(body !== undefined && !['GET', 'HEAD'].includes(method) ? { body } : {}) });
+}
+
+/** Every operation the pack serves, called over HTTP as an application calls it, against its server.ts served as a World
+ *  runs it: once plainly and once with a scenario loaded (an empty one, as a World that scripts nothing loads it). Each
+ *  answers within 10 s, never with a 500 the spec does not declare, never with a field of the twin's own (`_`
+ *  bookkeeping, the kernel's `updatedAt`) and, answered successfully, in the shape the spec gives the operation; and every
+ *  refresh list a fresh account can read (one with no parameter in its path) answers it successfully, so a World rooted
+ *  at this twin reads its resources back. Escaped before: the scenario hang (a served pack given a scenario answered
+ *  nothing), leaked kernel fields in answers no life step read, and refresh scopes on operations the pack answered with
+ *  the gap. The life walks what a customer does; this calls what the pack declares it serves. */
+async function surfaceSwept(pack: string, scratch: string): Promise<{ failures: string[]; note: string }> {
+  const out: string[] = [];
+  const descriptor = ((await manifestOf(pack)) as { descriptor?: { hosts?: Array<{ host?: string }>; credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> } } }).descriptor;
+  const fetchOf = ((await import(join(pack, 'src', 'fetch.ts'))) as Record<string, unknown>)[fetchName(pack)] as (() => { owners?: () => Owners; ownersByUnit?: () => Record<string, Owners> }) | undefined;
+  const root = fetchOf?.();
+  const byUnit = root?.ownersByUnit?.() ?? { '': root?.owners?.() ?? {} };
+  const { shapeChecker } = await import('./walk/shape.ts');
+  const { leaked } = await import('./walk/behavior-journey.ts');
+  const shape = await shapeChecker(pack);
+  type Unit = { name: string; host: string; basePath: string; ops: SweptOperation[]; refreshLists: Array<{ resource: string; id: string }>; auth?: { header: string; scheme: string } };
+  const units: Unit[] = [];
+  const vendorFields = new Set<string>();
+  for (const unit of unitsIn(pack).filter(hasOwnSurface)) {
+    const surface = readJson(join(unit, 'src', 'generated', 'surface.gen.json')) as { format?: string; basePath?: string; operations?: SweptOperation[]; resources?: Array<{ fields: Array<{ name: string }> }> } | undefined;
+    for (const r of surface?.resources ?? []) for (const f of r.fields) vendorFields.add(f.name);
+    // a line protocol and a command table ride in no path of their own: the life's line steps and the examples read them
+    if (!surface?.operations || ['command-reply', 'command-table'].includes(String(surface.format))) continue;
+    const m = (await manifestOf(unit)) as Manifest & { hosts?: Array<{ host?: string }>; auth?: { header: string; scheme: string } };
+    const host = m.hosts?.find((h) => h.host)?.host ?? descriptor?.hosts?.find((h) => h.host)?.host;
+    if (!host) { out.push(`${nameOf(pack, unit)}: no host is named (its manifest's hosts or the descriptor's) for an application to call it at`); continue; }
+    const owners = byUnit[unit === pack ? '' : basename(unit)] ?? {};
+    const refreshLists = Object.entries(m.resources ?? {}).flatMap(([resource, decl]) => (decl.refresh?.list ? [{ resource, id: decl.refresh.list }] : []));
+    units.push({ name: nameOf(pack, unit), host, basePath: surface.basePath ?? '', ops: surface.operations.filter((o) => owners[o.id] !== undefined && owners[o.id] !== 'gap'), refreshLists, ...(m.auth ? { auth: m.auth } : {}) });
+  }
+  if (!units.length) return { failures: out, note: 'no unit serves an operation on a path of its own' };
+  const tally = { calls: 0, ok: 0, refused: 0 };
+  const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
+  const scenarioPath = join(scratch, 'surface-scenario.json');
+  writeFileSync(scenarioPath, '{"handlers":[]}');
+  for (const mode of ['plain', 'scenario'] as const) {
+    const before = env.VOLTER_WORLD_BOOT_ID;
+    env.VOLTER_WORLD_BOOT_ID = 'conformance';
+    let server: Served;
+    try { server = await serve(pack, { root: join(scratch, `surface-${mode}`), ...(mode === 'scenario' ? { scenarioPath } : {}) }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
+    const http = servedHttpFetch(server.inspectPort ?? server.port);
+    const send = async (request: Request): Promise<Response | 'timeout' | Error> => {
+      await server.managedDatabaseUrl?.();
+      const abort = new AbortController();
+      try { return await within(10_000, http(request, { signal: abort.signal })); } catch (error) { return error as Error; } finally { abort.abort(); }
+    };
+    try {
+      // the account an application holds: the key the credential door issues, sent as the vendor reads its credential
+      let issued: string | undefined;
+      if (descriptor?.credentialDoor) {
+        const door = descriptor.credentialDoor;
+        const answer = await send(new Request(`https://${descriptor.hosts?.find((h) => h.host)?.host ?? units[0]!.host}${door.path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(door.body) }));
+        const fields = answer instanceof Response ? ((await answer.json().catch(() => ({}))) as Record<string, unknown>) : {};
+        issued = Object.values(door.fill).map((f) => fields[f]).find((v): v is string => typeof v === 'string');
+      }
+      const said = mode === 'scenario' ? ' with a scenario loaded' : '';
+      for (const u of units) {
+        // a unit whose manifest declares no `auth` checks its key in its own front: the key goes as most vendors read
+        // one, a bearer token, and a refusal of it is no finding of the refresh below
+        const auth = u.auth ?? { header: 'authorization', scheme: 'Bearer' };
+        const credential: Record<string, string> = issued ? { [auth.header]: auth.scheme ? `${auth.scheme} ${issued}` : issued } : {};
+        const answered = new Map<string, number>();
+        for (const op of u.ops) {
+          const request = sweepRequest(op, u.basePath, u.host, credential);
+          const where = `${u.name}: ${op.id} (${request.method} ${new URL(request.url).pathname})`;
+          const res = await send(request);
+          if (res === 'timeout') { out.push(`${where} answered nothing in 10 s${said}`); continue; }
+          if (res instanceof Error) { out.push(`${where}: the connection failed${said} (${res.message})`); continue; }
+          answered.set(op.id, res.status);
+          if (mode === 'plain') { tally.calls++; if (res.status < 300) tally.ok++; else tally.refused++; }
+          const text = await res.text();
+          if (res.status === 500 && !op.responseMedia?.['500'] && !op.responseMedia?.['5XX']) { out.push(`${where} answered 500${said}, which the spec does not declare: ${text.slice(0, 160)}`); continue; }
+          if (mode === 'scenario') continue;
+          const type = res.headers.get('content-type') ?? '';
+          let body: unknown;
+          if (/json/.test(type)) { try { body = JSON.parse(text); } catch { body = undefined; } }
+          for (const key of leaked(body, vendorFields, '', !op.answers || res.status >= 300)) out.push(`${where} answers the twin's own field ${key}`);
+          if (res.status >= 200 && res.status < 300 && shape) {
+            const hit = shape.operationOf(request.method, request.url, Object.fromEntries(request.headers));
+            if (hit) for (const detail of shape.failures(hit.op, body, type, request.headers.get('accept') ?? undefined, res.status, { method: request.method, responseText: text })) out.push(`${where}: ${detail}`);
+          }
+        }
+        if (mode === 'plain') for (const r of u.refreshLists) {
+          const op = u.ops.find((o) => o.id === r.id);
+          if (!op || op.path.includes('{') || (op.basePath ?? '').includes('{')) continue;
+          const status = answered.get(r.id);
+          if (status !== undefined && (status === 401 || status === 403) && (!u.auth || !issued)) continue;
+          if (status !== undefined && (status < 200 || status >= 300)) out.push(`${u.name}: ${r.resource}'s refresh lists by ${r.id}, which answered a fresh account ${status}: a World rooted at this twin reads nothing back`);
+        }
+      }
+    } finally { await server.stop(); }
+  }
+  // one defect repeated over a surface reads as one: the first 40 findings, and how many more
+  return { failures: out.length > 40 ? [...out.slice(0, 40), `… ${out.length - 40} more`] : out, note: `${tally.calls} served operations called, twice each: ${tally.ok} answered successfully, ${tally.refused} refused, unscripted` };
+}
+
 /** 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:
@@ -376,7 +501,9 @@ async function lifeServed(pack: string): Promise<string[]> {
       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(),
+      // bounded: Bun's server.stop(true) never settles once a WebSocket peer has closed under it (discord's life, Bun
+      // 1.3.11: the walk ended and the stop spun at full CPU for 45 minutes), so the check waits 5 s and goes on
+      stop: async () => { await within(5000, Promise.resolve(server.stop())); },
     };
   };
   const world = inMemoryWorld(`conform-${basename(pack)}`);
@@ -406,10 +533,12 @@ async function clientCases(pack: string, scratch: string): Promise<{ failures: s
       ? { 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;
+  const descriptor = ((await manifestOf(pack)) as { descriptor?: { hosts?: Array<{ host?: string; suffix?: string }>; hostsNone?: 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;
+  // a raw protocol's pack (hostsNone: SMTP, whose relay is whatever host the operator names) is reached by its TCP
+  // connection alone; its client names a stand-in host the connection never resolves
+  const host = descriptor?.hosts?.find((h) => h.host)?.host ?? (descriptor?.hostsNone ? 'relay.world.test' : undefined);
   if (!host) return { failures: ['the descriptor names no host for its client to address'] };
   const scenarioPath = join(scratch, 'client-scenario.json');
   writeFileSync(scenarioPath, '{"handlers":[]}');
@@ -423,11 +552,27 @@ async function clientCases(pack: string, scratch: string): Promise<{ failures: s
     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>;
+      // a door that answers nothing is the pack's failure, never conform's hang (a pack served with a scenario that answered
+      // nothing once held this request open for good)
+      const abort = new AbortController();
+      const asked = await within(10_000, fetch(`http://127.0.0.1:${server.port}${door.path}`, { method: 'POST', headers: { host, 'content-type': 'application/json' }, body: JSON.stringify(door.body), signal: abort.signal }).then((r) => r.json().catch(() => ({}))));
+      abort.abort();
+      if (asked === 'timeout') return { failures: [`the credential door (POST ${door.path}) answered nothing in 10 s, served with a scenario loaded`] };
+      const answer = asked 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, packFacts: join(pack, 'generated', 'pack-facts.json') }));
+    // a release carries its facts (generated/pack-facts.json, `twin-standard facts`); a source checkout does not, so its
+    // facts are compiled here, as that command compiles them, for the client the case runs
+    let packFacts = join(pack, 'generated', 'pack-facts.json');
+    if (!existsSync(packFacts)) {
+      const { compilePackFacts, renderPackFacts } = await import('./pack-facts.ts');
+      const compiled = await compilePackFacts([{ vendor, dir: pack }]);
+      if (compiled.undeclared.length) throw new Error('Pack descriptor is missing');
+      packFacts = join(scratch, 'pack-facts.json');
+      writeFileSync(packFacts, renderPackFacts(compiled));
+    }
+    writeFileSync(job, JSON.stringify({ vendor, port: server.port, host, env: issued, scenarioPath, packFacts, ...(descriptor?.hostsNone ? { raw: true } : {}) }));
     // 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(clients, `run${extension}`), job], { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -444,8 +589,42 @@ async function clientCases(pack: string, scratch: string): Promise<{ failures: s
   } finally { await server.stop(); }
 }
 
+/** The gate over every unit of the pack: the form section of the grade, which holds the rules an author's code keeps
+ *  (p3-rules.ts: ids from ctx.mint, the twin's URL from ctx.publicBase, the kernel's crypto, bytes in ctx.blobs, secrets
+ *  drawn from ctx.secret) and the pack layout, handler, kernel and manifest contracts. A contributor's conform is the
+ *  whole of what a machine decides of the pack, as the catalog's admission reads it. */
+async function formOf(pack: string): Promise<string[]> {
+  const { p3Gate } = await import('./gate.ts');
+  return (await p3Gate(unitsIn(pack))).flatMap((r) => r.failures.map((f) => `${nameOf(pack, r.unit)}: ${f}`));
+}
+
+/** The pack's records hold what a reviewer reads them for: each demand row cites the application's line it was read at
+ *  (`<path>:<line>`, or `<package>@<version>:<path>:<line>` for a call a dependency makes), the spec's record names a
+ *  vendored file that is there, the life names the session that wrote it (what makes a judge's verdict independent),
+ *  and the package says what it serves in a README. Rules every builder brief carried by hand, decided here. */
+function records(pack: string): string[] {
+  const out: string[] = [];
+  if (!existsSync(join(pack, 'README.md'))) out.push('README.md is missing: the package says what it serves, for whom, its doors and what it leaves out');
+  const life = readJson(join(pack, 'journeys', 'customer-life.json')) as { author?: unknown } | undefined;
+  if (life && (typeof life.author !== 'string' || !life.author.trim())) out.push('journeys/customer-life.json names no author (the session that wrote it), so no verdict on it can be shown independent');
+  for (const unit of unitsIn(pack)) {
+    const name = nameOf(pack, unit);
+    const journeys = hasJourneySource(unit) ? join(unit, 'journeys') : join(unit, '..', 'journeys');
+    const demand = unit === pack || hasJourneySource(unit) ? readJson(join(journeys, 'demand.json')) as { applications?: Array<{ name?: string; backend?: Array<{ operation?: string; evidence?: unknown }> }> } | undefined : undefined;
+    for (const app of demand?.applications ?? []) for (const row of app.backend ?? []) {
+      if (typeof row.evidence !== 'string' || !/:\d+/.test(row.evidence)) out.push(`${name}: ${app.name ?? 'an application'}'s call of ${row.operation ?? '(no operation)'} cites no line it was read at (evidence "<path>:<line>")`);
+    }
+    if (!hasOwnSurface(unit)) continue;
+    const source = existsSync(join(unit, 'spec', 'SOURCE.md')) ? readFileSync(join(unit, 'spec', 'SOURCE.md'), 'utf8') : '';
+    const file = /\*\*File:\*\*[^`\n]*`([^`]+)`/.exec(source)?.[1];
+    if (file && !existsSync(join(unit, 'spec', file))) out.push(`${name}: spec/SOURCE.md names ${file} as the vendored spec, and spec/ holds no such file`);
+  }
+  return out;
+}
+
 /** Every check over the pack at `dir`, in order. */
-export async function conformance(dir: string): Promise<ConformanceResult[]> {
+/** `onCheck` hears each check's id as it starts, so a caller can show where a long run stands. */
+export async function conformance(dir: string, options: { onCheck?: (id: string) => void } = {}): 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
@@ -453,8 +632,9 @@ export async function conformance(dir: string): Promise<ConformanceResult[]> {
   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]}`] }; }
+  const run = async (id: string, asks: string, check: () => Promise<string[] | { failures: string[]; note: string }> | string[]): Promise<ConformanceResult> => {
+    options.onCheck?.(id);
+    try { const r = await check(); return Array.isArray(r) ? { id, asks, failures: r } : { id, asks, failures: r.failures, note: r.note }; } catch (error) { return { id, asks, failures: [`the check could not run: ${(error as Error).message.split('\n')[0]}`] }; }
   };
   try {
     return [
@@ -465,11 +645,15 @@ export async function conformance(dir: string): Promise<ConformanceResult[]> {
       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> => {
+        options.onCheck?.('client');
         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)),
+      await run('surface', 'every served operation called over HTTP as an application calls it, plainly and with a scenario loaded: answered within 10 s, no undeclared 500, no field of the twin\'s own, a success in the spec\'s shape, and every refresh list a fresh account reads answering', () => surfaceSwept(pack, scratch)),
+      await run('records', 'each demand row cites the line it was read at, the spec\'s record names a vendored file that is there, the life names its author, the package has its README', () => records(pack)),
+      await run('form', 'every unit passes the form section of the grade (the gate): the layout, the handler and kernel contracts, the manifest as data, the rules an author\'s code holds', () => formOf(pack)),
     ];
   } finally {
     process.chdir(here);

package/src/consumer.ts

@@ -181,7 +181,11 @@ export async function runConsumerWorkflow(packDir: string, options: ConsumerOpti
       if (JSON.stringify(before) !== JSON.stringify(resumed)) throw new Error('Resume changed recorded application state before readback');
       await run('retained-readback', ['run', '--', ...recipe.retention.readback]);
       const after = JSON.parse(await run('log-after-readback', ['log', '--json']));
-      if (JSON.stringify(before) !== JSON.stringify(after)) throw new Error('Retained readback added mutations; it must only inspect existing state');
+      // the readback adds no write of the application's: what it adds may only be the vendor's own moves (a key's
+      // last-used time, recorded by the vendor as a request uses it: actor `system`, ctx.asVendor), never an API call's
+      const added = (after as Array<{ id?: string; actor?: { kind?: string } }>).filter((entry) => !(before as Array<{ id?: string }>).some((prior) => prior.id === entry.id));
+      const kept = (before as Array<{ id?: string }>).every((prior) => (after as Array<{ id?: string }>).some((entry) => JSON.stringify(entry) === JSON.stringify(prior)));
+      if (!kept || added.some((entry) => entry.actor?.kind !== 'system')) throw new Error('Retained readback added mutations; it must only inspect existing state');
       retainedReadback = true;
     }
   } catch (error) { failures.push((error as Error).message); }

package/src/create-pack.ts

@@ -150,6 +150,9 @@ export function packFetchFile(dir: string, name: string): string {
   const hasLive = existsSync(join(semantics, 'live.ts'));
   // a GraphQL API beside the REST one: its resolvers and the vendor's schema (graphql-wire.ts)
   const hasGraphql = existsSync(join(semantics, 'graphql.ts')) && existsSync(join(dir, 'src', 'generated', 'graphql-sdl.gen.json'));
+  // a stream whose documents are BSON (the MongoDB wire): the pack's own bson library, resolved from the pack as graphql's is
+  const packageJson = existsSync(join(dir, 'package.json')) ? (parseExactJson(readFileSync(join(dir, 'package.json'), 'utf8')) as { dependencies?: Record<string, string> }) : {};
+  const hasBson = existsSync(join(dir, 'src', 'stream.ts')) && packageJson.dependencies?.bson !== undefined;
   const screensDir = join(dir, 'src', 'screens');
   const screens = existsSync(screensDir) ? readdirSync(screensDir).filter((n) => /\.tsx?$/.test(n) && !/\.(test|uitest)\.tsx?$/.test(n) && !/^shared\.tsx?$/.test(n)).sort() : [];
   const id = (file: string): string => file.replace(/\.tsx?$/, '');
@@ -195,6 +198,7 @@ export function packFetchFile(dir: string, name: string): string {
     ...screens.map((f) => `import { screen as ${identifier(`screen_${id(f)}`)} } from './screens/${f}';`),
     ...laneImports,
     '',
+    ...(hasBson ? ["/** The pack's BSON library, resolved from the pack as graphql's loader is (architecture, the MongoDB wire). */", "export const loadBson = (): Promise<unknown> => import('bson');", ''] : []),
     `export function ${name}(options: PackFetchOptions = {}): DerivedFetch {`,
     '  return createPackFetch({',
     '    manifest,',
@@ -502,6 +506,26 @@ export function laneInitFiles(vendor: string, lanes: string[]): Record<string, s
   return files;
 }
 
+/** A unit's fixed files as the manifest and the spec make them now (architecture, "Creating a pack"): a lane's fetch, and
+ *  a pack's fetch, index, server and cli. A pack with a wire of its own (`src/stream.ts`, SMTP's and Redis's byte-stream
+ *  door) writes its server and cli itself: they carry its listener beside the fetch, so they are not fixed. `--index`
+ *  writes these and the grade's `fixed-reproducible` compares them byte for byte. */
+export async function fixedFiles(dir: string): Promise<Record<string, string>> {
+  const files: Record<string, string> = { 'src/fetch.ts': packFetchFile(dir, fetchName(dir)) };
+  if (!existsSync(join(dir, 'package.json'))) return files;
+  const { manifest } = await import(join(dir, 'src', 'manifest.ts')) as { manifest?: { vendor?: string } };
+  const vendor = manifest?.vendor;
+  if (!vendor || !/^[a-z][a-z0-9-]*$/.test(vendor)) throw new Error('Pack manifest must declare its vendor identity independently of the npm package name');
+  files['src/index.ts'] = packIndexFile(dir, vendor);
+  if (!existsSync(join(dir, 'src', 'stream.ts'))) {
+    // a unit whose spec is a proto (derive-pack generated its schema) is served over gRPC: its serve seam in that form
+    const lanesOnly = !hasOwnSurface(dir) && readdirSync(dir).some((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
+    files['src/server.ts'] = serverFile(vendor, !lanesOnly && existsSync(join(dir, 'src', 'generated', 'proto.gen.json')));
+    files['src/cli.ts'] = cliFile(vendor);
+  }
+  return files;
+}
+
 export async function createPack(args: string[]): Promise<void> {
   const [unit, ...rest] = args;
   if (!unit || (!rest.includes('--index') && !rest.includes('--brief') && !rest.includes('--init'))) {
@@ -562,9 +586,9 @@ export async function createPack(args: string[]): Promise<void> {
     }
     const path = join(dir, 'src', 'semantics', 'index.ts');
     if (!lanesOnly) { writeFileSync(path, handlerIndex(dir)); console.log(`create-pack: wrote ${path}`); }
-    // the fetch, again: a door file, the clock or a screen may have been added since
-    writeFileSync(join(dir, 'src', 'fetch.ts'), packFetchFile(dir, fetchName(dir)));
-    console.log(`create-pack: wrote ${join(dir, 'src', 'fetch.ts')}`);
+    // the fixed files, again: a door file, the clock, a screen, a lane or a proto may have been added since, and a pack
+    // made by an earlier create-pack takes the current form
+    for (const [rel, text] of Object.entries(await fixedFiles(dir))) { writeFileSync(join(dir, rel), text); console.log(`create-pack: wrote ${join(dir, rel)}`); }
     // a pack's own index (a lane's is the vendor's to name): the descriptor with what the kernel derives from the surface
     if (existsSync(join(dir, 'package.json'))) {
       const { manifest } = await import(join(dir, 'src', 'manifest.ts')) as { manifest?: { vendor?: string; descriptor?: { transport?: string } } };

package/src/protocol-3.ts

@@ -283,6 +283,18 @@ const criteria: Criterion[] = [
       return changed.length ? fail(`derive-pack writes differently: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ` and ${changed.length - 5} more` : ''}`) : pass(`${filesUnder(gen).length} files reproduced`);
     },
   },
+  {
+    id: 'fixed-reproducible', section: 'form',
+    asks: 'create-pack regenerates the fixed files (fetch, and a pack\'s index, server and cli) byte for byte',
+    async check(unit) {
+      // loaded when graded: create-pack reads this module's handler names, so a static import would be a cycle
+      const { fixedFiles } = await import('./create-pack.ts');
+      let want: Record<string, string>;
+      try { want = await fixedFiles(unit.dir); } catch (error) { return fail(`create-pack cannot write the fixed files: ${error instanceof Error ? error.message : String(error)}`.slice(0, 200)); }
+      const differ = Object.entries(want).filter(([rel, text]) => !existsSync(join(unit.dir, rel)) || readFileSync(join(unit.dir, rel), 'utf8') !== text).map(([rel]) => rel);
+      return differ.length ? fail(`create-pack --index writes differently: ${differ.join(', ')} (run it, never edit a fixed file)`) : pass(`${Object.keys(want).length} fixed files reproduced`);
+    },
+  },
   {
     id: 'layout', section: 'form',
     asks: "the unit's files exactly Pack layout's tree: fixed names at src/'s root, semantics/ its fixed files and one per spec family, screens/ one per declared screen, journeys/ its closed set",
@@ -466,8 +478,8 @@ const criteria: Criterion[] = [
         // an error message's "from '<name>'", is none)
         let text = readFileSync(join(src, f), 'utf8');
         if (f === 'fetch.ts') {
-          // The generated fetch supplies the kernel wire with the pack-local parser library.
-          // Exempt only that exact factory part; other static or dynamic imports still count.
+          // The generated fetch supplies the kernel wire with the pack-local library: graphql's parser, a stream's BSON.
+          // Exempt only those exact generated parts; other static or dynamic imports still count.
           const source = ts.createSourceFile(f, text, ts.ScriptTarget.Latest, true);
           const loaders: Array<{ start: number; end: number }> = [];
           const visit = (node: ts.Node): void => {
@@ -481,6 +493,16 @@ const criteria: Criterion[] = [
                 factory && ts.isCallExpression(factory) && ts.isIdentifier(factory.expression) && factory.expression.text === 'createPackFetch' &&
                 factory.arguments[0] === graphql.parent) loaders.push({ start: node.getStart(source), end: node.end });
             }
+            // The generated BSON loader of a stream's pack (architecture, the MongoDB wire): exactly
+            // `export const loadBson = (): Promise<unknown> => import('bson');`, BSON supplied as graphql is.
+            if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+              node.arguments.length === 1 && ts.isStringLiteral(node.arguments[0]!) && node.arguments[0]!.text === 'bson') {
+              const arrow = node.parent, declaration = arrow.parent, list = declaration?.parent, statement = list?.parent;
+              if (ts.isArrowFunction(arrow) && arrow.parameters.length === 0 && arrow.body === node &&
+                declaration && ts.isVariableDeclaration(declaration) && ts.isIdentifier(declaration.name) && declaration.name.text === 'loadBson' &&
+                statement && ts.isVariableStatement(statement) && statement.parent === source &&
+                statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) loaders.push({ start: node.getStart(source), end: node.end });
+            }
             ts.forEachChild(node, visit);
           };
           visit(source);

package/src/spec-ir.ts

@@ -49,6 +49,8 @@ export type IrOperation = {
   bodyEncoding: 'json' | 'form' | 'multipart' | 'xml' | 'none';
   /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
   scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
+  /** A form-encoded operation's string fields that take only listed values, by bracket path (formEnumsOf). */
+  enums?: Record<string, string[]>;
   successStatus: number;
   /** Binary media types declared by each response status, independent of the twin’s response headers. */
   responseMedia?: Record<string, string[]>;
@@ -350,6 +352,33 @@ function formScalarsOf(doc: Json, op: Json, pathItem: Json, encoding: IrOperatio
   return Object.keys(out).length ? Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b))) : undefined;
 }
 
+/** A form-encoded operation's string fields whose schema lists the values they take (`status`: active, inactive,
+ *  canceled), by the bracket path formScalarsOf uses; a field another alternative leaves free (a string without an enum,
+ *  or a number) takes any value and is not listed. */
+function formEnumsOf(doc: Json, op: Json, pathItem: Json, encoding: IrOperation['bodyEncoding']): Record<string, string[]> | undefined {
+  if (encoding !== 'form') return undefined;
+  const out: Record<string, string[]> = {};
+  const visit = (schema: Json, at: string[], depth: number): void => {
+    const s = deref(doc, schema);
+    if (!s || typeof s !== 'object' || depth > 12) return;
+    const alts = [...(Array.isArray(s.anyOf) ? s.anyOf : []), ...(Array.isArray(s.oneOf) ? s.oneOf : [])].map((a: Json) => deref(doc, a));
+    if (alts.length) {
+      const free = alts.some((a: Json) => (a?.type === 'string' && !Array.isArray(a.enum)) || a?.type === 'integer' || a?.type === 'number' || a?.type === 'boolean');
+      const listed = alts.filter((a: Json) => a?.type === 'string' && Array.isArray(a.enum)).flatMap((a: Json) => a.enum.map(String));
+      if (!free && listed.length && at.length) out[at.join('.')] = [...new Set(listed)];
+      for (const a of alts) if (a?.type === 'object' || a?.type === 'array' || a?.properties) visit(a, at, depth + 1);
+      return;
+    }
+    if (s.type === 'string' && Array.isArray(s.enum) && at.length) { out[at.join('.')] = s.enum.map(String); return; }
+    if (s.type === 'array') { visit(s.items, [...at, '[]'], depth + 1); return; }
+    for (const [name, p] of Object.entries(propsOf(doc, s))) visit(p, [...at, name], depth + 1);
+  };
+  for (const p of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])].map((q: Json) => deref(doc, q))) if (p?.in === 'query') visit(p.schema, [String(p.name)], 0);
+  const body = deref(doc, deref(doc, op.requestBody)?.content?.['application/x-www-form-urlencoded']?.schema);
+  for (const [name, p] of Object.entries(propsOf(doc, body))) visit(p, [name], 0);
+  return Object.keys(out).length ? Object.fromEntries(Object.entries(out).sort(([x], [y]) => x.localeCompare(y))) : undefined;
+}
+
 /** The class of one operation, from its method, its path and what it answers. An operation this cannot place is `action`, never CRUD. */
 /** A path and its discriminator as one key: `/responses/{id}` and `/responses/{id}?beta=true` are different reads. */
 // a null value (the key present with any value) keys as the bare name
@@ -477,6 +506,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
       const credentials = [...new Set(security.flatMap((req: Json) => { const names = Object.keys(req ?? {}); return names.length ? names : ['anonymous']; }))].sort();
       const body = bodyOf(doc, op);
       const scalars = formScalarsOf(doc, op, item, body.bodyEncoding);
+      const enums = formEnumsOf(doc, op, item, body.bodyEncoding);
       const ownServer = String((op.servers ?? (item as Json).servers)?.[0]?.url ?? '');
       const ownBase = /^https?:\/\//.test(ownServer) ? new URL(ownServer).pathname.replace(/\/+$/, '') : undefined;
       raw.push({
@@ -488,6 +518,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
         ...(ownBase !== undefined && ownBase !== docBase ? { basePath: ownBase } : {}),
         ...body,
         ...(scalars ? { scalars } : {}),
+        ...(enums ? { enums } : {}),
         successStatus: success.status,
         ...(Object.keys(responseMedia).length ? { responseMedia, ...(Object.keys(defaultResponseMedia).length ? { defaultResponseMedia } : {}) } : {}),
         ...(success.empty ? { emptySuccess: true as const } : {}),

package/src/tools/judge-brief.ts

@@ -0,0 +1,63 @@
+// A JUDGE'S BRIEF (pack-done's (f); architecture, "What a judge rejects"): what a judge reads and writes for one vendor's
+// outline, life and published examples, printed for a judge in another session (`codex exec`, `claude -p`, any agent
+// runtime). The verdict names its judge and the authors; the grade refuses one whose judge is an author
+// (packages/twin-standard/src/verdict.ts). One judging per pack: the verdict stands through later changes.
+//
+//   twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository's root; twin-world's
+//   bun scripts/judge-brief.ts runs the same)
+import { attributionName } from '../verdict.ts';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { packsRoot } from './packs-root.ts';
+const PACKS = packsRoot();
+/** The architecture a judge's list is read from: the twin-world checkout this standard is in, else its published copy. */
+const ARCHITECTURE = join(import.meta.dir, '..', '..', '..', '..', 'docs', 'contributing', 'architecture.md');
+const PUBLISHED_ARCHITECTURE = 'https://world-docs.volter.ai/docs/contributing/architecture.md';
+
+const vendor = process.argv[2];
+const authorsAt = process.argv.indexOf('--authors');
+const authors = authorsAt > 0 ? (process.argv[authorsAt + 1] ?? '').split(',').map((a) => a.trim()).filter(Boolean).map((name) => attributionName(name)!) : [];
+if (!vendor || vendor.startsWith('-') || !authors.length) {
+  console.error('usage: twin-standard judge-brief <vendor> --authors <author name>[,<agent>...]   (from the pack repository\'s root)');
+  process.exit(2);
+}
+const journeys = join(PACKS, vendor, 'journeys');
+if (!existsSync(journeys)) { console.error(`judge-brief: ${vendor} has no journeys/ in ${PACKS}`); process.exit(2); }
+// the list of what a judge rejects, as architecture holds it
+const architecture = existsSync(ARCHITECTURE) ? readFileSync(ARCHITECTURE, 'utf8') : await fetch(PUBLISHED_ARCHITECTURE).then((r) => (r.ok ? r.text() : ''), () => '');
+const listAt = architecture.indexOf('#### What a judge rejects\n');
+if (listAt < 0) { console.error(`judge-brief: the architecture (${existsSync(ARCHITECTURE) ? ARCHITECTURE : PUBLISHED_ARCHITECTURE}) has no "#### What a judge rejects" section`); process.exit(2); }
+const listFrom = architecture.indexOf('\n- ', listAt);
+const listTo = architecture.indexOf('\n\n', listFrom + 1);
+const rejects = architecture.slice(listFrom + 1, listTo < 0 ? undefined : listTo).trim();
+const sha = (file: string): string => createHash('sha256').update(readFileSync(file)).digest('hex');
+const judged = [
+  { file: 'customer-life.outline.md', verdict: 'customer-life.outline.verdict.json', what: "the life's outline: the customer's story in acts" },
+  { file: 'customer-life.json', verdict: 'customer-life.verdict.json', what: 'the life: every step an application or person takes, its expectations' },
+  { file: 'vendor-examples.json', verdict: 'vendor-examples.verdict.json', what: "the published examples: the vendor's own documented requests and answers, replayed" },
+].filter((j) => existsSync(join(journeys, j.file)));
+
+console.log(`You are the judge of the ${vendor} twin's journeys. You did not write them, and you judge them in a session other than
+the run that wrote them. Judge them against the vendor and against the list below; do not edit any judged file, and run no
+test. Read what you need: the pack's spec (${vendor}/spec/, SOURCE.md naming every page read), its demand
+(${vendor}/journeys/demand.json: what the applications call), its decision table (journeys/decisions.json), and the
+vendor's own documentation the spec cites.
+
+What you judge (in ${vendor}/journeys/), each with the sha256 your verdict names:
+${judged.map((j) => `- ${j.file} (${j.what}): sha256 ${sha(join(journeys, j.file))}`).join('\n')}
+
+What a judge rejects (docs/contributing/architecture.md, "What a judge rejects"):
+${rejects}
+
+For each file write its verdict beside it, as JSON:
+${judged.map((j) => `- ${j.verdict}`).join('\n')}
+{
+  "judge": { "agent": "<what you are: your runtime and model>", "name": "<your author name or reviewer role>" },
+  "authors": ${JSON.stringify(authors)},
+  "sha256": "<the judged file's sha256 above>",
+  "judgedAt": "<today, YYYY-MM-DD>",
+  "plausible": <true only when no ruling stands>,
+  "rulings": [ { "id": "<short name>", "steps": [<step indexes, or acts>], "barItem": "<the list's item>", "reason": "<what is wrong, citing the step and the vendor's page>", "correction": "<what the author changes>" } ]
+}
+A correction naming a wait gives it as a life writes one: one number and one unit (\`915m\`, \`3d\`). A verdict with any ruling is not plausible. The authors apply every ruling; this is the one judging, and the verdict stands through their changes.`);