@volter/twin-standard 1.0.0

package/src/protocol-3.ts

@@ -0,0 +1,617 @@
+// Protocol 3, the derived pack (docs/contributing/architecture.md, "Protocol 3: the derived pack", "Pack layout",
+// "The report", "The grade"): its criteria, each recomputed from the tree with no network and no clock.
+//
+// Version 1 checks what the repository's tools can decide today. Criteria the grade section names that no tool
+// decides yet (a credential stored as issued; hollow capabilities; the invariants row) are listed in PLANNED and
+// counted in no grade until a version of this standard checks them.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import ts from 'typescript';
+import { fileURLToPath } from 'node:url';
+import { sharingLanesIn } from './lanes.ts';
+import type { Criterion, GradeUnit, Standard } from './types.ts';
+
+/** The lanes over the unit's vendor's state, when the unit is one of them ("Pack layout"), else none: a lane over its
+ *  vendor's state takes the vendor's states, shared helpers, manifest and engine from the vendor's src/, and nothing of
+ *  another lane. */
+function vendorLanes(unit: GradeUnit): string[] {
+  if (!unit.name.includes('/')) return [];
+  const pkg = dirname(unit.dir);
+  const lanes = sharingLanesIn(pkg, basename(pkg));
+  return lanes.includes(basename(unit.dir)) ? lanes : [];
+}
+/** Whether `from` (relative to `depth` directories under the lane) names the vendor's `rest` of its src/. */
+function vendorPath(unit: GradeUnit, from: string, depth: number, rest: RegExp): boolean {
+  if (!vendorLanes(unit).length) return false;
+  const m = new RegExp(`^${'\\.\\./'.repeat(depth)}src/(.+)$`).exec(from);
+  return m !== null && rest.test(m[1]!);
+}
+
+const pass = (reason: string) => ({ pass: true, reason });
+const fail = (reason: string) => ({ pass: false, reason });
+const sha256 = (bytes: Uint8Array | string) => createHash('sha256').update(bytes).digest('hex');
+const readJson = (path: string): unknown => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return undefined; } };
+
+/** What spec/ holds beside the vendored documents: provenance, corrections, the grouping, the examples index, recordings. */
+const SPEC_METADATA = /^(SOURCE\.md|sources\.json|patches\.json|grouping\.json|doc-examples\.json|README\.md|[^/]*\.sha256|recordings\/.*)$/;
+/** A tool in spec/ is not a vendored document (it belongs in scripts/): named by the layout criterion, never hashed. */
+const SPEC_TOOL = /\.(py|sh|ts|js|mjs|cjs|rb)$/;
+/** The vendored documents: every file under spec/ that is not its metadata. */
+function specFiles(unit: GradeUnit): string[] {
+  const dir = join(unit.dir, 'spec');
+  return filesUnder(dir).filter((f) => !SPEC_METADATA.test(f) && !SPEC_TOOL.test(f)).map((f) => join(dir, f));
+}
+
+/** Every file under a directory git does not ignore, relative to it (the checkout's tree, never runtime state). */
+function filesUnder(dir: string, base = dir): string[] {
+  if (!existsSync(dir)) return [];
+  // tracked and not-yet-added files alike (T0 runs before the commit); ignored runtime state (.volter) never
+  const run = spawnSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard', '--', '.'], { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] });
+  const tracked = run.status === 0 ? [...new Set(String(run.stdout).split('\0').filter(Boolean))] : [];
+  return tracked.map((f) => relative(base, join(dir, f))).filter((f) => existsSync(join(base, f)));
+}
+/** Every file under a directory, tracked or not (a directory the grader itself wrote). */
+function allFilesUnder(dir: string, base = dir): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) out.push(...allFilesUnder(path, base));
+    else out.push(relative(base, path));
+  }
+  return out;
+}
+/** The tracked entries directly inside a directory. */
+function entriesOf(dir: string): string[] {
+  return [...new Set(filesUnder(dir).map((f) => f.split('/')[0]!))].sort();
+}
+
+/** "Pack layout"'s closed list (architecture.md). A lane's package files and serve factory are its vendor's. */
+const LAYOUT_DIRS = new Set(['generated', 'semantics', 'engine', 'screens']);
+const PACKAGE_FILES = new Set(['README.md', 'package.json', 'LICENSE', 'CHANGELOG.md', 'tsconfig.json', 'tsconfig.build.json', 'gate.ts', 'census.json', 'vendor']);
+const TEST_FILE = /\.(test|uitest)\.tsx?$|\.d\.ts$/;
+const own = (unit: GradeUnit) => unit.name.split('/').at(-1)!;
+/** The standard's own derivation (./derive.ts): every grader derives the same way, whatever repository it grades. */
+const DERIVE = fileURLToPath(new URL(`./derive${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+/** The npm package a unit is in: the pack, or a lane's vendor. */
+const packageOf = (unit: GradeUnit): string => (unit.name.includes('/') ? dirname(unit.dir) : unit.dir);
+const isLane = (unit: GradeUnit) => unit.name.includes('/');
+/** The fixed names at src/'s root ("Pack layout"); a lane's serve factory and bin are its vendor's. */
+function srcFileInForm(unit: GradeUnit, name: string): boolean {
+  if (name.endsWith('.d.ts')) return true; // the types of a vendor SDK the pack's tests drive
+  return (isLane(unit) ? ['manifest.ts', 'index.ts', 'fetch.ts', 'budget.ts'] : ['manifest.ts', 'index.ts', 'cli.ts', 'fetch.ts', 'server.ts', 'budget.ts']).includes(name);
+}
+/** The fixed files of semantics/ besides the families' handler files and their tests. */
+const SEMANTICS_FIXED = new Set(['states.ts', 'index.ts', 'shared.ts', 'doors.ts', 'seed.ts', 'around.ts', 'events.ts', 'clock.ts', 'tenant.ts', 'scenario.ts', 'gap.ts', 'graphql.ts', 'sockets.ts']);
+/** journeys/'s closed set. */
+const JOURNEY_FILES = new Set(['customer-life.outline.md', 'customer-life.outline.verdict.json', 'customer-life.json', 'customer-life.verdict.json', 'decisions.json',
+  'vendor-examples.json', 'vendor-examples.verdict.json', 'demand.json', 'unreachable.json', 'score.json', 'coverage.json',
+  // a generative pack's life names the World's scenario it walks under (architecture, "Writing a life")
+  'scenario.json']);
+/** Entries at the unit's root the form does not name (a vendor's lanes are units of their own). */
+function rootOutsideForm(unit: GradeUnit): string[] {
+  return entriesOf(unit.dir).filter((name) => {
+    if (['spec', 'journeys', 'src'].includes(name)) return false;
+    if (existsSync(join(unit.dir, name, 'src', 'manifest.ts'))) return false;
+    return isLane(unit) || !(PACKAGE_FILES.has(name) || name === `${own(unit)}-spec-census.json`);
+  });
+}
+
+/** Source with its comments removed (a comment naming process.env reads nothing). */
+function stripComments(text: string): string {
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"`\\])\/\/.*$/gm, '$1');
+}
+
+/** Why there is no report: no life to walk, or a walk that failed. */
+function noReport(unit: GradeUnit): string {
+  if (unit.walkError) return `the walk failed: ${unit.walkError}`;
+  return existsSync(join(unit.dir, 'journeys', 'customer-life.json')) ? 'the customer life was not walked (no report given)' : 'no journeys/customer-life.json';
+}
+
+/** An operation's family: the first segment of its path after a version (`/v1/organizations/{id}` is `organizations`), a
+ *  dotted RPC method's first part (`chat.postMessage` is `chat`), a line command's name (architecture, "Pack layout"). */
+function familyOf(path: string): string {
+  // the interim rule ("What an author writes"), until derive-pack writes the spec's own grouping on each operation
+  const segs = path.split('/').filter((x) => x && !/^v?\d+(\.\d+)?$|^\d{4}-\d{2}-\d{2}$/.test(x) && !x.startsWith('{'));
+  if (!segs.length) return 'operations'; // named in a header: every path is `/`
+  const first = segs[0]!;
+  const bare = first.replace(/^\.+/, ''); // `/.well-known/...` is the family `well-known`
+  return (bare.includes('.') ? bare.split('.')[0]! : bare).replace(/[^A-Za-z0-9_-]/g, '-');
+}
+
+/** What no handler, helper or awaited manifest function may reach ("What an author writes, and how"). */
+const FORBIDDEN_REACH: ReadonlyArray<readonly [RegExp, string]> = [
+  [/\bMath\.random\b|\bcrypto\.(randomUUID|getRandomValues|subtle)\b|\brandomBytes\b|\brandomUUID\b/, 'randomness or an unmarked cipher'],
+  [/\bDate\.now\b|\bnew Date\(\s*\)|(^|[^.\w])Date\(\s*\)|\bperformance\.now\b/m, 'the wall clock'],
+  [/\bprocess\.env\b|\bBun\.env\b|\bDeno\.env\b/, 'the environment'],
+  [/(^|[^\w])fetch\s*\(|\bXMLHttpRequest\b|\bnode:(net|http|https|tls|dgram)\b/m, 'the network'],
+  [/\bimport\s*\(|\brequire\s*\(/, 'a module loaded at run time'],
+  [/\bctx\.(now|core|atomically|tree|writeDetailed)\b|\}\s*=\s*ctx\b|\bctx\s*\[/, 'a context member outside the contract, or the context taken apart'],
+  [/\bSemanticsContext\b|\bSemantics\b|\bsemanticsContext\b/, "the kernel's wide context (a handler is typed Handler, over HandlerContext; a lane reaches its vendor's through ctx.over)"],
+];
+/** A handler's name for an operationId: the id with every character a JavaScript name cannot hold made `_`, and a
+ *  leading digit prefixed with `_` (`pulls/create` is `pulls_create`) ("What an author writes, and how"). */
+const RESERVED = new Set(['break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null', 'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof', 'var', 'void', 'while', 'with', 'yield', 'let', 'static', 'implements', 'interface', 'package', 'private', 'protected', 'public', 'await']);
+export const handlerName = (operationId: string): string => {
+  const name = operationId.replace(/[^A-Za-z0-9_$]/g, '_').replace(/^(\d)/, '_$1');
+  // a name JavaScript reserves (an operation named `delete`) takes a trailing `_`
+  return RESERVED.has(name) ? `${name}_` : name;
+};
+
+/** The unit's operations by id, with their family, from its generated surface. */
+function operationsOf(unit: GradeUnit): Map<string, string> {
+  const surface = readJson(join(unit.dir, 'src', 'generated', 'surface.gen.json')) as { operations?: Array<{ id: string; path: string; family?: string }> } | undefined;
+  return new Map((surface?.operations ?? []).map((o) => [o.id, o.family ?? familyOf(o.path)]));
+}
+
+function report(unit: GradeUnit) {
+  return unit.report;
+}
+
+const criteria: Criterion[] = [
+  // ── form ─────────────────────────────────────────────────────────────────────────────────────
+  {
+    id: 'spec-vendored', section: 'form',
+    asks: "the vendor's spec vendored under spec/ with SOURCE.md",
+    check(unit) {
+      const files = specFiles(unit);
+      if (!files.length) return fail('no vendored spec under spec/ (openapi, smithy, discovery, asyncapi or an RFC)');
+      if (!existsSync(join(unit.dir, 'spec', 'SOURCE.md'))) return fail('spec/SOURCE.md is missing');
+      return pass(files.length > 4 ? `${files.length} documents` : files.map((f) => relative(join(unit.dir, 'spec'), f)).join(', '));
+    },
+  },
+  {
+    id: 'spec-hash', section: 'form',
+    asks: "SOURCE.md's sha256 matches the vendored bytes",
+    check(unit) {
+      const files = specFiles(unit);
+      const source = existsSync(join(unit.dir, 'spec', 'SOURCE.md')) ? readFileSync(join(unit.dir, 'spec', 'SOURCE.md'), 'utf8') : '';
+      const sidecars = filesUnder(join(unit.dir, 'spec')).filter((f) => f.endsWith('.sha256')).map((f) => readFileSync(join(unit.dir, 'spec', f), 'utf8')).join('\n');
+      const stated = new Set(((source + sidecars).match(/\b[0-9a-f]{64}\b/g) ?? []));
+      if (!files.length || !stated.size) return fail(!files.length ? 'no vendored spec' : 'neither SOURCE.md nor a .sha256 beside the spec states a sha256');
+      const unmatched = files.filter((f) => {
+        const bytes = readFileSync(f);
+        const hashes = [sha256(bytes)];
+        if (f.endsWith('.gz')) { try { hashes.push(sha256(gunzipSync(bytes))); } catch { /* not gzip */ } }
+        return !hashes.some((h) => stated.has(h));
+      });
+      return unmatched.length ? fail(`no stated sha256 matches ${unmatched.map((f) => basename(f)).join(', ')}`) : pass('matches');
+    },
+  },
+  {
+    id: 'spec-patches', section: 'form',
+    asks: 'every correction to the spec carries its reason and its source',
+    check(unit) {
+      const path = join(unit.dir, 'spec', 'patches.json');
+      // a criterion whose premise is absent is not met: no spec, no corrections to judge
+      if (!specFiles(unit).length) return fail('no vendored spec');
+      if (!existsSync(path)) return pass('no corrections');
+      const doc = readJson(path) as { patches?: Array<{ why?: string; source?: { url?: string; spec?: string } }> } | undefined;
+      const patches = doc?.patches;
+      if (!Array.isArray(patches)) return fail('spec/patches.json is not { patches: [...] }');
+      const bare = patches.filter((p) => !p.why || !(p.source?.url || p.source?.spec || /https?:\/\//.test(p.why))).length;
+      return bare ? fail(`${bare} of ${patches.length} corrections lack a reason or a source`) : pass(`${patches.length} corrections, each sourced`);
+    },
+  },
+  {
+    id: 'manifest', section: 'form',
+    asks: 'src/manifest.ts: the facts no spec carries, its resources and state machines',
+    check(unit) {
+      return existsSync(join(unit.dir, 'src', 'manifest.ts')) ? pass('present') : fail('src/manifest.ts is missing');
+    },
+  },
+  {
+    id: 'derived-reproducible', section: 'form',
+    asks: 'derive-pack regenerates src/generated/ byte for byte',
+    check(unit) {
+      const gen = join(unit.dir, 'src', 'generated');
+      if (!existsSync(gen)) return fail('src/generated/ is missing');
+      // derive into a directory of its own and compare: the pack's tree is never written
+      const tmp = mkdtempSync(join(tmpdir(), 'grade-derive-'));
+      let run, changed: string[];
+      try {
+        run = spawnSync(process.execPath, [DERIVE, unit.dir, '--out', tmp], { cwd: unit.dir, stdio: ['ignore', 'pipe', 'pipe'], timeout: 300_000 });
+        const before = filesUnder(gen), after = allFilesUnder(tmp);
+        changed = [...new Set([...before, ...after])].sort().filter((f) => !before.includes(f) || !after.includes(f) || !readFileSync(join(gen, f)).equals(readFileSync(join(tmp, f))));
+      } finally {
+        rmSync(tmp, { recursive: true, force: true });
+      }
+      // the pack's own path and the scratch directory are this checkout's, not the pack's: the verdict names neither, so
+      // a standing written from one checkout reads the same from any other
+      if (run.status !== 0) return fail(`derive-pack refused: ${String(run.stderr || run.stdout).split(unit.dir).join('.').split(tmp).join('<out>').trim().split('\n').slice(-2).join(' ').slice(0, 200)}`);
+      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: '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",
+    async check(unit) {
+      const src = join(unit.dir, 'src');
+      if (!existsSync(src)) return fail('src/ is missing');
+      const families = new Set(operationsOf(unit).values());
+      const outside = [
+        ...rootOutsideForm(unit),
+        ...filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f)).map((f) => `spec/${f}`),
+        ...entriesOf(src).filter((name) => statSync(join(src, name)).isDirectory() ? !LAYOUT_DIRS.has(name) : !srcFileInForm(unit, name)).map((n) => `src/${n}`),
+        ...filesUnder(join(src, 'semantics')).filter((f) => {
+          if (f.includes('/')) return true;
+          const stem = f.replace(/\.test\.tsx?$/, '').replace(/\.tsx?$/, '');
+          return !(SEMANTICS_FIXED.has(f) || SEMANTICS_FIXED.has(`${stem}.ts`) || (families.has(stem.replace(/-ops$/, '')) && /\.(test\.)?ts$/.test(f)));
+        }).map((f) => `src/semantics/${f}`),
+        // a lane over its vendor's state has no journeys of its own: the vendor's life walks it ("Pack layout")
+        ...filesUnder(join(unit.dir, 'journeys')).filter((f) => vendorLanes(unit).length > 0 || !JOURNEY_FILES.has(f)).map((f) => `journeys/${f}`),
+      ];
+      // screens/: one file per screen the manifest declares, named by its id
+      if (existsSync(join(src, 'screens'))) {
+        let ids = new Set<string>();
+        try {
+          const m = ((await import(join(src, 'manifest.ts'))) as { manifest?: { screens?: Array<{ id: string }> } }).manifest;
+          ids = new Set((m?.screens ?? []).map((x) => x.id));
+        } catch { /* a manifest that does not load fails manifest-data and states-module */ }
+        // screens/shared.tsx: what two or more of the pack's screens share (its page shell, its skin), itself no screen
+        outside.push(...filesUnder(join(src, 'screens')).filter((f) => !/^shared\.tsx?$/.test(f) && (!ids.has(f.replace(/\.(ui)?test\.tsx?$/, '').replace(/\.tsx?$/, '')) || f.includes('/'))).map((f) => `src/screens/${f}`));
+      }
+      const fetchFile = join(src, 'fetch.ts');
+      if (!existsSync(fetchFile)) outside.push('(no src/fetch.ts)');
+      else if (!/\bcreatePackFetch\s*\(/.test(readFileSync(fetchFile, 'utf8'))) outside.push('(src/fetch.ts builds no createPackFetch)');
+      // a screen's one answer is `screen(ctx)`, which the kernel calls for its host and path
+      for (const f of existsSync(join(src, 'screens')) ? filesUnder(join(src, 'screens')).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x) && !/^shared\.tsx?$/.test(x)) : []) {
+        const names = [...stripComments(readFileSync(join(src, 'screens', f), 'utf8')).matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)|^export\s+(?:const|let|var|class)\s+([A-Za-z0-9_$]+)|^export\s*\{/gm)].map((m) => m[1] ?? m[2] ?? '{…}');
+        if (names.join() !== 'screen') outside.push(`(src/screens/${f} exports ${names.join(', ') || 'nothing'}, not only screen)`);
+      }
+      return outside.length ? fail(`${outside.length} outside the form: ${outside.slice(0, 8).join(', ')}${outside.length > 8 ? ` and ${outside.length - 8} more` : ''}`) : pass('the layout exactly');
+    },
+  },
+  {
+    id: 'handler-contract', section: 'form',
+    asks: 'every file in semantics/ reaches no randomness, clock, environment, network or module but the kernel, the states and the shared helpers; each handler file is its family\'s and exports only its operations, named by the fixed rule',
+    check(unit) {
+      const dir = join(unit.dir, 'src', 'semantics');
+      if (!existsSync(dir)) return pass('no handlers');
+      const ops = operationsOf(unit);
+      const families = new Set(ops.values());
+      const found: string[] = [];
+      for (const f of filesUnder(dir).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x))) {
+        const text = stripComments(readFileSync(join(dir, f), 'utf8'));
+        const raw = readFileSync(join(dir, f), 'utf8');
+        // a stopgap awaiting a kernel mechanism is not the contract: the mechanism is built, then the handler written
+        if (/\/\/\s*awaiting:/.test(raw)) found.push(`${f} awaits a kernel mechanism (an awaiting: marker)`);
+        // every file of semantics/, the fixed ones included: what no handler may reach, no helper may either
+        for (const [pattern, what] of FORBIDDEN_REACH) {
+          if (pattern.test(text)) found.push(`${f} reaches ${what}`);
+        }
+        for (const m of text.matchAll(/^\s*import\s+(?:[^'"]*\sfrom\s+)?['"]([^'"]+)['"]/gm)) {
+          const from = m[1]!;
+          const mapImport = f === 'index.ts' && /^\.\/[A-Za-z0-9_-]+\.ts$/.test(from); // the handler map names its families' handlers
+          // the pack's engine slot (src/engine/), itself held to the pack contract (kernel-contract): a handler computes with it
+          const engineModule = /^\.\.\/engine\/[A-Za-z0-9_-]+\.ts$/.test(from) || vendorPath(unit, from, 3, /^engine\/[A-Za-z0-9_-]+\.ts$/);
+          // a lane over its vendor's state takes the vendor's states and shared helpers ("Pack layout")
+          const vendorShared = vendorPath(unit, from, 3, /^(semantics\/(states|shared)|manifest)\.ts$/);
+          if (from !== '@volter/world-core' && !/^\.\/(states|shared)\.ts$/.test(from) && !mapImport && !engineModule && !vendorShared) found.push(`${f} imports ${from}`);
+        }
+        // the handler map is typed over the narrow context, so the compiler holds every handler it names to the contract
+        if (f === 'index.ts' && !/:\s*Record<\s*string\s*,\s*Handler\s*>/.test(text)) found.push('index.ts does not type its handler map Record<string, Handler>');
+        if (['states.ts', 'index.ts', 'shared.ts', 'seed.ts'].includes(f)) continue;
+        const isDoors = f === 'doors.ts';
+        if (f === 'events.ts') {
+          const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          // a vendor whose API has a family named `events` (Polar's usage events) keeps that family's handlers here too,
+          // beside the webhook renderer; `values` is an event's further envelope values (world-core's EventValues)
+          const extra = names.filter((n) => n !== 'data' && n !== 'values');
+          const own = families.has('events') ? extra.filter((n) => ops.get([...ops.keys()].find((id) => handlerName(id) === n) ?? '') === 'events') : [];
+          if (!names.includes('data') && !own.length) found.push(`events.ts exports ${names.join(', ') || 'nothing'}, not data`);
+          const stray = extra.filter((n) => !own.includes(n));
+          if (stray.length) found.push(`events.ts exports ${stray.join(', ')}, neither data, values nor the events family's operations`);
+          continue;
+        }
+        if (f === 'clock.ts') {
+          const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'clock' || /^export\s+(const|let|var|class)\s|^export\s*\{/m.test(text)) found.push(`clock.ts exports ${names.join(', ') || 'nothing'}, not only clock`);
+          continue;
+        }
+        if (f === 'around.ts') {
+          const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'around') found.push(`around.ts exports ${names.join(', ') || 'nothing'}, not only around`);
+          continue;
+        }
+        if (f === 'scenario.ts') {
+          const names = [...text.matchAll(/^export\s+(?:const|let|var|function|async\s+function)\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'scenario' || /^export\s*\{/m.test(text)) found.push(`scenario.ts exports ${names.join(', ') || 'nothing'}, not only scenario`);
+          continue;
+        }
+        if (f === 'graphql.ts') {
+          // the GraphQL wire's resolvers (world-core graphql-wire.ts): `graphql`, and nothing else
+          const names = [...text.matchAll(/^export\s+(?:const|let|var|function|async\s+function)\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'graphql' || /^export\s*\{/m.test(text)) found.push(`graphql.ts exports ${names.join(', ') || 'nothing'}, not only graphql`);
+          continue;
+        }
+        if (f === 'sockets.ts') {
+          // the manifest's sockets (world-core sockets.ts): one exported engine per socket id, and nothing else
+          if (/^export\s+(?:async\s+)?function\s|^export\s+(let|var|class)\s|^export\s*\{/m.test(text)) found.push('sockets.ts exports otherwise than one const engine per socket');
+          continue;
+        }
+        if (f === 'gap.ts') {
+          const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'gap' || /^export\s+(const|let|var|class)\s|^export\s*\{/m.test(text)) found.push(`gap.ts exports ${names.join(', ') || 'nothing'}, not only gap`);
+          continue;
+        }
+        if (f === 'tenant.ts') {
+          const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'tenant' || /^export\s+(const|let|var|class)\s|^export\s*\{/m.test(text)) found.push(`tenant.ts exports ${names.join(', ') || 'nothing'}, not only tenant`);
+          continue;
+        }
+        const family = f.replace(/\.tsx?$/, '').replace(/-ops$/, '');
+        if (!isDoors && (f.includes('/') || !families.has(family))) { found.push(`${f} is no family of the spec`); continue; }
+        if (/^export\s*\{/m.test(text) || /^export\s+(const|let|var|class)\s/m.test(text)) found.push(`${f} exports otherwise than one function per operation`);
+        if (isDoors) continue; // a door is named by its door, declared in the manifest
+        for (const m of text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)) {
+          const name = m[1]!;
+          const op = [...ops.keys()].find((id) => handlerName(id) === name);
+          if (!op) found.push(`${f} exports ${name}, which names no operation of the spec`);
+          else if (ops.get(op) !== family) found.push(`${f} exports ${name}, an operation of ${ops.get(op)}`);
+        }
+      }
+      const note = '';
+      return found.length ? fail(`${found.length}: ${found.slice(0, 6).join('; ')}${found.length > 6 ? ` and ${found.length - 6} more` : ''}${note}`) : pass(`every file of semantics/ holds to the contract${note}`);
+    },
+  },
+  {
+    id: 'engine-pure', section: 'form',
+    asks: "src/engine/ is the vendor's computation and nothing else: no context, no state read or written, no answer made, nothing of semantics/, screens/ or the manifest reached, and none of what no handler may reach",
+    check(unit) {
+      const dir = join(unit.dir, 'src', 'engine');
+      if (!existsSync(dir)) return pass('the pack has no engine');
+      const found: string[] = [];
+      for (const f of filesUnder(dir).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x))) {
+        const text = stripComments(readFileSync(join(dir, f), 'utf8'));
+        // what a handler does belongs to a handler (semantics/<family>.ts, shared.ts), where the handler contract holds it
+        if (/\b(HandlerContext|WriteHookContext|SemanticsContext)\b/.test(text)) found.push(`${f} takes a context`);
+        if (/\bnew\s+Response\s*\(|\bResponse\.(json|redirect|error)\s*\(/.test(text)) found.push(`${f} makes an answer`);
+        for (const from of ts.preProcessFile(readFileSync(join(dir, f), 'utf8'), true, true).importedFiles.map((i) => i.fileName)) {
+          if (/^\.\.\/(semantics|screens)\/|^\.\.\/manifest\.ts$|^\.\.\/fetch\.ts$/.test(from)) found.push(`${f} imports ${from}`);
+        }
+        for (const [re, what] of FORBIDDEN_REACH) if (re.test(text)) found.push(`${f} reaches ${what}`);
+      }
+      return found.length ? fail(`${found.length}: ${found.slice(0, 6).join('; ')}${found.length > 6 ? ` and ${found.length - 6} more` : ''}`) : pass('the engine is computation only');
+    },
+  },
+  {
+    id: 'kernel-contract', section: 'form',
+    asks: "every file of src/ imports the kernel through its root, the pack contract, and nothing past it: no `@volter/world-core/runtime` or other entry (cli.ts alone takes args and lifecycle), no node builtin, no other package but @volter/world-ui",
+    check(unit) {
+      const src = join(unit.dir, 'src');
+      if (!existsSync(src)) return fail('src/ is missing');
+      const found: string[] = [];
+      for (const f of filesUnder(src).filter((x) => /\.tsx?$/.test(x) && !TEST_FILE.test(x) && !x.startsWith('generated/'))) {
+        // the file's imports, re-exports and dynamic imports as TypeScript reads them (a string that only reads like one,
+        // an error message's "from '<name>'", is none)
+        const specifiers = ts.preProcessFile(readFileSync(join(src, f), 'utf8'), true, true).importedFiles.map((i) => i.fileName);
+        for (const from of specifiers) {
+          if (from.startsWith('.')) continue;
+          if (from === '@volter/world-core' || from === '@volter/world-ui') continue;
+          if (f === 'cli.ts' && (from === '@volter/world-core/args' || from === '@volter/world-core/lifecycle')) continue;
+          found.push(`${f} imports ${from}`);
+        }
+      }
+      return found.length ? fail(`${found.length}: ${found.slice(0, 6).join('; ')}${found.length > 6 ? ` and ${found.length - 6} more` : ''}`) : pass('every file imports only the pack contract');
+    },
+  },
+  {
+    id: 'manifest-data', section: 'form',
+    asks: 'the manifest is data: its imports and one exported manifest object literal, with no function in it',
+    check(unit) {
+      const path = join(unit.dir, 'src', 'manifest.ts');
+      if (!existsSync(path)) return fail('src/manifest.ts is missing');
+      // parsed, not matched: the file's top-level statements and every function inside its object
+      const file = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+      const found: string[] = [];
+      let exported = 0;
+      for (const st of file.statements) {
+        if (ts.isImportDeclaration(st)) {
+          const from = (st.moduleSpecifier as ts.StringLiteral).text;
+          const vendorStates = vendorPath(unit, from, 2, /^semantics\/states\.ts$/);
+          if (from !== '@volter/world-core' && from !== './semantics/states.ts' && from !== './semantics/shared.ts' && from !== './semantics/events.ts' && !vendorStates) found.push(`imports ${from}`);
+          continue;
+        }
+        if (ts.isTypeAliasDeclaration(st) || ts.isInterfaceDeclaration(st)) continue;
+        const isManifest = ts.isVariableStatement(st) && st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+          && st.declarationList.declarations.length === 1 && (st.declarationList.declarations[0]!.name as ts.Identifier).text === 'manifest';
+        if (isManifest) { exported += 1; continue; }
+        // a constant that is data (a citation, a list reused across resources) is the manifest's data too
+        const isCode = (n: ts.Node): boolean => ts.isCallExpression(n) || ts.isNewExpression(n) || ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isTaggedTemplateExpression(n) || ts.isGetAccessor(n) || ts.isSetAccessor(n) || ts.forEachChild(n, isCode) === true;
+        if (ts.isVariableStatement(st) && !st.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+          && st.declarationList.declarations.every((d) => d.initializer && !isCode(d.initializer))) continue;
+        found.push(`a top-level ${ts.SyntaxKind[st.kind]} beside the manifest (${st.getText().slice(0, 40).replace(/\s+/g, ' ')}…)`);
+      }
+      if (exported !== 1) found.push('no single exported manifest');
+      const visit = (node: ts.Node): void => {
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node)) {
+          // no function in the data: what a manifest cannot state as data (a write hook, who is calling) is a kernel
+          // mechanism not yet built, never a function beside the facts
+          const prop = ts.isPropertyAssignment(node.parent) ? node.parent : ts.isMethodDeclaration(node) ? node : undefined;
+          const key = prop && ts.isIdentifier(prop.name) ? prop.name.text : undefined;
+          found.push(`a function at ${key ?? 'an unnamed place'}`);
+          return;
+        }
+        if (ts.isGetAccessor(node) || ts.isSetAccessor(node) || ts.isTaggedTemplateExpression(node)) {
+          found.push('an accessor or a tagged template, code in the data');
+          return;
+        }
+        if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+          found.push(`a call in the data (${node.getText().slice(0, 30).replace(/\s+/g, ' ')}…)`);
+          return;
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(file);
+      return found.length ? fail([...new Set(found)].slice(0, 6).join('; ')) : pass('data');
+    },
+  },
+  {
+    id: 'states-module', section: 'form',
+    asks: 'every state machine and state ruling in src/semantics/states.ts (`export const states`), each resource\'s taken whole by the manifest',
+    async check(unit) {
+      // read by loading the modules, not their text: a machine built by a helper or named otherwise is still found
+      const manifestPath = join(unit.dir, 'src', 'manifest.ts');
+      const statesPath = join(unit.dir, 'src', 'semantics', 'states.ts');
+      let manifest: { resources?: Record<string, { state?: unknown; notState?: unknown }> } | undefined;
+      try { manifest = ((await import(manifestPath)) as { manifest?: typeof manifest }).manifest; } catch (e) { return fail(`manifest.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      const resources = Object.entries(manifest?.resources ?? {});
+      const ruled = resources.filter(([, r]) => (r.state && Object.keys(r.state as object).length) || (Array.isArray(r.notState) && r.notState.length));
+      if (!ruled.length) return pass('the pack declares no state machine and rules no candidate');
+      if (!existsSync(statesPath)) return fail(`${ruled.length} resources carry states or rulings, and there is no semantics/states.ts`);
+      let states: Record<string, { state?: unknown; notState?: unknown }> | undefined;
+      try { states = ((await import(statesPath)) as { states?: typeof states }).states; } catch (e) { return fail(`semantics/states.ts does not load: ${(e as Error).message.slice(0, 120)}`); }
+      if (!states) return fail('semantics/states.ts exports no `states`');
+      const off = ruled.filter(([name, r]) => (r.state !== undefined && r.state !== states![name]?.state) || (r.notState !== undefined && r.notState !== states![name]?.notState)).map(([name]) => name);
+      return off.length ? fail(`resources whose states or rulings are not states.ts's own: ${off.join(', ')}`) : pass(`${ruled.length} resources, their states and rulings from states.ts`);
+    },
+  },
+  {
+    id: 'no-env-on-serve-path', section: 'form',
+    asks: "the form's source reads no environment variable (cli, budget and tests aside)",
+    check(unit) {
+      const src = join(unit.dir, 'src');
+      const readers = filesUnder(src).filter((f) => /\.tsx?$/.test(f) && !TEST_FILE.test(f) && !/(^|\/)(cli|[a-z0-9-]+-cli|[a-z0-9-]+-budget)\.ts$/.test(f))
+        .filter((f) => /\bprocess\.env\b|\bBun\.env\b|\bDeno\.env\b/.test(stripComments(readFileSync(join(src, f), 'utf8'))));
+      return readers.length ? fail(`reads the environment: ${readers.slice(0, 6).join(', ')}`) : pass('none');
+    },
+  },
+  {
+    // it reads the walked life's report, so it is proof, never form (the form is what a reading of the tree decides)
+    id: 'no-dead-code', section: 'proof',
+    asks: 'no file kept whose every declaration is recorded unreachable',
+    check(unit) {
+      if (!unit.report) return fail(noReport(unit));
+      const u = readJson(join(unit.dir, 'journeys', 'unreachable.json')) as { code?: Array<{ file: string; declarations?: string[] }> } | undefined;
+      const src = join(unit.dir, 'src');
+      const dead = (u?.code ?? []).filter((entry) => {
+        const path = join(src, entry.file);
+        if (!existsSync(path) || !entry.declarations?.length) return false;
+        const declared = [...readFileSync(path, 'utf8').matchAll(/^export\s+(?:async\s+)?(?:function|const|class|let)\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]!);
+        if (!declared.length || !declared.every((d) => entry.declarations!.includes(d))) return false;
+        // a declaration recorded is a part of it no World runs; the file is dead only when nothing else imports it
+        const stem = entry.file.replace(/\.tsx?$/, '').split('/').at(-1)!;
+        return !filesUnder(src).some((f) => f !== entry.file && /\.tsx?$/.test(f) && !TEST_FILE.test(f)
+          && new RegExp(`from ['"][^'"]*\\b${stem}(\\.tsx?)?['"]`).test(readFileSync(join(src, f), 'utf8')));
+      }).map((e) => e.file);
+      return dead.length ? fail(`recorded wholly unreachable yet kept: ${dead.join(', ')}`) : pass('none');
+    },
+  },
+  // ── proof ────────────────────────────────────────────────────────────────────────────────────
+  {
+    id: 'outline-judged', section: 'proof',
+    asks: "the outline judged plausible by another session, the verdict naming the outline's current content",
+    check(unit) {
+      const journeys = vendorLanes(unit).length ? join(dirname(unit.dir), 'journeys') : join(unit.dir, 'journeys');
+      const outline = join(journeys, 'customer-life.outline.md');
+      const verdict = readJson(join(journeys, 'customer-life.outline.verdict.json')) as { sha256?: string; plausible?: boolean; judge?: { agent?: string; session?: string }; authors?: string[] } | undefined;
+      if (!existsSync(outline)) return fail('no journeys/customer-life.outline.md');
+      if (!verdict) return fail('no outline verdict');
+      if (verdict.sha256 !== sha256(readFileSync(outline))) return fail("the verdict names an older outline (its sha256 is not the outline's)");
+      if (!verdict.plausible) return fail('judged not plausible');
+      if (/self-judged/i.test(verdict.judge?.session ?? '')) return fail('self-judged (not a verdict)');
+      if (!verdict.judge?.agent) return fail('the verdict does not name its judge (judge.agent)');
+      if (!verdict.authors?.length) return fail('the verdict does not name the authors, so the judge is not shown to be another session');
+      if (verdict.authors.includes(verdict.judge.agent)) return fail('the judge is among the authors');
+      return pass(`plausible, judge ${verdict.judge.agent}`);
+    },
+  },
+  {
+    id: 'life-judged', section: 'proof',
+    asks: "the customer life judged plausible by another session, the verdict naming its current content",
+    check(unit) {
+      const r = report(unit);
+      if (!r) return fail(noReport(unit));
+      return r.life.verdict === 'plausible' ? pass(`${r.life.steps} steps, judge ${r.life.judge}`) : fail(`verdict: ${r.life.verdict}`);
+    },
+  },
+  {
+    id: 'life-checks', section: 'proof',
+    asks: 'every check on every step of the life holds, with no judge flag',
+    check(unit) {
+      const r = report(unit);
+      if (!r) return fail(noReport(unit));
+      if (r.failures.length || r.flags.length) return fail(`${r.failures.length} checks failing, ${r.flags.length} judge flags${r.failures[0] ? ` — first: ${r.failures[0].beat} ${r.failures[0].step.slice(0, 60)}` : ''}`);
+      return pass(`${r.life.steps} steps hold`);
+    },
+  },
+  {
+    id: 'examples', section: 'proof',
+    asks: "every example the vendor published for a served operation replayed and judged",
+    check(unit) {
+      const r = report(unit);
+      if (!r) return fail(noReport(unit));
+      return r.examples.done ? pass(r.examples.line) : fail(r.examples.line || 'not replayed');
+    },
+  },
+  {
+    id: 'coverage', section: 'proof',
+    asks: 'the life and the examples reach every hand-written line and declared move, or the pack records why no World can',
+    check(unit) {
+      const r = report(unit);
+      if (!r?.coverage) return fail(r ? 'coverage not measured' : noReport(unit));
+      const c = r.coverage.code;
+      const note = `lines ${c.run}/${c.lines} run, ${c.recorded} recorded unreachable`;
+      return r.coverage.missing ? fail(`${r.coverage.missing} missing — ${note}`) : pass(note);
+    },
+  },
+  {
+    id: 'exemptions-reasoned', section: 'proof',
+    asks: 'every line or move recorded unreachable carries its reason',
+    check(unit) {
+      const u = readJson(join(unit.dir, 'journeys', 'unreachable.json')) as { code?: Array<{ why?: string }>; state?: Array<{ why?: string }> } | undefined;
+      if (!unit.report) return fail(noReport(unit));
+      if (!u) return pass('no exemptions');
+      const all = [...(u.code ?? []), ...(u.state ?? [])];
+      const bare = all.filter((e) => !e.why?.trim()).length;
+      return bare ? fail(`${bare} of ${all.length} exemptions without a reason`) : pass(`${all.length} exemptions, each with its reason`);
+    },
+  },
+  // ── soundness ────────────────────────────────────────────────────────────────────────────────
+  {
+    id: 'typecheck', section: 'soundness', executed: true,
+    asks: "the pack typechecks",
+    check(unit) {
+      const pkg = packageOf(unit);
+      if (!existsSync(join(pkg, 'tsconfig.json'))) return fail(`${pkg} has no tsconfig.json`);
+      const tsc = () => spawnSync('bunx', ['tsc', '--noEmit', '-p', '.'], { cwd: pkg, stdio: ['ignore', 'pipe', 'pipe'], timeout: 600_000 });
+      let run = tsc();
+      if (run.status !== 0) run = tsc(); // a red is rerun once before it counts (gates, "Reading a red")
+      const errors = String(run.stdout).split('\n').filter((l) => /error TS\d+/.test(l));
+      return run.status === 0 ? pass('clean') : fail(`${errors.length} errors${errors[0] ? ` — ${errors[0].slice(0, 160)}` : ''}`);
+    },
+  },
+  {
+    id: 'suites', section: 'soundness', executed: true,
+    asks: "the pack's own tests pass",
+    check(unit) {
+      const pkg = packageOf(unit);
+      const scope = `./${relative(pkg, join(unit.dir, 'src'))}/`;
+      // T0's per-test timeout: the 5 s default goes red on a random pack under load (verify-pack.ts)
+      const suites = () => spawnSync('bun', ['test', '--timeout', '60000', scope], { cwd: pkg, stdio: ['ignore', 'pipe', 'pipe'], timeout: 900_000 });
+      let run = suites();
+      if (run.status !== 0) run = suites(); // a red is rerun once before it counts (gates, "Reading a red")
+      const out = String(run.stdout) + String(run.stderr);
+      if (/Tests need "\.test"|0 test files matching/.test(out) || /\b0 tests? across/.test(out)) return pass('no tests of its own (the life is its proof)');
+      const passed = out.match(/^\s*(\d+) pass/m)?.[1] ?? '?';
+      const failed = out.match(/^\s*(\d+) fail/m)?.[1] ?? '?';
+      return run.status === 0 ? pass(`${passed} pass`) : fail(`${failed} fail, ${passed} pass`);
+    },
+  },
+];
+
+/** Named by "The grade" and decided by no tool yet: counted in no grade until a version of this standard checks them. */
+export const PLANNED = [
+  'no handler that only does what the derived core does: its operation run through the core answering and writing the same',
+  'no credential stored as it was issued',
+  "no hollow capability beyond the gate's allowlist",
+  "the pack's row of the invariants matrix with every cell passing or not applicable",
+  "a patch's quote re-found in its stored source",
+];
+
+export const protocol3: Standard = { id: 'protocol-3', version: 3, title: 'Protocol 3: the derived pack', criteria, planned: PLANNED };