@volter/twin-standard 1.0.30 → 1.0.31

package/src/derive.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { parseExactJson, exactInteger } from '@volter/world-core/exact-json';
 // derive — the derived-pack generator's build step (docs/contributing/architecture.md, "The derived pack"), the
 // standard's own: the grade's `derived-reproducible` runs it, so every grader derives the same way. Reads a pack's
 // vendored spec (`<pack>/spec/openapi.json[.gz]`), builds the spec IR (./spec-ir.ts) and writes the pack's
@@ -16,7 +17,7 @@ import { fromProto, protoSchema, readProtoFiles } from './spec-ir-proto.ts';
 import { fromRedisCommands, type CommandTableSpec } from './spec-ir-commands.ts';
 import { fromClientCalls, type ClientOpsSpec } from './spec-ir-client.ts';
 import { discoveryMethods, fromDiscovery, isDiscovery } from './spec-ir-discovery.ts';
-import { handlerCitations, quotedPage, type Patch, type SourceRecord, urlsIn } from './check-sources.ts';
+import { handlerCitations, quotedPage, sourceHeld, type Patch, type SourceRecord, urlsIn } from './check-sources.ts';
 import { applySpecPatch } from './spec-patches.ts';
 import { unitAt } from './unit.ts';
 import { mergeDocuments, readSpecDocuments } from './spec-documents.ts';
