@volter/twin-standard 1.0.0

package/dist/src/spec-patches.d.ts

@@ -0,0 +1,8 @@
+export type SpecPatch = {
+    op: string;
+    path: string;
+    from?: string;
+    value?: unknown;
+};
+/** Apply one patch to `doc` in place. */
+export declare function applySpecPatch(doc: unknown, p: SpecPatch): void;

package/dist/src/spec-patches.js

@@ -0,0 +1,24 @@
+// A pack's corrections to its vendor's spec (spec/patches.json): RFC 6902 operations (add, replace, remove, move, copy),
+// applied to the parsed spec so the vendored file stays the vendor's own bytes. derive-pack.ts applies them before the
+// IR; vendor-examples.ts reads the patched schemas, which are what the twin is derived from.
+/** Apply one patch to `doc` in place. */
+export function applySpecPatch(doc, p) {
+    const at = (pointer) => {
+        const keys = pointer.split('/').slice(1).map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~'));
+        const key = keys.pop();
+        return { parent: keys.reduce((node, k) => node[k], doc), key };
+    };
+    const read = (pointer) => { const { parent, key } = at(pointer); return parent[key]; };
+    const value = p.op === 'move' || p.op === 'copy' ? structuredClone(read(p.from)) : p.value;
+    const drop = ({ parent, key }) => (Array.isArray(parent) ? parent.splice(Number(key), 1) : delete parent[key]);
+    if (p.op === 'move')
+        drop(at(p.from));
+    const { parent, key } = at(p.path);
+    if (p.op === 'remove')
+        drop({ parent, key });
+    // into an array, `add` inserts at the index (`-` appends) and `replace` overwrites it
+    else if (Array.isArray(parent) && p.op !== 'replace')
+        parent.splice(key === '-' ? parent.length : Number(key), 0, value);
+    else
+        parent[key] = value;
+}

package/dist/src/spec.d.ts

@@ -0,0 +1,5 @@
+export { CRUD_CLASSES, fromOpenAPI, fromSmithy, fromSwagger2, slug, type SpecIR } from './spec-ir.js';
+export { discoveryToOpenAPI, fromDiscovery, isDiscovery } from './spec-ir-discovery.js';
+export type { ClientCall, ClientOpsSpec } from './spec-ir-client.js';
+export { mergeDocuments, readSpecDocuments, type SpecDocuments } from './spec-documents.js';
+export { applySpecPatch, type SpecPatch } from './spec-patches.js';

package/dist/src/spec.js

@@ -0,0 +1,7 @@
+// The spec side of the standard, for a tool that reads a vendor's spec as the derivation does (a vendor's published
+// examples replayed, a client's calls extracted): the spec IR, a Discovery document as OpenAPI, several documents as one
+// API, and a recorded patch applied.
+export { CRUD_CLASSES, fromOpenAPI, fromSmithy, fromSwagger2, slug } from "./spec-ir.js";
+export { discoveryToOpenAPI, fromDiscovery, isDiscovery } from "./spec-ir-discovery.js";
+export { mergeDocuments, readSpecDocuments } from "./spec-documents.js";
+export { applySpecPatch } from "./spec-patches.js";

package/dist/src/types.d.ts

@@ -0,0 +1,75 @@
+/** What a criterion is checked against: one unit (a pack, or one lane of a multi-API pack), read from the tree. */
+export interface GradeUnit {
+    /** `stripe`, or a lane `aws/secretsmanager` */
+    name: string;
+    /** the vendor (the pack directory's name) */
+    vendor: string;
+    /** absolute path of the unit's directory */
+    dir: string;
+    /** score-pack's report for the unit, recomputed now (null when the unit has no customer life to walk) */
+    report: ScoreReport | null;
+    /** why the walk gave no report although the unit has a life (a crash, a timeout), else undefined */
+    walkError?: string;
+}
+export interface ScoreReport {
+    vendor: string;
+    life: {
+        steps: number;
+        verdict: string;
+        judge: string | null;
+        authors: string[];
+    };
+    failures: Array<{
+        step: string;
+        beat: string;
+        detail: string;
+    }>;
+    flags: Array<{
+        pattern: string;
+        step: string;
+        detail: string;
+    }>;
+    coverage: {
+        missing: number;
+        code: {
+            lines: number;
+            run: number;
+            recorded: number;
+            missing: number;
+        };
+        state?: unknown;
+    } | null;
+    examples: {
+        done: boolean;
+        replayed?: boolean;
+        verdict?: string;
+        line: string;
+    };
+    breadth: {
+        operations: number;
+        [servedBy: string]: number;
+    };
+    missingForDone: string[];
+}
+export interface CriterionResult {
+    pass: boolean;
+    /** why it failed, or what it measured when it passed */
+    reason: string;
+}
+export interface Criterion {
+    id: string;
+    section: 'form' | 'proof' | 'soundness';
+    /** it runs the pack (typecheck, tests), so its result can vary with the machine; the rest read the tree */
+    executed?: boolean;
+    /** what it asks, in one line, for the catalog */
+    asks: string;
+    check(unit: GradeUnit): CriterionResult | Promise<CriterionResult>;
+}
+export interface Standard {
+    id: string;
+    version: number;
+    title: string;
+    criteria: Criterion[];
+    /** criteria the standard names that no tool decides yet: shown, counted in no grade */
+    planned: string[];
+}

