@volter/twin-standard 1.0.30 → 1.0.31

package/dist/src/archive-source.d.ts

@@ -0,0 +1,13 @@
+export type ArchiveSource = {
+    url: string;
+    sha256: string;
+    member: string;
+};
+export declare function archiveSource(locator: string): ArchiveSource | undefined;
+/** One cache per source-check run; multiple pinned members share the archive's one download. */
+export declare function archiveReader(): (source: ArchiveSource) => Promise<{
+    status: number;
+    raw: string;
+    sha256?: string;
+    error?: string;
+}>;

package/dist/src/archive-source.js

@@ -0,0 +1,176 @@
+// 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 function archiveSource(locator) {
+    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) => createHash('sha256').update(bytes).digest('hex');
+const stringAt = (bytes, start, size) => bytes.subarray(start, start + size).toString('utf8').replace(/\0.*$/s, '');
+function zipMember(bytes, member) {
+    // 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) {
+    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) {
+    const out = {};
+    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, member) {
+    let at = 0, longName, local = {}, global = {};
+    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() {
+    const downloads = new Map();
+    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/dist/src/check-sources.d.ts

@@ -3,6 +3,8 @@ export type SourceRecord = {
     status: number;
     checked: string;
     quotes?: Record<string, boolean>;
+    sha256?: string;
+    error?: string;
 };
 export type Patch = {
     op: string;
@@ -11,13 +13,14 @@ export type Patch = {
     source?: {
         url?: string;
         spec?: string;
+        recording?: string;
         quote: string;
     };
 };
 /** Every URL in a text, without trailing punctuation. */
 export declare const urlsIn: (text: string) => string[];
-/** 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 declare function handlerCitations(pkg: string): Array<{
     where: string;
     source: string;
@@ -27,7 +30,21 @@ export declare const quotedPage: (source: string) => {
     url: string;
     quote: string;
 } | undefined;
+/** Evidence is usable offline only when the page answered or the archive digest matched its pin. */
+export declare function sourceHeld(url: string, record: SourceRecord | undefined): boolean;
 /** What a pack cites: each URL, and the quotes a patch says the URL's page holds. */
 export declare function citations(pkg: string): Promise<Map<string, Set<string>>>;
 /** 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 declare function readPage(url: string): Promise<{
+    status: number;
+    text: string;
+    readable: string;
+    raw: string;
+    sha256?: string;
+    error?: string;
+}>;
 export declare function checkSources(args: string[]): Promise<void>;

package/dist/src/check-sources.js

@@ -18,27 +18,51 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 //
 // 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 } from 'node:path';
+import { dirname, join } from 'node:path';
 import { unitAt } from "./unit.js";
+import { archiveReader, archiveSource } from "./archive-source.js";
 /** Every URL in a text, without trailing punctuation. */
-export const urlsIn = (text) => (text.match(/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). */
+export const urlsIn = (text) => (text.match(/(?:archive:)?https?:\/\/[^\s"'<>]+/g) ?? []).map((u) => u.replace(/[),.;:\]]+$/, ''));
+/** 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) {
-    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 = [];
+    const walk = (dir, prefix) => {
+        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 = 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) => {
-    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, record) {
+    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) {
     const cited = new Map();
@@ -46,17 +70,24 @@ export async function citations(pkg) {
         cited.set(url, new Set()); if (quote)
         cited.get(url).add(quote); };
     const { manifest } = (await import(__rewriteRelativeImportExtension(join(pkg, 'src', 'manifest.ts'))));
-    for (const r of Object.values(manifest.resources))
+    // 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)
-                for (const u of urlsIn(String(t.source ?? '')))
-                    cite(u);
+            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);
+        // 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))
+            for (const u of urlsIn(c.source.replace(/"[^"]*"/g, '')))
                 cite(u);
     }
     const patchPath = join(pkg, 'spec', 'patches.json');
@@ -76,7 +107,40 @@ export async function citations(pkg) {
 const textOf = (html) => 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) => 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) => 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) {
+    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) => 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) {
     const vendor = args[0];
     if (!vendor) {
@@ -88,41 +152,35 @@ export async function checkSources(args) {
     const record = 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) => 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}`);
+        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/dist/src/cli.js

@@ -9,15 +9,20 @@
 //   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.js";
 import { grade, STANDARDS } from "./grade.js";
+import { withCheckoutFiles } from "./protocol-3.js";
 import { gatePublished } from "./published.js";
 const [command, ...args] = process.argv.slice(2);
 const usage = () => {
-    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);
 };
 if (command === '--version') {
@@ -79,14 +84,16 @@ 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'] } : {}) });
-        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'] } : {}) });
+            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])
@@ -100,6 +107,42 @@ else if (command === 'check-sources') {
         usage();
     await (await import("./check-sources.js")).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.js")).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.js")).conformPublished(target, at >= 0 ? { registry: args[at + 1] } : {})
+        : await (await import("./conformance.js")).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/dist/src/clients/ai-gateway.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/ai-gateway.js

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

package/dist/src/clients/anthropic-messages.d.ts

@@ -0,0 +1,10 @@
+import type { ClientCase } from './harness.js';
+/** 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 declare function messagesCases(v: MessagesVendor): ClientCase[];

package/dist/src/clients/anthropic-messages.js

@@ -0,0 +1,52 @@
+const MESSAGES = 'https://platform.claude.com/docs/en/api/messages';
+const TOOLS = [{ name: 'lookup', input_schema: { type: 'object', properties: {} } }];
+export function messagesCases(v) {
+    const SCRIPT = { handlers: [
+            { id: 'calls', on: { hasTool: 'lookup' }, respond: v.toolTurn },
+            { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
+        ] };
+    const ask = async (c, extra = {}) => {
+        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 });
+    };
+    const text = (m) => 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) => 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) => 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 ${e.message}`);
+                c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+                const second = await ask(c).then(text, (e) => `error ${e.message}`);
+                return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
+            },
+        },
+    ];
+}

package/dist/src/clients/anthropic.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/anthropic.js

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

package/dist/src/clients/aws.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];