@@ -50,13 +51,14 @@ const text = (specPath.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('ut
 // corrects a JSON spec
 const lineProtocol = specPath.endsWith('.txt');
 const commandVersion = commandTable ? (/\*\*Version:\*\* `([^`]+)`/.exec(existsSync(join(PKG, 'spec', 'SOURCE.md')) ? readFileSync(join(PKG, 'spec', 'SOURCE.md'), 'utf8') : '')?.[1] ?? '') : '';
-let doc: any = severalDocuments ? readSpecDocuments(join(PKG, 'spec')) : commandTable ? fromRedisCommands(Object.fromEntries(readdirSync(specPath).filter((f) => f.endsWith('.json')).sort().map((f) => [f, JSON.parse(readFileSync(join(specPath, f), 'utf8'))])), commandVersion) : rpcService ? readProtoFiles(protoTree(specPath)) : lineProtocol ? fromCommandReplies(text) : /\.ya?ml(\.gz)?$/.test(specPath) ? parseYaml(text) : JSON.parse(text);
+let doc: any = severalDocuments ? readSpecDocuments(join(PKG, 'spec')) : commandTable ? fromRedisCommands(Object.fromEntries(readdirSync(specPath).filter((f) => f.endsWith('.json')).sort().map((f) => [f, parseExactJson(readFileSync(join(specPath, f), 'utf8'))])), commandVersion) : rpcService ? readProtoFiles(protoTree(specPath)) : lineProtocol ? fromCommandReplies(text) : /\.ya?ml(\.gz)?$/.test(specPath) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text);
 
 // ── the evidence the pack cites ──────────────────────────────────────────────────────────────
 // A source is a page check-sources (./check-sources.ts) fetched and recorded found (spec/sources.json), a quote
-// that page holds, or `spec:<operationId or /json/pointer> "quote"`: words of the vendored spec itself
-// (read before any patch, so a patch never vouches for itself).
-const vendored = lineProtocol || commandTable ? structuredClone(doc) : JSON.parse(text.startsWith('{') ? text : JSON.stringify(doc));
+// that page holds, `spec:<operationId or /json/pointer> "quote"`: words of the vendored spec itself (read before any
+// patch, so a patch never vouches for itself), or `recording:<file> "quote"`: words of an answer the vendor gave,
+// recorded in spec/recordings/.
+const vendored = lineProtocol || commandTable ? structuredClone(doc) : parseExactJson(text.startsWith('{') ? text : JSON.stringify(doc));
 /** An RFC's section by its number (`4.1.4`): its heading's line to the next heading's. */
 const sectionOf = (n: string): string | undefined => {
   const at = text.search(new RegExp(`^${n.replace(/\./g, '\\.')}\\.  `, 'm'));
@@ -65,7 +67,7 @@ const sectionOf = (n: string): string | undefined => {
   return next < 0 ? text.slice(at) : text.slice(at, at + 1 + next);
 };
 const sourcesPath = join(PKG, 'spec', 'sources.json');
-const recorded: Record<string, SourceRecord> = existsSync(sourcesPath) ? JSON.parse(readFileSync(sourcesPath, 'utf8')) : {};
+const recorded: Record<string, SourceRecord> = existsSync(sourcesPath) ? parseExactJson(readFileSync(sourcesPath, 'utf8')) : {};
 const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace']);
 const specOps = new Map<string, unknown>();
 // an operation by its id: the spec's operationId, or the `method_path` slug the IR mints where the spec names none (QStash)
@@ -91,8 +93,21 @@ const wordsIn = (node: unknown): string => (typeof node === 'string' ? node : no
 const bare = (s: string): string => s.replace(/\s+/g, '');
 // a JSON pointer into the spec, an operation by id, or (an RFC's) a section by number
 const specNode = (ref: string): unknown => (ref.startsWith('/') ? ref.split('/').slice(1).map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~')).reduce((n: any, k) => n?.[k], severalDocuments && !ref.startsWith('/documents/') ? pointed : vendored) : lineProtocol && /^\d+(\.\d+)*$/.test(ref) ? sectionOf(ref) : specOps.get(ref));
+/** Validate structured recording evidence before any string interpolation or page fallback. */
+function unheldRecording(name: unknown, quote: unknown): string | undefined {
+  if (typeof name !== 'string' || !/^[\w.-]+$/.test(name)) return 'recording filename is no recording (use a safe basename)';
+  if (typeof quote !== 'string' || !quote.trim()) return 'recording evidence quotes nothing (use a nonempty string)';
+  const file = join(PKG, 'spec', 'recordings', name);
+  if (!existsSync(file)) return `spec/recordings/${name} is no recording`;
+  return bare(readFileSync(file, 'utf8')).includes(bare(quote.replace(/\\"/g, '"'))) ? undefined : `spec/recordings/${name} does not hold "${quote}"`;
+}
+
 /** Why a citation does not hold, or undefined when it does. */
 function unheld(source: string): string | undefined {
+  // Malformed recording citations never fall back to a checked page.
+  const recording = /^recording:(\S+)\s+"([\s\S]*)"$/.exec(source.trim());
+  if (recording) return unheldRecording(recording[1], recording[2]);
+  if (source.trim().startsWith('recording:')) return 'malformed recording citation';
   const spec = /^spec:(\S+)\s+"([\s\S]*)"$/.exec(source.trim());
   if (spec && !spec[2]!.trim()) return `spec:${spec[1]} quotes nothing`;
   if (spec) {
@@ -100,9 +115,12 @@ function unheld(source: string): string | undefined {
     if (node === undefined) return `the spec has nothing at ${spec[1]}`;
     return bare(wordsIn(node)).includes(bare(spec[2]!.replace(/\\"/g, '"'))) ? undefined : `the spec at ${spec[1]} does not say "${spec[2]}"`;
   }
+  if (source.trim().startsWith('archive:') && !quotedPage(source)) return 'archive evidence needs a valid pinned member and quote';
+  const archiveQuote = quotedPage(source);
+  if (archiveQuote?.url.startsWith('archive:') && recorded[archiveQuote.url]?.quotes?.[archiveQuote.quote] !== true) return 'archive member does not hold its quote as recorded';
   const urls = urlsIn(source);
   if (!urls.length) return `"${source.slice(0, 60)}" names no page and no spec words`;
-  const dead = urls.filter((u) => recorded[u]?.status !== 200);
+  const dead = urls.filter((u) => !sourceHeld(u, recorded[u]));
   return dead.length ? dead.map((u) => `${u} is ${recorded[u] ? `answering ${recorded[u]!.status || 'nothing'}` : 'not checked'} (twin-standard check-sources ${vendor})`).join('; ') : undefined;
 }
 const evidence: string[] = [];
@@ -111,21 +129,22 @@ for (const c of handlerCitations(PKG)) {
   const q = quotedPage(c.source);
   // a quote is checked only in the two forms that say where it is; any other quote is refused, never passed unread
   const trimmed = c.source.trim();
-  const loose = !q && (/^spec:/.test(trimmed) ? !/^spec:\S+\s+"[\s\S]*"$/.test(trimmed) : trimmed.includes('"'));
-  const held = loose ? `"${c.source.slice(0, 60)}" quotes words in no form a check reads (\`<url> "<quote>"\` or \`spec:<ref> "<quote>"\`)` : q ? (recorded[q.url]?.quotes?.[q.quote] === true ? undefined : `${q.url} does not hold "${q.quote}" as recorded (twin-standard check-sources ${vendor})`) : unheld(c.source);
-  if (held) evidence.push(`semantics/${c.where}: ${held}`);
+  const loose = !q && (/^(spec|recording):/.test(trimmed) ? !/^(spec|recording):\S+\s+"[\s\S]*"$/.test(trimmed) : trimmed.includes('"'));
+  const held = loose ? `"${c.source.slice(0, 60)}" quotes words in no form a check reads (\`<url> "<quote>"\`, \`spec:<ref> "<quote>"\` or \`recording:<file> "<quote>"\`)` : q ? ((!q.url.startsWith('archive:') || sourceHeld(q.url, recorded[q.url])) && recorded[q.url]?.quotes?.[q.quote] === true ? undefined : `${q.url} does not hold "${q.quote}" as recorded (twin-standard check-sources ${vendor})`) : unheld(c.source);
+  if (held) evidence.push(`${c.where}: ${held}`);
 }
 // Corrections to the vendor's spec, as data: RFC 6902 operations (add, replace, remove, move, copy)
 // in spec/patches.json, applied before the IR so the vendored file stays the vendor's own bytes. Each says
 // `why`, citing what shows the vendor differs from its spec (its docs, the spec's own example, a recording).
 const patchPath = join(PKG, 'spec', 'patches.json');
 if (existsSync(patchPath)) {
-  for (const p of JSON.parse(readFileSync(patchPath, 'utf8')).patches as Array<{ op: string; path: string; from?: string; value?: unknown; why: string }>) {
+  for (const p of parseExactJson(readFileSync(patchPath, 'utf8')).patches as Array<{ op: string; path: string; from?: string; value?: unknown; why: string }>) {
     if (!p.why?.trim()) { console.error(`${vendor}: spec patch ${p.op} ${p.path} gives no why`); process.exit(1); }
     {
       const s = (p as Patch).source;
-      const held = s?.spec ? unheld(`spec:${s.spec} "${s.quote}"`)
-        : s?.url ? (recorded[s.url]?.quotes?.[s.quote] === true ? undefined : `${s.url} does not hold "${s.quote}" as recorded`)
+      const held = s?.recording !== undefined ? unheldRecording(s.recording, s.quote)
+        : s?.spec ? unheld(`spec:${s.spec} "${s.quote}"`)
+        : s?.url ? ((!s.url.startsWith('archive:') || sourceHeld(s.url, recorded[s.url])) && recorded[s.url]?.quotes?.[s.quote] === true ? undefined : `${s.url} does not hold "${s.quote}" as recorded`)
         : urlsIn(p.why).length ? unheld(p.why) : 'it cites no page and quotes nothing';
       if (held) evidence.push(`spec patch ${p.op} ${p.path}: ${held}`);
     }
@@ -174,7 +193,7 @@ const ir: SpecIR = isDiscovery(doc) ? fromDiscovery(doc) : doc?.format === 'clie
 // A spec that groups its operations by tag (Cloudflare's: nearly every path begins /accounts/{account_id}/, so the
 // path's first segment names one family for thousands of operations) says so in spec/grouping.json, `{ "by": "tag" }`:
 // each operation's family is then its first tag, as a file name (`Worker Script` is `worker-script`).
-const grouping = existsSync(join(PKG, 'spec', 'grouping.json')) ? (JSON.parse(readFileSync(join(PKG, 'spec', 'grouping.json'), 'utf8')) as { by?: string }) : {};
+const grouping = existsSync(join(PKG, 'spec', 'grouping.json')) ? (parseExactJson(readFileSync(join(PKG, 'spec', 'grouping.json'), 'utf8')) as { by?: string }) : {};
 if (grouping.by === 'tag') {
   // an operation the spec names no operationId for is found by its method and path, in the spec as corrected (an
   // operation a patch adds carries its own tags: PostHog's person delete)
@@ -193,10 +212,14 @@ if (grouping.by === 'tag') {
 const sdlPath = ['schema.graphql.gz', 'schema.graphql'].map((f) => join(PKG, 'spec', f)).find((p) => existsSync(p));
 // the GraphQL wire's root fields (`mutation.issueArchive`), which a transition may name as a REST operation is named
 const graphqlOperations = new Set<string>();
+let graphqlSchema: import('graphql').GraphQLSchema | undefined;
+let graphqlLib: typeof import('graphql') | undefined;
 if (sdlPath) {
   const { fromGraphQL } = await import('./spec-ir-graphql.ts');
   const sdl = (sdlPath.endsWith('.gz') ? gunzipSync(readFileSync(sdlPath)) : readFileSync(sdlPath)).toString('utf8');
   const gql = fromGraphQL(sdl);
+  graphqlLib = await import('graphql');
+  graphqlSchema = graphqlLib.buildSchema(sdl, { assumeValidSDL: true });
   for (const o of gql.operations) graphqlOperations.add(o.id);
   mkdirSync(out, { recursive: true });
   writeFileSync(join(out, 'graphql.gen.json'), `${JSON.stringify({ generatedBy: 'scripts/derive-pack.ts', spec: sdlPath.split('/').pop(), ...gql })}\n`);
@@ -282,17 +305,65 @@ if (existsSync(manifestPath)) {
   // (a resource the spec names is read by its own list or retrieve; one the manifest names apart from the spec's, an RPC
   // vendor's, by the list or read the scope names, with `items` where the answer holds them when the spec does not say)
   const specNamed = new Set(ir.resources.map((r) => r.name));
-  const scopes = Object.entries(manifest.resources as Record<string, { refresh?: { list?: string; get?: string; none?: string; items?: string } }>).flatMap(([name, decl]) => {
+  const scopes = Object.entries(manifest.resources as Record<string, { storedAs?: string; refresh?: { list?: string; get?: string; none?: string; items?: string; detail?: string } }>).flatMap(([name, decl]) => {
     const r = decl.refresh;
     if (!r) return [];
+    if ('graphql' in r && r.graphql) {
+      const g = graphqlLib;
+      if (!g || !graphqlSchema) return [`${name}: a GraphQL refresh needs a vendored schema`];
+      const refresh = r.graphql as { query: string; items: string; pageInfo?: string };
+      const id = r.list ?? r.get;
+      if (!id || !graphqlOperations.has(id) || !id.startsWith('query.')) return [`${name}: refresh names no GraphQL read operation (${id})`];
+      let document: import('graphql').DocumentNode;
+      try { document = g.parse(refresh.query); } catch (error) { return [`${name}: invalid GraphQL refresh: ${String(error)}`]; }
+      const invalid = g.validate(graphqlSchema, document);
+      if (invalid.length) return invalid.map((e) => `${name}: GraphQL refresh: ${e.message}`);
+      const operation = g.getOperationAST(document);
+      if (!operation || operation.operation !== 'query') return [`${name}: a refresh document must select one query`];
+      const parts = refresh.items.replace(/^\$body\.?/, '').split('.');
+      if (parts.shift() !== 'data') return [`${name}: GraphQL items must name a path under data`];
+      let selections = operation.selectionSet;
+      let type: import('graphql').GraphQLNamedType = graphqlSchema.getQueryType()!;
+      for (const part of parts) {
+        const field = selections.selections.find((n): n is import('graphql').FieldNode => n.kind === 'Field' && (n.alias?.value ?? n.name.value) === part);
+        if (!field || !g.isObjectType(type)) return [`${name}: GraphQL items path ${refresh.items} is not selected by the document`];
+        if (type === graphqlSchema.getQueryType() && `query.${field.name.value}` !== id) return [`${name}: GraphQL refresh declares ${id} but selects query.${field.name.value}`];
+        const definition: import('graphql').GraphQLField<unknown, unknown> = type.getFields()[field.name.value]!;
+        type = g.getNamedType(definition.type);
+        selections = field.selectionSet!;
+      }
+      const normalize = (value: string) => value.replace(/_/g, '').toLowerCase();
+      if (normalize(type.name) !== normalize(name) && normalize(type.name) !== normalize(decl.storedAs ?? name)) return [`${name}: GraphQL items return ${type.name}, not ${name}`];
+      return [];
+    }
     const op = (id: string | undefined) => ir.operations.find((o) => o.id === id);
     const ours = (o: { resource?: string }): boolean => !specNamed.has(name) || o.resource === name;
     if (r.list !== undefined) {
       const o = op(r.list);
+      // a list the spec's reading does not class as one (a nullable array, a union of list envelopes, a list nested in its
+      // envelope: Discord's, Polar's, Cloudflare's) is read where the scope says its items are: any read the spec names
+      // (still this resource's read: one the spec's reading gives another resource is refused)
+      if (o && r.items) {
+        // a read asked by POST (an RPC list: AWS JSON's ListSecrets) is a read too; one the spec classes a write is not
+        if (String(o.method).toUpperCase() !== 'GET' && ['create', 'update', 'delete', 'action'].includes(String(o.class))) return [`${name}: refresh.list ${r.list} is a ${o.class}, not a read`];
+        const detail = r.detail ? op(r.detail) : undefined;
+        const detailed = detail?.method.toUpperCase() === 'GET' && ours(detail);
+        return !o.resource || ours(o) || detailed ? [] : [`${name}: refresh.list ${r.list} reads ${o.resource}, not ${name}`];
+      }
       if (!(o?.class === 'list' && ours(o))) return [`${name}: refresh.list ${r.list} is ${o ? `a ${o.class} of ${o.resource ?? 'no resource'}` : 'no operation of the spec'}, not a list of ${name}`];
       return o.answers?.list || r.items ? [] : [`${name}: refresh.list ${r.list} answers no list the spec names; say where its items are (items)`];
     }
-    if (r.get !== undefined) { const o = op(r.get); return o?.class === 'retrieve' && ours(o) ? [] : [`${name}: refresh.get ${r.get} is ${o ? `a ${o.class} of ${o.resource ?? 'no resource'}` : 'no operation of the spec'}, not the retrieve of ${name}`]; }
+    if (r.get !== undefined) {
+      const o = op(r.get);
+      if (o?.class === 'retrieve' && ours(o)) return [];
+      // a resource the spec does not name (a client-derived spec classes every request an action) is read by the GET
+      // the scope names, the answer itself the subject
+      if (o && !specNamed.has(name) && !o.resource && String(o.method).toUpperCase() === 'GET') return [];
+      // ...or by the POST the scope names that the manifest's `reads` rules a read (an RPC method: Telegram's getChat),
+      // whatever schema it answers (getChat's ChatFullInfo, a chat's fuller form, under `result`)
+      if (o && !specNamed.has(name) && ((manifest as { reads?: string[] }).reads ?? []).includes(o.id)) return [];
+      return [`${name}: refresh.get ${r.get} is ${o ? `a ${o.class} of ${o.resource ?? 'no resource'}` : 'no operation of the spec'}, not the retrieve of ${name}`];
+    }
     return typeof r.none === 'string' && r.none.trim() ? [] : [`${name}: refresh names no list, no get and no reason`];
   });
   if (scopes.length) {

package/src/gate.ts

@@ -1,8 +1,9 @@
+import { unpublishedUnitFiles } from './conformance.ts';
+import { hasOwnSurface } from './lanes.ts';
 // The gate — what may be in a Protocol 3 pack repository or catalog: every pack and lane passes the form
 // section of the grade (docs/contributing/architecture.md, "The grade"), so nothing that is not Protocol 3 enters it:
 // nothing outside the pack layout, no handler past its contract.
-// The repository was made so that this holds (the owner, 2026-09-29: "this was WHY we created p3 so this can't
-// happen"); this is what makes it hold. It runs before a commit (the pack repository's hook, on the units it touches),
+// Protocol 3's repository was made so that this holds; this is what makes it hold. It runs before a commit (the pack repository's hook, on the units it touches),
 // before a release (pack-release, on each pack it releases), and on every version submitted to the catalog
 // (twin-catalog's check, on the published tarball) — each at the version of this package it pins, so all of them judge by
 // one standard.
@@ -16,6 +17,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import ts from 'typescript';
 import { grade } from './grade.ts';
+import { withCheckoutFiles } from './protocol-3.ts';
 import { isPackArtifact } from './pack-files.ts';
 
 /** Every unit of a pack repository: each pack (a directory with a package.json) and each lane in it (a directory with
@@ -38,7 +40,7 @@ export function unitsOf(repo: string): string[] {
  *  generated facts, its lanes, and in src/ only its manifest (its lanes' routes, discovery and descriptor, as data), the
  *  fetch the kernel serves them by (createVendorFetch, generated) and the fixed serve factory, index and bin. Nothing
  *  routes by hand: only the fetch reaches a lane. A directory with no manifest and no lane is no Protocol 3 pack. */
-const ROOT_ENTRIES = new Set(['README.md', 'package.json', 'LICENSE', 'CHANGELOG.md', 'tsconfig.json', 'tsconfig.build.json', 'gate.ts', 'census.json', 'vendor', 'journeys', 'generated', 'src', 'node_modules']);
+const ROOT_ENTRIES = new Set(['README.md', 'package.json', 'LICENSE', 'CHANGELOG.md', 'tsconfig.json', 'tsconfig.build.json', 'gate.ts', 'census.json', 'vendor', 'journeys', 'spec', 'generated', 'src', 'node_modules']);
 const ROOT_SRC = new Set(['manifest.ts', 'fetch.ts', 'index.ts', 'cli.ts', 'server.ts']);
 /** What the repository ignores (a build's dist/, a World's state) is no file of the pack, as protocol-3's layout reads it. */
 function ignored(dir: string, names: string[]): Set<string> {
@@ -53,6 +55,7 @@ export function laneRootFailures(dir: string): string[] {
   const skip = ignored(dir, stray);
   const outside = [
     ...stray.filter((n) => !skip.has(n)),
+    ...(existsSync(join(dir, 'spec')) ? readdirSync(join(dir, 'spec')).filter((n) => !['sources.json', 'SOURCE.md', 'README.md'].includes(n)).map((n) => `spec/${n}`) : []),
     ...(existsSync(join(dir, 'src')) ? readdirSync(join(dir, 'src')).filter((n) => !ROOT_SRC.has(n) && !n.endsWith('.d.ts') && n !== 'semantics').map((n) => `src/${n}`) : []),
     // what the lanes share, and nothing else (architecture, "Pack layout": a vendor whose every API is a lane)
     ...(existsSync(join(dir, 'src', 'semantics')) ? readdirSync(join(dir, 'src', 'semantics')).filter((n) => n !== 'shared.ts').map((n) => `src/semantics/${n}`) : []),
@@ -60,6 +63,7 @@ export function laneRootFailures(dir: string): string[] {
   const failures = outside.length ? [`layout: ${outside.length} outside the vendor's root (its lanes hold the rest): ${outside.slice(0, 8).join(', ')}${outside.length > 8 ? ` and ${outside.length - 8} more` : ''}`] : [];
   // the vendor's front is declared and the kernel serves it: a manifest, and a fetch that is createVendorFetch over it
   const src = (n: string): string => (existsSync(join(dir, 'src', n)) ? readFileSync(join(dir, 'src', n), 'utf8') : '');
+  failures.push(...unpublishedUnitFiles(dir).map((f) => `layout: ${f}`));
   if (!src('manifest.ts')) failures.push("layout: no src/manifest.ts: a vendor of lanes declares its lanes' routes, discovery and descriptor");
   if (!/\bcreateVendorFetch\(/.test(src('fetch.ts'))) failures.push('layout: src/fetch.ts builds no createVendorFetch: the kernel routes a vendor\'s lanes from its manifest, nothing by hand');
   // the root's own files hold to the pack contract as a unit's do (the grade's kernel-contract)
@@ -82,15 +86,17 @@ export function laneRootFailures(dir: string): string[] {
 
 /** Each unit's blocking form failures (empty when it may be in the repository). */
 export async function p3Gate(units: string[]): Promise<Array<{ unit: string; failures: string[] }>> {
-  const out: Array<{ unit: string; failures: string[] }> = [];
-  for (const unit of units) {
-    // a vendor whose every API is a lane has no spec of its own: its lanes are graded, and its root is only the vendor's
-    // front (architecture, "Pack layout", "Other wires: lanes")
-    const lanesOnly = !existsSync(join(unit, 'spec')) && readdirSync(unit).some((n) => existsSync(join(unit, n, 'src', 'manifest.ts')));
-    if (lanesOnly || !existsSync(join(unit, 'src', 'manifest.ts'))) { out.push({ unit, failures: laneRootFailures(unit) }); continue; }
-    const grades = await grade(unit, { static: true, sections: ['form'] });
-    const form = Object.values(grades).flatMap((g) => g.criteria).filter((c) => !c.pass);
-    out.push({ unit, failures: form.map((c) => `${c.id}: ${c.reason}`) });
-  }
-  return out;
+  return withCheckoutFiles(async () => {
+    const out: Array<{ unit: string; failures: string[] }> = [];
+    for (const unit of units) {
+      // a vendor whose every API is a lane has no spec of its own: its lanes are graded, and its root is only the vendor's
+      // front (architecture, "Pack layout", "Other wires: lanes")
+      const lanesOnly = !hasOwnSurface(unit) && readdirSync(unit).some((n) => existsSync(join(unit, n, 'src', 'manifest.ts')));
+      if (lanesOnly || !existsSync(join(unit, 'src', 'manifest.ts'))) { out.push({ unit, failures: laneRootFailures(unit) }); continue; }
+      const grades = await grade(unit, { static: true, sections: ['form'] });
+      const form = Object.values(grades).flatMap((g) => g.criteria).filter((c) => !c.pass);
+      out.push({ unit, failures: form.map((c) => `${c.id}: ${c.reason}`) });
+    }
+    return out;
+  });
 }

package/src/index.ts

@@ -4,9 +4,11 @@
 // of a submission — judges by the same standard at the version it pins. Changing a criterion is a release of this
 // package: a criterion's id never changes meaning, a changed criterion takes a new id and a new standard version.
 export { grade, STANDARDS, type CriterionGrade, type GradeOptions, type StandardGrade } from './grade.ts';
+export { conformance, decisionTableProblems, type ConformanceResult, UNIT_FILES, unitFilesMissing } from './conformance.ts';
 export { laneRootFailures, p3Gate, unitsOf } from './gate.ts';
-export { gatePublished, vendorOfPackage, type PublishedGate } from './published.ts';
-export { handlerName, protocol3, PLANNED } from './protocol-3.ts';
-export { sharingLanesIn } from './lanes.ts';
+export { conformPublished, gatePublished, vendorOfPackage, type PublishedGate } from './published.ts';
+export { handlerName, protocol3, PLANNED, withCheckoutFiles } from './protocol-3.ts';
+export { notIndependent, type Verdict } from './verdict.ts';
+export { sharingLanesIn, hasOwnSurface } from './lanes.ts';
 export { unitAt } from './unit.ts';
 export type { Criterion, CriterionResult, GradeUnit, ScoreReport, Standard } from './types.ts';

package/src/lanes.ts

@@ -4,6 +4,13 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+/** Metadata such as sources.json is not a derivable API of a vendor whose APIs all belong to its lanes. */
+export function hasOwnSurface(pkg: string): boolean {
+  if (existsSync(join(pkg, 'src', 'generated', 'surface.gen.json'))) return true;
+  const spec = join(pkg, 'spec');
+  return existsSync(spec) && readdirSync(spec).some((name) => /^(openapi\.(json|yaml)(\.gz)?|smithy\.json(\.gz)?|discovery\.json(\.gz)?|rfc\d+\.txt|openapi|proto|commands|client-ops\.json)$/.test(name));
+}
+
 /** The service a manifest names: the top-level `service:` of its exported manifest object. */
 function serviceOf(manifestPath: string): string | undefined {
   const text = readFileSync(manifestPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');

package/src/p3-rules.ts

@@ -14,8 +14,6 @@ const RULES: Array<{ rule: string; test: (line: string) => boolean }> = [
   { rule: "the twin's URL from the request (use ctx.publicBase)", test: (l) => /request\.url\)\.origin/.test(l) },
   // signing, digests and randomness are the kernel's (ctx.crypto, world-core's exports)
   { rule: 'node:crypto in a pack (use ctx.crypto or the kernel\'s digest)', test: (l) => /from ['"](node:)?crypto['"]|require\(['"](node:)?crypto['"]\)/.test(l) },
-  // a webhook is the manifest's events; ctx.deliver is for a message that is no declared event (a push notification)
-  { rule: 'ctx.deliver where the manifest\'s events belong (or record why)', test: (l) => /ctx\.deliver\(/.test(l) },
   // an object's bytes are ctx.blobs, never a row's field
   { rule: "bytes kept in a row (use ctx.blobs)", test: (l) => /ctx\.(write|record)\([^;]*toString\(['"]base64['"]\)/.test(l) || /\b_bytes\s*:/.test(l) },
   // a secret the vendor issues is drawn from ctx.secret, never computed from ids

package/src/protocol-3.ts

@@ -4,7 +4,10 @@
 // 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 { unpublishedUnitFiles } from './conformance.ts';
+import { attributionName, notIndependent } from './verdict.ts';
 import { spawnSync } from 'node:child_process';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -39,30 +42,54 @@ const readJson = (path: string): unknown => { try { return JSON.parse(readFileSy
 
 /** 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. */
+/** A tool in spec/ is not a vendored document: never hashed, and outside the layout unless it is the script that wrote
+ *  the document from the vendor's reference page, which SOURCE.md names (architecture, "Creating a pack", step 2). */
 const SPEC_TOOL = /\.(py|sh|ts|js|mjs|cjs|rb)$/;
+/** spec/'s tools SOURCE.md names: the writers of a document a vendor publishes only as a page. */
+function namedSpecTools(unit: GradeUnit): Set<string> {
+  const path = join(unit.dir, 'spec', 'SOURCE.md');
+  const source = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  return new Set(filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f) && !f.includes('/') && source.includes(`\`${f}\``)));
+}
 /** 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));
 }
 
-/** Files relative to a directory: Git's tree in a checkout, the disk tree of an unpacked package outside one. */
+/** The checkout a directory is in: the nearest ancestor holding `.git` (a directory, or a worktree's file). */
+function checkoutOf(dir: string): string | undefined {
+  for (let d = dir; ; d = dirname(d)) {
+    if (existsSync(join(d, '.git'))) return d;
+    if (dirname(d) === d) return undefined;
+  }
+}
+// Grading fans out over a checkout's directories. A caller explicitly owns the immutable listing for one pass;
+// nested gates share it, while concurrent passes have separate snapshots and direct checks always read git afresh.
+const checkoutFiles = new AsyncLocalStorage<Map<string, string[]>>();
+export function withCheckoutFiles<T>(fn: () => T): T {
+  return checkoutFiles.getStore() ? fn() : checkoutFiles.run(new Map(), fn);
+}
+/** Files relative to a directory: Git's tree in a checkout (one listing per checkout per pass), the disk tree of an
+ *  unpacked package outside one. A failed Git listing refuses; it never reads as an empty tree. */
 function filesUnder(dir: string, base = dir): string[] {
   if (!existsSync(dir)) return [];
-  const checkout = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
-  if (checkout.status !== 0 || checkout.error || checkout.stdout.trim() !== 'true') {
-    if (checkout.status !== null && checkout.status !== 0 && !checkout.error && !checkout.signal
-      && /^fatal: not a git repository(?:[ (:]|$)/m.test(String(checkout.stderr ?? ''))) return allFilesUnder(dir, base, true);
-    throw new Error(`git rev-parse failed: directory=${JSON.stringify(dir)} status=${checkout.status} signal=${JSON.stringify(checkout.signal)} error=${JSON.stringify(checkout.error?.message ?? null)} stdout=${JSON.stringify(String(checkout.stdout ?? '').trim())} stderr=${JSON.stringify(String(checkout.stderr ?? '').trim())}`);
-  }
-  // 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', 'pipe'] });
-  if (run.status !== 0 || run.error) {
-    throw new Error(`git ls-files failed: directory=${JSON.stringify(dir)} status=${run.status} signal=${JSON.stringify(run.signal)} error=${JSON.stringify(run.error?.message ?? null)} stderr=${JSON.stringify(String(run.stderr ?? '').trim())}`);
+  const top = checkoutOf(dir);
+  if (!top) return allFilesUnder(dir, base, true);
+  const listing = checkoutFiles.getStore();
+  let files = listing?.get(top);
+  if (!files) {
+    // 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: top, stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024 });
+    if (run.status !== 0 || run.error) {
+      throw new Error(`git ls-files failed: directory=${JSON.stringify(top)} status=${run.status} signal=${JSON.stringify(run.signal)} error=${JSON.stringify(run.error?.message ?? null)} stderr=${JSON.stringify(String(run.stderr ?? ''))}`);
+    }
+    files = [...new Set(String(run.stdout).split('\0').filter(Boolean))];
+    listing?.set(top, files);
   }
-  const tracked = [...new Set(String(run.stdout).split('\0').filter(Boolean))];
-  return tracked.map((f) => relative(base, join(dir, f))).filter((f) => existsSync(join(base, f)));
+  const under = relative(top, dir);
+  const mine = under === '' ? files : files.filter((f) => f.startsWith(`${under}/`)).map((f) => f.slice(under.length + 1));
+  return mine.map((f) => relative(base, join(dir, f))).filter((f) => existsSync(join(base, f)));
 }
 /** Disk files outside a checkout, or the complete output of the grader's own derivation. */
 function allFilesUnder(dir: string, base = dir, excludeArtifacts = false): string[] {
@@ -94,15 +121,26 @@ 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);
+  return (isLane(unit) ? ['manifest.ts', 'index.ts', 'fetch.ts', 'budget.ts'] : ['manifest.ts', 'index.ts', 'cli.ts', 'fetch.ts', 'server.ts', 'stream.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', 'board.ts']);
+const SEMANTICS_FIXED = new Set(['answer-views.ts', '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', 'board.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']);
+/** Only scenario basenames the two walks explicitly declare extend the closed layout. */
+function journeyFiles(unit: GradeUnit): Set<string> {
+  const files = new Set(JOURNEY_FILES);
+  for (const name of ['customer-life.json', 'vendor-examples.json']) {
+    try {
+      const journey = JSON.parse(readFileSync(join(unit.dir, 'journeys', name), 'utf8')) as { scenario?: unknown };
+      if (typeof journey.scenario === 'string' && /^[a-z0-9][a-z0-9.-]*\.json$/i.test(journey.scenario)) files.add(journey.scenario);
+    } catch { /* malformed or absent journeys get no additional files */ }
+  }
+  return files;
+}
 /** 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) => {
@@ -141,7 +179,7 @@ const FORBIDDEN_REACH: ReadonlyArray<readonly [RegExp, string]> = [
   [/\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'],
+  [/\bctx\.(now|core|atomically|tree|writeDetailed)\b|\}\s*=\s*ctx\b(?!\s*[.?])|\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
@@ -201,10 +239,10 @@ const criteria: Criterion[] = [
       // 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 doc = readJson(path) as { patches?: Array<{ why?: string; source?: { url?: string; spec?: string; recording?: 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;
+      const bare = patches.filter((p) => !p.why || !(p.source?.url || p.source?.spec || p.source?.recording || /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`);
     },
   },
@@ -246,7 +284,8 @@ const criteria: Criterion[] = [
       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}`),
+        ...unpublishedUnitFiles(unit.dir),
+        ...filesUnder(join(unit.dir, 'spec')).filter((f) => SPEC_TOOL.test(f) && !namedSpecTools(unit).has(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;
@@ -254,7 +293,7 @@ const criteria: Criterion[] = [
           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}`),
+        ...filesUnder(join(unit.dir, 'journeys')).filter((f) => vendorLanes(unit).length > 0 || !journeyFiles(unit).has(f)).map((f) => `journeys/${f}`),
       ];
       // screens/: one file per screen the manifest declares, named by its id
       if (existsSync(join(src, 'screens'))) {
@@ -324,6 +363,11 @@ const criteria: Criterion[] = [
           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 === 'answer-views.ts') {
+          const names = [...text.matchAll(/^export\s+const\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
+          if (names.join() !== 'answerViews' || /^export\s+(?:async\s+)?function\s|^export\s+(let|var|class)\s|^export\s*\{/m.test(text)) found.push(`answer-views.ts exports ${names.join(', ') || 'nothing'}, not only answerViews`);
+          continue;
+        }
         if (f === 'board.ts') {
           const names = [...text.matchAll(/^export\s+(?:async\s+)?function\s+([A-Za-z0-9_$]+)/gm)].map((m) => m[1]);
           if (names.join() !== 'board' || /^export\s+(const|let|var|class)\s|^export\s*\{/m.test(text)) found.push(`board.ts exports ${names.join(', ') || 'nothing'}, not only board`);
@@ -527,13 +571,13 @@ const criteria: Criterion[] = [
       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');
+      const author = /^Author:\s*(.+?)\.?\s*$/m.exec(readFileSync(outline, 'utf8'))?.[1];
+      attributionName(author);
       if (!verdict) return fail('no outline verdict');
       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}`);
+      const dependent = notIndependent(verdict);
+      if (dependent) return fail(dependent);
+      return pass(`plausible, judge ${verdict.judge!.agent}`);
     },
   },
   {
@@ -542,7 +586,7 @@ const criteria: Criterion[] = [
     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}`);
+      return r.life.steps > 0 && r.life.verdict === 'plausible' ? pass(`${r.life.steps} steps, judge ${r.life.judge}`) : fail(`verdict: ${r.life.verdict}`);
     },
   },
   {