package/dist/src/types.js

@@ -0,0 +1,4 @@
+// A standard the grader grades against (docs/contributing/architecture.md, "The grade"): its id and version, and
+// its criteria, unweighted (a grade is criteria met over criteria). The grader is one engine (./grade.ts); a new
+// protocol, or a revision of one, is another module beside this, released as a version of this package.
+export {};

package/dist/src/unit.d.ts

@@ -0,0 +1,5 @@
+/** The unit at `path`: its absolute directory and the name it is reported by. */
+export declare function unitAt(path: string): {
+    dir: string;
+    name: string;
+};

package/dist/src/unit.js

@@ -0,0 +1,14 @@
+// A unit the standard grades, named from its directory (docs/contributing/architecture.md, "The catalog: where twins come
+// from": the standard takes a pack's directory, in any repository, or an unpacked published tarball): a pack is its
+// directory's name, and a lane keeps its vendor (`cloudflare/r2`).
+import { existsSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+/** The unit at `path`: its absolute directory and the name it is reported by. */
+export function unitAt(path) {
+    const dir = resolve(path.replace(/^~/, process.env.HOME ?? '~'));
+    // a lane is a unit under its vendor's package: it has no package.json of its own, its vendor's directory does (a pack
+    // has its own, whatever its parent holds: a pack repository's root is a workspace)
+    const parent = resolve(dir, '..');
+    const lane = !existsSync(join(dir, 'package.json')) && existsSync(join(parent, 'package.json')) && existsSync(join(dir, 'spec'));
+    return { dir, name: lane ? `${basename(parent)}/${basename(dir)}` : basename(dir) };
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@volter/twin-standard",
+  "version": "1.0.0",
+  "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",
+    "protocol-3",
+    "standard",
+    "grade",
+    "catalog",
+    "openapi"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin-world.git",
+    "directory": "packages/twin-standard"
+  },
+  "homepage": "https://github.com/volter-ai/twin-world/tree/main/packages/twin-standard#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./cli": {
+      "types": "./dist/src/cli.d.ts",
+      "default": "./dist/src/cli.js"
+    },
+    "./check-sources": {
+      "types": "./dist/src/check-sources.d.ts",
+      "default": "./dist/src/check-sources.js"
+    },
+    "./spec": {
+      "types": "./dist/src/spec.d.ts",
+      "default": "./dist/src/spec.js"
+    }
+  },
+  "bin": {
+    "twin-standard": "dist/src/cli.js"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "graphql": "^16.13.2",
+    "typescript": "^5.9.0",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/check-sources.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env bun
+// check-sources — the evidence a derived pack cites, fetched (docs/contributing/architecture.md,
+// "Protocol 3", Correcting the spec and The semantics layer). Every URL a state transition's `source`,
+// a handler's `// source:` line or a spec patch's `why` names is fetched once and its answer recorded in `spec/sources.json`; a patch's
+// `quote` is looked for in the text of the page its `source` names. derive-pack reads the record offline
+// and refuses a dead source, one never checked, and a quote its page does not hold.
+//
+// Documentation pages, never a vendor's API: each is fetched at most once per run, sixteen at a time,
+// and a page already recorded as found is not fetched again (--recheck fetches everything).
+//
+// 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 { unitAt } from './unit.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 } };
+
+/** Every URL in a text, without trailing punctuation. */
+export const urlsIn = (text: string): string[] => (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 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 m = /(?:^\s*(?:\/\/|\/?\*+)|[\s;,)}\]]\/\/)\s*source:\s*(.+?)\s*(?:\*\/)?\s*$/i.exec(line);
+      return m ? [{ where: `${f}:${i + 1}`, source: m[1]! }] : [];
+    }));
+}
+
+/** 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;
+};
+
+/** 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);
+  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);
+  }
+  const patchPath = join(pkg, 'spec', 'patches.json');
+  if (existsSync(patchPath)) {
+    for (const p of (JSON.parse(readFileSync(patchPath, 'utf8')) as { patches: Patch[] }).patches) {
+      for (const u of urlsIn(p.why)) cite(u);
+      if (p.source?.url) cite(p.source.url, p.source.quote);
+    }
+  }
+  return cited;
+}
+
+// a page's characters with its markup, entities and whitespace gone, so a quote from the rendered page is
+// found in it however the page highlights or wraps it (a code example is a span per token, and an external link
+// carries an invisible U+2060 word joiner beside its icon: clerk.com/docs/webhooks/overview, "Clerk uses Svix")
+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, '');
+
+/** Fetch and record the sources the unit at `args[0]` cites (`--recheck`: every one, not only those due). */
+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); }
+  const pkg = unitAt(vendor).dir;
+  const recordPath = join(pkg, 'spec', 'sources.json');
+  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 today = new Date().toISOString().slice(0, 10);
+  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 found = Object.fromEntries([...quotes].map((q) => [q, status === 200 && text.includes(bare(q))]));
+      record[url] = { status, checked: today, ...(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);
+  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 u of unquoted) console.log(`  quote missing: ${u}`);
+}
+
+if (import.meta.main) await checkSources(process.argv.slice(2));

