@volter/twin-standard 1.0.30 → 1.0.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "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",
@@ -45,6 +45,14 @@
     "./spec": {
       "types": "./dist/src/spec.d.ts",
       "default": "./dist/src/spec.js"
+    },
+    "./walk": {
+      "types": "./dist/src/walk/behavior-journey.d.ts",
+      "default": "./dist/src/walk/behavior-journey.js"
+    },
+    "./journey": {
+      "types": "./dist/src/walk/journey-kit.d.ts",
+      "default": "./dist/src/walk/journey-kit.js"
     }
   },
   "bin": {
@@ -61,11 +69,39 @@
     "typescript": "^5.9.0",
     "yaml": "2.9.0"
   },
+  "peerDependencies": {
+    "@volter/world-core": "*",
+    "@volter/world-runtime": "*"
+  },
+  "peerDependenciesMeta": {
+    "@volter/world-runtime": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.131.0",
+    "@aws-sdk/client-s3": "^3.1081.0",
+    "@aws-sdk/client-secrets-manager": "^3.1081.0",
+    "@clerk/backend": "2.33.3",
+    "@elevenlabs/elevenlabs-js": "^2.70.0",
+    "@planetscale/database": "1.19.0",
+    "@slack/socket-mode": "2.0.7",
+    "@slack/web-api": "7.19.0",
     "@types/bun": "^1.2.20",
-    "@types/node": "^24.0.0"
+    "@types/node": "^24.0.0",
+    "@upstash/qstash": "2.11.0",
+    "@upstash/ratelimit": "2.0.6",
+    "@upstash/redis": "1.38.2",
+    "@volter/identity": "0.4.1",
+    "@volter/tunnel": "2.0.5",
+    "aws4fetch": "^1.0.20",
+    "cloudflare": "^7.2.0",
+    "openai": "^7.25.0",
+    "stripe": "^23.0.0",
+    "@google/genai": "2.13.0",
+    "@google/generative-ai": "0.24.1"
   },
   "engines": {
-    "node": ">=22.3"
+    "node": ">=22.6"
   }
 }

package/src/archive-source.ts