package/src/cli.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env bun
+// twin-standard — the Protocol 3 standard's commands, the same wherever they run (a pack repository's hook and workflow,
+// a release, the catalog's check of a submission, an author's machine):
+//
+//   twin-standard gate <pack repository> [<pack or lane dir>…]   every unit passes the form section, or exit 1
+//   twin-standard gate-published <name>@<version>… [--registry <url>]
+//                                                                  each published version passes the gate, as the catalog
+//                                                                  grades a submission (its tarball, unpacked)
+//   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 --version                                        the package's version and each standard's
+import { readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { unitsOf, p3Gate } from './gate.ts';
+import { grade, STANDARDS } from './grade.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');
+  process.exit(2);
+};
+
+if (command === '--version') {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
+  console.log(`@volter/twin-standard ${pkg.version} · ${STANDARDS.map((s) => `${s.id}@${s.version}`).join(' ')}`);
+} else if (command === 'gate') {
+  const [repoArg, ...only] = args;
+  if (!repoArg) usage();
+  const repo = resolve(repoArg!);
+  const results = await p3Gate(only.length ? only.map((u) => resolve(u)) : unitsOf(repo));
+  let blocked = 0;
+  for (const r of results) {
+    const name = relative(repo, r.unit) || r.unit;
+    if (r.failures.length) { blocked++; console.error(`✗ ${name}`); for (const f of r.failures) console.error(`    ${f}`); }
+    else console.log(`✓ ${name}`);
+  }
+  console.log(blocked ? `gate: ${blocked} of ${results.length} units are not Protocol 3; they may not be in ${repo}` : `gate: all ${results.length} units are Protocol 3`);
+  process.exit(blocked ? 1 : 0);
+} else if (command === 'gate-published') {
+  const at = args.indexOf('--registry');
+  const registry = at >= 0 ? args[at + 1] : undefined;
+  const specs = args.filter((a, i) => !a.startsWith('--') && (at < 0 || i !== at + 1));
+  if (!specs.length) usage();
+  let blocked = 0;
+  for (const spec of specs) {
+    let r;
+    try { r = await gatePublished(spec, registry ? { registry } : {}); } catch (e) { blocked++; console.error(`✗ ${spec}\n    ${(e as Error).message}`); continue; }
+    if (r.failures.length) { blocked++; console.error(`✗ ${spec}`); for (const f of r.failures) for (const x of f.failures) console.error(`    ${f.unit}: ${x}`); }
+    else console.log(`✓ ${spec}`);
+  }
+  console.log(blocked ? `gate: ${blocked} of ${specs.length} versions are not Protocol 3` : `gate: all ${specs.length} versions are Protocol 3`);
+  process.exit(blocked ? 1 : 0);
+} 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}`);
+    }
+  }
+} else if (command === 'derive') {
+  if (!args[0]) usage();
+  // the derivation is a script over process.argv: it reads the unit from its first argument
+  process.argv = [process.argv[0]!, process.argv[1]!, ...args];
+  await import('./derive.ts');
+} else if (command === 'check-sources') {
+  if (!args[0]) usage();
+  await (await import('./check-sources.ts')).checkSources(args);
+} else {
+  usage();
+}