@@ -0,0 +1,141 @@
+// Pinned vendor archive evidence. Members are read in memory, never extracted to the filesystem.
+import { createHash } from 'node:crypto';
+import { gunzipSync, inflateRawSync } from 'node:zlib';
+
+export type ArchiveSource = { url: string; sha256: string; member: string };
+export function archiveSource(locator: string): ArchiveSource | undefined {
+  const m = /^archive:(https?:\/\/\S+)#sha256=([a-fA-F0-9]{64})!\/(\S+)$/.exec(locator);
+  if (!m || m[3]!.startsWith('/') || m[3]!.includes('\\') || m[3]!.split('/').some(p => p === '..' || p === '.' || !p)) return undefined;
+  return { url: m[1]!, sha256: m[2]!.toLowerCase(), member: m[3]! };
+}
+const hashOf = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('hex');
+const stringAt = (bytes: Buffer, start: number, size: number): string => bytes.subarray(start, start + size).toString('utf8').replace(/\0.*$/s, '');
+
+function zipMember(bytes: Buffer, member: string): Buffer {
+  // The central directory supplies sizes even when local headers use data descriptors.
+  let end = bytes.length - 22;
+  while (end >= Math.max(0, bytes.length - 65557) && bytes.readUInt32LE(end) !== 0x06054b50) end--;
+  if (end < Math.max(0, bytes.length - 65557)) throw new Error('ZIP has no end directory');
+  if (bytes.readUInt16LE(end + 4) || bytes.readUInt16LE(end + 6)) throw new Error('multi-disk ZIP is not supported');
+  let count = bytes.readUInt16LE(end + 10), offset = bytes.readUInt32LE(end + 16);
+  if (count === 0xffff || offset === 0xffffffff) {
+    const loc = end - 20;
+    if (loc < 0 || bytes.readUInt32LE(loc) !== 0x07064b50) throw new Error('ZIP64 has no directory locator');
+    const pos = Number(bytes.readBigUInt64LE(loc + 8));
+    if (!Number.isSafeInteger(pos) || bytes.readUInt32LE(pos) !== 0x06064b50) throw new Error('invalid ZIP64 directory');
+    count = Number(bytes.readBigUInt64LE(pos + 32)); offset = Number(bytes.readBigUInt64LE(pos + 48));
+  }
+  for (let i = 0; i < count; i++) {
+    if (bytes.readUInt32LE(offset) !== 0x02014b50) throw new Error('invalid ZIP directory member');
+    const flags = bytes.readUInt16LE(offset + 8), method = bytes.readUInt16LE(offset + 10);
+    let size = bytes.readUInt32LE(offset + 20), plain = bytes.readUInt32LE(offset + 24), local = bytes.readUInt32LE(offset + 42);
+    const names = bytes.readUInt16LE(offset + 28), extras = bytes.readUInt16LE(offset + 30), comments = bytes.readUInt16LE(offset + 32);
+    const name = stringAt(bytes, offset + 46, names);
+    if (name === member) {
+      if (flags & 1) throw new Error('encrypted ZIP member');
+      // ZIP64 values appear only for fields whose ordinary value is the sentinel.
+      if (size === 0xffffffff || plain === 0xffffffff || local === 0xffffffff) {
+        let at = offset + 46 + names, stop = at + extras;
+        while (at < stop) {
+          const id = bytes.readUInt16LE(at), len = bytes.readUInt16LE(at + 2);
+          if (id === 1) {
+            let v = at + 4;
+            if (plain === 0xffffffff) { plain = Number(bytes.readBigUInt64LE(v)); v += 8; }
+            if (size === 0xffffffff) { size = Number(bytes.readBigUInt64LE(v)); v += 8; }
+            if (local === 0xffffffff) local = Number(bytes.readBigUInt64LE(v));
+            break;
+          }
+          at += 4 + len;
+        }
+      }
+      if (![size, plain, local].every(Number.isSafeInteger) || bytes.readUInt32LE(local) !== 0x04034b50) throw new Error('invalid ZIP local member');
+      const mode = bytes.readUInt32LE(offset + 38) >>> 16;
+      if ((mode & 0xf000) === 0xa000 || name.endsWith('/')) throw new Error('ZIP member is not a regular file');
+      const start = local + 30 + bytes.readUInt16LE(local + 26) + bytes.readUInt16LE(local + 28);
+      if (start + size > bytes.length) throw new Error('truncated ZIP member');
+      const data = bytes.subarray(start, start + size);
+      const result = method === 0 ? data : method === 8 ? inflateRawSync(data) : undefined;
+      if (!result) throw new Error(`unsupported ZIP compression ${method}`);
+      if (result.length !== plain) throw new Error('ZIP member size differs from its directory');
+      return result;
+    }
+    offset += 46 + names + extras + comments;
+  }
+  throw new Error(`archive has no member ${member}`);
+}
+function tarNumber(bytes: Buffer): number {
+  if (bytes[0]! & 0x80) {
+    let n = BigInt(bytes[0]! & 0x7f);
+    for (const b of bytes.subarray(1)) n = (n << 8n) | BigInt(b);
+    const value = Number(n);
+    if (!Number.isSafeInteger(value)) throw new Error('tar size is too large');
+    return value;
+  }
+  const s = bytes.toString('ascii').replace(/\0.*$/s, '').trim();
+  if (s && !/^[0-7]+$/.test(s)) throw new Error('invalid tar number');
+  return s ? parseInt(s, 8) : 0;
+}
+function paxFields(bytes: Buffer): Record<string, string> {
+  const out: Record<string, string> = {};
+  let at = 0;
+  while (at < bytes.length) {
+    const space = bytes.indexOf(32, at), n = Number(bytes.subarray(at, space).toString());
+    if (space < at || !Number.isInteger(n) || n <= space - at + 1 || at + n > bytes.length) throw new Error('invalid tar PAX record');
+    const entry = bytes.subarray(space + 1, at + n - 1).toString('utf8'), eq = entry.indexOf('=');
+    if (eq >= 0) out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    at += n;
+  }
+  return out;
+}
+function tarMember(bytes: Buffer, member: string): Buffer {
+  let at = 0, longName: string | undefined, local: Record<string, string> = {}, global: Record<string, string> = {};
+  while (at + 512 <= bytes.length) {
+    const header = bytes.subarray(at, at + 512);
+    if (header.every(b => b === 0)) break;
+    const sum = header.reduce((n, b, i) => n + (i >= 148 && i < 156 ? 32 : b), 0);
+    if (sum !== tarNumber(header.subarray(148, 156))) throw new Error('invalid tar header checksum');
+    const kind = stringAt(header, 156, 1), baseSize = tarNumber(header.subarray(124, 136));
+    const meta = kind === 'x' || kind === 'g' || kind === 'L' || kind === 'K';
+    const attributes = { ...global, ...local };
+    const size = !meta && attributes.size !== undefined ? Number(attributes.size) : baseSize;
+    if (!Number.isSafeInteger(size) || size < 0 || at + 512 + size > bytes.length) throw new Error('invalid tar member size');
+    const data = bytes.subarray(at + 512, at + 512 + size);
+    if (kind === 'x') local = paxFields(data);
+    else if (kind === 'g') global = { ...global, ...paxFields(data) };
+    else if (kind === 'L') longName = data.toString('utf8').replace(/\0.*$/s, '');
+    else if (kind !== 'K') {
+      const prefix = stringAt(header, 345, 155);
+      const name = attributes.path ?? longName ?? `${prefix ? `${prefix}/` : ''}${stringAt(header, 0, 100)}`;
+      if (name.replace(/^\.\//, '') === member) {
+        if (kind !== '' && kind !== '0' && kind !== '7') throw new Error('tar member is not a regular file');
+        return data;
+      }
+      local = {}; longName = undefined;
+    }
+    at += 512 + Math.ceil(size / 512) * 512;
+  }
+  throw new Error(`archive has no member ${member}`);
+}
+
+/** One cache per source-check run; multiple pinned members share the archive's one download. */
+export function archiveReader(): (source: ArchiveSource) => Promise<{ status: number; raw: string; sha256?: string; error?: string }> {
+  const downloads = new Map<string, Promise<{ status: number; bytes: Buffer }>>();
+  return async source => {
+    try {
+      let pending = downloads.get(source.url);
+      if (!pending) {
+        pending = (async () => {
+          const res = await fetch(source.url, { redirect: 'follow', signal: AbortSignal.timeout(30000), headers: { 'user-agent': 'volter-source-check/1.0 (+https://volter.ai)' } });
+          return { status: res.status, bytes: Buffer.from(await res.arrayBuffer()) };
+        })();
+        downloads.set(source.url, pending);
+      }
+      const { status, bytes } = await pending;
+      if (status !== 200) return { status, raw: '' };
+      const sha256 = hashOf(bytes);
+      if (sha256 !== source.sha256) return { status: 0, raw: '', sha256, error: `SHA256 differs: expected ${source.sha256}, received ${sha256}` };
+      const member = bytes.readUInt32LE(0) === 0x04034b50 ? zipMember(bytes, source.member) : tarMember(bytes[0] === 0x1f && bytes[1] === 0x8b ? gunzipSync(bytes) : bytes, source.member);
+      return { status, raw: member.toString('utf8'), sha256 };
+    } catch (err) { return { status: 0, raw: '', error: err instanceof Error ? err.message : String(err) }; }
+  };
+}

package/src/check-sources.ts

@@ -10,44 +10,69 @@
 //
 // Usage: twin-standard check-sources <pack dir> [--recheck]   (twin-world: bun scripts/check-sources.ts <vendor>)
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { unitAt } from './unit.ts';
+import { archiveReader, archiveSource } from './archive-source.ts';
 
-export type SourceRecord = { status: number; checked: string; quotes?: Record<string, boolean> };
-export type Patch = { op: string; path: string; why: string; source?: { url?: string; spec?: string; quote: string } };
+export type SourceRecord = { status: number; checked: string; quotes?: Record<string, boolean>; sha256?: string; error?: string };
+export type Patch = { op: string; path: string; why: string; source?: { url?: string; spec?: string; recording?: string; quote: string } };
 
 /** Every URL in a text, without trailing punctuation. */
-export const urlsIn = (text: string): string[] => (text.match(/https?:\/\/[^\s"'<>]+/g) ?? []).map((u) => u.replace(/[),.;:\]]+$/, ''));
+export const urlsIn = (text: string): string[] => (text.match(/(?:archive:)?https?:\/\/[^\s"'<>]+/g) ?? []).map((u) => u.replace(/[),.;:\]]+$/, ''));
 
-/** The citations a pack's handlers write: each comment line of `src/semantics/` reading `source: <citation>`, where it
- *  stands (`<file>:<line>`) and what it cites ("What an author writes, and how": a rule carries its citation beside it). */
+/** The citations beside vendor rules in a pack's handwritten source, including hosted screens and engines.
+ * Generated source and test files do not supply author evidence. */
 export function handlerCitations(pkg: string): Array<{ where: string; source: string }> {
-  const dir = join(pkg, 'src', 'semantics');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter((f) => /\.tsx?$/.test(f) && !/\.test\.tsx?$/.test(f)).sort().flatMap((f) =>
-    readFileSync(join(dir, f), 'utf8').split('\n').flatMap((line, i) => {
-      // a line of its own (`// source:`, `* source:` in a doc comment) or a comment ending a statement
+  const files: Array<{ name: string; at: string }> = [];
+  const walk = (dir: string, prefix: string): void => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const name = `${prefix}${entry.name}`, at = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== 'generated') walk(at, `${name}/`);
+      } else if (/\.tsx?$/.test(entry.name) && !/\.(?:test|uitest|spec)\.tsx?$/.test(entry.name)) files.push({ name, at });
+    }
+  };
+  walk(join(pkg, 'src'), '');
+  const comments = files.flatMap(({ name: f, at }) =>
+    readFileSync(at, 'utf8').split('\n').flatMap((line, i) => {
       const m = /(?:^\s*(?:\/\/|\/?\*+)|[\s;,)}\]]\/\/)\s*source:\s*(.+?)\s*(?:\*\/)?\s*$/i.exec(line);
       return m ? [{ where: `${f}:${i + 1}`, source: m[1]! }] : [];
     }));
+  const examplesPath = join(pkg, 'spec', 'doc-examples.json');
+  const examples: Array<{ source?: string; quote?: string }> = existsSync(examplesPath) ? JSON.parse(readFileSync(examplesPath, 'utf8')) : [];
+  return [...comments, ...examples.flatMap((e, i) => e.quote !== undefined && (e.source?.startsWith('archive:') || /raw\.githubusercontent\.com\/.*\/tests?\//.test(e.source ?? '')) ? [{ where: `spec/doc-examples.json[${i}]`, source: `${e.source} "${e.quote.replace(/"/g, '\\"')}"` }] : [])];
 }
 
 /** A handler citation's page and the words it says the page holds (`https://… "quote"`), when it quotes. */
 export const quotedPage = (source: string): { url: string; quote: string } | undefined => {
-  const m = /^(https?:\/\/\S+)\s+"([\s\S]+)"$/.exec(source.trim());
-  return m && m[2]!.trim() ? { url: m[1]!.replace(/[),.;:\]]+$/, ''), quote: m[2]!.replace(/\\"/g, '"') } : undefined;
+  const m = /^((?:archive:)?https?:\/\/\S+)\s+"([\s\S]+)"$/.exec(source.trim());
+  return m && m[2]!.trim() && (!m[1]!.startsWith('archive:') || archiveSource(m[1]!)) ? { url: m[1]!.replace(/[),.;:\]]+$/, ''), quote: m[2]!.replace(/\\"/g, '"') } : undefined;
 };
 
+/** Evidence is usable offline only when the page answered or the archive digest matched its pin. */
+export function sourceHeld(url: string, record: SourceRecord | undefined): boolean {
+  if (record?.status !== 200) return false;
+  if (!url.startsWith('archive:')) return true;
+  const archive = archiveSource(url);
+  return !!archive && record.sha256 === archive.sha256;
+}
+
 /** What a pack cites: each URL, and the quotes a patch says the URL's page holds. */
 export async function citations(pkg: string): Promise<Map<string, Set<string>>> {
   const cited = new Map<string, Set<string>>();
   const cite = (url: string, quote?: string) => { if (!cited.has(url)) cited.set(url, new Set()); if (quote) cited.get(url)!.add(quote); };
-  const { manifest } = (await import(join(pkg, 'src', 'manifest.ts'))) as { manifest: { resources: Record<string, { state?: Record<string, { transitions: Array<{ source?: string }> }> }> } };
-  for (const r of Object.values(manifest.resources)) for (const f of Object.values(r.state ?? {})) for (const t of f.transitions) for (const u of urlsIn(String(t.source ?? ''))) cite(u);
+  const { manifest } = (await import(join(pkg, 'src', 'manifest.ts'))) as { manifest: { resources?: Record<string, { state?: Record<string, { transitions: Array<{ source?: string }> }> }> } };
+  // a vendor of lanes' root declares no resources of its own (its lanes do): only its handlers' and manifest's citations
+  for (const r of Object.values(manifest.resources ?? {})) for (const f of Object.values(r.state ?? {})) for (const t of f.transitions) {
+    const source = String(t.source ?? ''), q = quotedPage(source);
+    if (q?.url.startsWith('archive:')) cite(q.url, q.quote); else for (const u of urlsIn(source)) cite(u);
+  }
   for (const c of handlerCitations(pkg)) {
     const q = quotedPage(c.source);
     if (q) cite(q.url, q.quote);
-    else for (const u of urlsIn(c.source)) cite(u);
+    // a URL inside the quoted words (`spec:<ref> "… https://…"`) is what the spec says, not a page cited
+    else for (const u of urlsIn(c.source.replace(/"[^"]*"/g, ''))) cite(u);
   }
   const patchPath = join(pkg, 'spec', 'patches.json');
   if (existsSync(patchPath)) {
@@ -65,8 +90,37 @@ export async function citations(pkg: string): Promise<Map<string, Set<string>>>
 const textOf = (html: string): string => bare(html.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '').replace(/<[^>]+>/g, '')
   .replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&'));
 const bare = (s: string): string => s.replace(/[\s\p{Cf}]+/gu, '');
+/** A page's markup taken out and its words kept apart, as a person reads it: block ends as line breaks, runs of space as one. */
+const readable = (html: string): string => html.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '')
+  .replace(/<\/(p|div|li|h[1-6]|pre|tr|section|article|br)\s*>|<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, ' ')
+  .replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&')
+  .replace(/[ \t]+/g, ' ').replace(/\n\s*\n\s*/g, '\n\n').trim();
 
 /** Fetch and record the sources the unit at `args[0]` cites (`--recheck`: every one, not only those due). */
+/** A documentation page as the citation check reads it: fetched as a browser-like agent (asked again as this tool where
+ *  that is refused), an HTML page's text without its markup, a plain page as it is. `twin-standard read-page <url>` prints
+ *  it, so an author reads a page through the same path its citations are checked on; `--raw` prints the page's own bytes
+ *  (a spec writer that reads the page's tables). */
+export async function readPage(url: string): Promise<{ status: number; text: string; readable: string; raw: string; sha256?: string; error?: string }> {
+  if (url.startsWith('archive:')) {
+    const archive = archiveSource(url);
+    if (!archive) return { status: 0, text: '', readable: '', raw: '', error: 'malformed archive locator' };
+    const result = await archiveReader()(archive);
+    return { ...result, text: bare(result.raw), readable: result.raw };
+  }
+  try {
+    const get = (agent: string): Promise<Response> => fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(8000), headers: { 'user-agent': agent } });
+    let res = await get('Mozilla/5.0 (volter twin source check)');
+    // a site that refuses a browser-like agent it cannot verify (dev.mysql.com) is asked again as the tool this is
+    if (res.status === 403) res = await get('volter-source-check/1.0 (+https://volter.ai)');
+    // an HTML page's text without its markup; a plain page (a raw source file, a markdown document) as it is: its
+    // `<name>` placeholders and `=>` arrows are not tags
+    const body = await res.text();
+    const html = (res.headers.get('content-type') ?? '').includes('html');
+    return { status: res.status, text: html ? textOf(body) : bare(body), readable: html ? readable(body) : body, raw: body };
+  } catch { return { status: 0, text: '', readable: '', raw: '' }; }
+}
+
 export async function checkSources(args: string[]): Promise<void> {
   const vendor = args[0];
   if (!vendor) { console.error('usage: twin-standard check-sources <pack dir> [--recheck]'); process.exit(1); }
@@ -75,35 +129,31 @@ export async function checkSources(args: string[]): Promise<void> {
   const record: Record<string, SourceRecord> = existsSync(recordPath) ? JSON.parse(readFileSync(recordPath, 'utf8')) : {};
   const cited = await citations(pkg);
   const recheck = args.includes('--recheck');
-  const due = [...cited].filter(([url, quotes]) => recheck || record[url]?.status !== 200 || [...quotes].some((q) => record[url]?.quotes?.[q] !== true));
+  const due = [...cited].filter(([url, quotes]) => recheck || !sourceHeld(url, record[url]) || [...quotes].some((q) => record[url]?.quotes?.[q] !== true));
   const today = new Date().toISOString().slice(0, 10);
+  const readArchive = archiveReader();
   let next = 0;
   await Promise.all(Array.from({ length: 16 }, async () => {
     while (next < due.length) {
       const [url, quotes] = due[next++]!;
-      let status = 0;
-      let text = '';
-      try {
-        const get = (agent: string): Promise<Response> => fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(8000), headers: { 'user-agent': agent } });
-        let res = await get('Mozilla/5.0 (volter twin source check)');
-        // a site that refuses a browser-like agent it cannot verify (dev.mysql.com) is asked again as the tool this is
-        if (res.status === 403) res = await get('volter-source-check/1.0 (+https://volter.ai)');
-        status = res.status;
-        // an HTML page's text without its markup; a plain page (a raw source file, a markdown document) as it is: its
-        // `<name>` placeholders and `=>` arrows are not tags
-        text = (res.headers.get('content-type') ?? '').includes('html') ? textOf(await res.text()) : bare(await res.text());
-      } catch { status = 0; }
+      const archive = archiveSource(url);
+      const result = archive ? await readArchive(archive) : await readPage(url);
+      const { status, sha256, error } = result;
+      const text = 'text' in result ? String(result.text) : bare(result.raw);
       const found = Object.fromEntries([...quotes].map((q) => [q, status === 200 && text.includes(bare(q))]));
-      record[url] = { status, checked: today, ...(quotes.size ? { quotes: found } : {}) };
+      record[url] = { status, checked: today, ...(sha256 ? { sha256 } : {}), ...(error ? { error } : {}), ...(quotes.size ? { quotes: found } : {}) };
     }
   }));
   const sorted = Object.fromEntries(Object.entries(record).filter(([url]) => cited.has(url)).sort(([a], [b]) => a.localeCompare(b)));
-  writeFileSync(recordPath, `${JSON.stringify(sorted, null, 2)}\n`);
-  const bad = Object.entries(sorted).filter(([, r]) => r.status !== 200);
+  // a vendor of lanes' root holds no spec/ (its lanes do) and no derive reads it: its citations are checked, not recorded
+  if (existsSync(dirname(recordPath))) writeFileSync(recordPath, `${JSON.stringify(sorted, null, 2)}\n`);
+  const bad = Object.entries(sorted).filter(([url, r]) => !sourceHeld(url, r));
   const unquoted = Object.entries(sorted).flatMap(([url, r]) => Object.entries(r.quotes ?? {}).filter(([, ok]) => !ok).map(([q]) => `${url}: "${q}"`));
   console.log(`${vendor}: ${cited.size} cited pages, ${due.length} fetched; ${bad.length} not found or not fetchable, ${unquoted.length} quotes not on their page`);
-  for (const [url, r] of bad) console.log(`  ${r.status || 'no answer'} ${url}`);
+  for (const [url, r] of bad) console.log(`  ${r.status || 'no answer'} ${url}${r.error ? `: ${r.error}` : ''}`);
   for (const u of unquoted) console.log(`  quote missing: ${u}`);
+  // a citation that does not hold fails the command, so a caller reads the verdict from the exit code, not the output
+  if (bad.length || unquoted.length) process.exitCode = 1;
 }
 
 if (import.meta.main) await checkSources(process.argv.slice(2));

package/src/cli.ts

@@ -9,16 +9,21 @@
 //   twin-standard grade <pack or lane dir>… [--static] [--form]    each criterion's result
 //   twin-standard derive <pack or lane dir> [--out <dir>]          write the unit's src/generated/ from its spec
 //   twin-standard check-sources <pack or lane dir> [--recheck]     fetch and record the sources the unit cites
+//   twin-standard conform <pack dir> | <name>@<version> [--registry <url>]
+//                                                                  the pack served and read as an application and the
+//                                                                  catalog meet it (conformance.ts): a checkout, or a
+//                                                                  published version as the catalog admits it; or exit 1
 //   twin-standard --version                                        the package's version and each standard's
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { unitsOf, p3Gate } from './gate.ts';
 import { grade, STANDARDS } from './grade.ts';
+import { withCheckoutFiles } from './protocol-3.ts';
 import { gatePublished } from './published.ts';
 
 const [command, ...args] = process.argv.slice(2);
 const usage = (): never => {
-  console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | check-sources <unit> [--recheck] | --version');
+  console.error('usage: twin-standard gate <repo> [units…] | gate-published <name>@<version>… [--registry <url>] | grade <unit>… [--static] [--form] | derive <unit> [--out <dir>] | read-page <url> [--raw] | check-sources <unit> [--recheck] | conform <pack dir> | <name>@<version> [--registry <url>] | --version');
   process.exit(2);
 };
 
@@ -55,13 +60,15 @@ if (command === '--version') {
 } else if (command === 'grade') {
   const units = args.filter((a) => !a.startsWith('--'));
   if (!units.length) usage();
-  for (const unit of units) {
-    const grades = await grade(unit, { static: args.includes('--static'), ...(args.includes('--form') ? { sections: ['form'] as const } : {}) });
-    for (const [key, s] of Object.entries(grades)) {
-      console.log(`${unit}  ${key}  ${s.met}/${s.total}`);
-      for (const c of s.criteria) console.log(`  ${c.pass ? 'ok ' : 'NO '} ${c.section.padEnd(9)} ${c.id.padEnd(22)} ${c.reason}`);
+  await withCheckoutFiles(async () => {
+    for (const unit of units) {
+      const grades = await grade(unit, { static: args.includes('--static'), ...(args.includes('--form') ? { sections: ['form'] as const } : {}) });
+      for (const [key, s] of Object.entries(grades)) {
+        console.log(`${unit}  ${key}  ${s.met}/${s.total}`);
+        for (const c of s.criteria) console.log(`  ${c.pass ? 'ok ' : 'NO '} ${c.section.padEnd(9)} ${c.id.padEnd(22)} ${c.reason}`);
+      }
     }
-  }
+  });
 } else if (command === 'derive') {
   if (!args[0]) usage();
   // the derivation is a script over process.argv: it reads the unit from its first argument
@@ -70,6 +77,31 @@ if (command === '--version') {
 } else if (command === 'check-sources') {
   if (!args[0]) usage();
   await (await import('./check-sources.ts')).checkSources(args);
+} else if (command === 'read-page') {
+  // a documentation page's text, read as the citation check reads it: where an author finds the vendor's examples and words
+  if (!args[0]) usage();
+  const { status, readable, raw, error } = await (await import('./check-sources.ts')).readPage(args[0]);
+  if (status !== 200) { console.error(`read-page: ${args[0]} answered ${status || 'nothing'}${error ? `: ${error}` : ''}`); process.exit(1); }
+  // --raw: the page's own bytes, as fetched (a spec writer reads its tables, which the readable text drops)
+  if (args.includes('--raw')) process.stdout.write(raw); else console.log(readable);
+} else if (command === 'conform') {
+  if (!args[0]) usage();
+  const at = args.indexOf('--registry');
+  const target = args.find((a, i) => !a.startsWith('--') && (at < 0 || i !== at + 1))!;
+  // a directory is a checkout; `<name>@<version>` (a scope's leading @ aside) is a version on the registry, and a
+  // `.tgz` the tarball `npm pack` makes of one, the bytes a publish would send
+  const published = target.endsWith('.tgz') || (!existsSync(target) && /^@?[^@]+@[^@]+$/.test(target));
+  const results = published
+    ? await (await import('./published.ts')).conformPublished(target, at >= 0 ? { registry: args[at + 1]! } : {})
+    : await (await import('./conformance.ts')).conformance(target);
+  for (const r of results) {
+    console.log(`${r.failures.length ? '✗' : '✓'} ${r.id.padEnd(15)} ${r.asks}${r.note ? `  (${r.note})` : ''}`);
+    for (const f of r.failures) console.log(`    ${f}`);
+  }
+  const failing = results.filter((r) => r.failures.length).length;
+  console.log(failing ? `conform: ${failing} of ${results.length} checks failing` : `conform: all ${results.length} checks hold`);
+  // a served pack may leave handles open (a socket's timers): the verdict is the exit code
+  process.exit(failing ? 1 : 0);
 } else {
   usage();
 }

package/src/clients/ai-gateway.ts

@@ -0,0 +1,4 @@
+// Vercel AI Gateway's chat through openai-node (its OpenAI-compatible API), the shared chat cases.
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = chatCases({ key: 'AI_GATEWAY_API_KEY', base: (host) => `https://${host}/v1`, model: 'anthropic/claude-sonnet-5' });

package/src/clients/anthropic-messages.ts

@@ -0,0 +1,60 @@
+// The Messages cases every vendor on Anthropic's Messages wire holds, driven by Anthropic's own SDK pointed at the vendor
+// (an application using @anthropic-ai/sdk with that vendor's base URL): a turn answered with the World's scenario
+// loaded, `tool_choice: { type: 'none' }` answered without a tool_use block, the scenario rewritten between two turns
+// deciding the second.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const MESSAGES = 'https://platform.claude.com/docs/en/api/messages';
+const TOOLS = [{ name: 'lookup', input_schema: { type: 'object' as const, properties: {} } }];
+/** A vendor's Messages as the SDK reaches it: the variable its key is issued in, the base URL on its host, a model it
+ *  serves, and a turn that calls the tool `lookup` in the World's scenario grammar for the vendor (the pack's GET /twin). */
+export type MessagesVendor = { key: string; base: (host: string) => string; model: string; toolTurn: Record<string, unknown> };
+
+export function messagesCases(v: MessagesVendor): ClientCase[] {
+  const SCRIPT = { handlers: [
+    { id: 'calls', on: { hasTool: 'lookup' }, respond: v.toolTurn },
+    { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
+  ] };
+  const ask = async (c: ClientContext, extra: Record<string, unknown> = {}) => {
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+    const client = new Anthropic({ apiKey: c.env[v.key] ?? '', baseURL: v.base(c.host), fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+    return client.messages.create({ model: v.model, max_tokens: 256, messages: [{ role: 'user', content: 'hello' }], ...extra } as never) as Promise<{ content?: Array<{ type: string; text?: string }> }>;
+  };
+  const text = (m: { content?: Array<{ type: string; text?: string }> }): string | undefined => m.content?.find((b) => b.type === 'text')?.text;
+  return [
+    {
+      id: 'messages-answers',
+      asks: "a message is answered, the World's scenario loaded",
+      source: `${MESSAGES} "Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation."`,
+      async run(c) {
+        c.scenario(SCRIPT);
+        const answer = await ask(c).catch((e: Error) => e);
+        if (answer instanceof Error) return [`the client's messages.create failed: ${answer.message}`];
+        return text(answer) === 'scripted words' ? [] : [`the scripted turn was not answered: ${JSON.stringify(answer.content).slice(0, 120)}`];
+      },
+    },
+    {
+      id: 'messages-tool-choice-none',
+      asks: "tool_choice { type: 'none' } is answered without a tool_use block",
+      source: `${MESSAGES} "The model will not be allowed to use tools."`,
+      async run(c) {
+        c.scenario(SCRIPT);
+        const none = await ask(c, { tools: TOOLS, tool_choice: { type: 'none' } }).catch((e: Error) => e);
+        if (none instanceof Error) return [`the client's messages.create failed: ${none.message}`];
+        return none.content?.some((b) => b.type === 'tool_use') ? ["tool_choice none was answered with a tool_use block"] : [];
+      },
+    },
+    {
+      id: 'messages-scenario-each-turn',
+      asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
+      source: 'architecture "The scenario is read from the World\'s store at every turn"',
+      async run(c) {
+        c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+        const first = await ask(c).then(text, (e: Error) => `error ${e.message}`);
+        c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+        const second = await ask(c).then(text, (e: Error) => `error ${e.message}`);
+        return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
+      },
+    },
+  ];
+}

package/src/clients/anthropic.ts

@@ -0,0 +1,4 @@
+// Anthropic's Messages through its own SDK (@anthropic-ai/sdk), the shared Messages cases.
+import { messagesCases } from './anthropic-messages.ts';
+
+export const cases = messagesCases({ key: 'ANTHROPIC_API_KEY', base: (host) => `https://${host}`, model: 'claude-sonnet-4-5', toolTurn: { toolUses: [{ name: 'lookup', input: {} }] } });