@volter/twin-standard 1.0.30 → 1.0.32

package/dist/src/derive.js

@@ -1,10 +1,4 @@
 #!/usr/bin/env bun
-// 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
-// `src/generated/`. Deterministic: a second run over the same spec writes the same bytes. Never hand-edit what it writes.
-//
-// Usage: twin-standard derive <pack dir> [--out <dir>]   (twin-world: bun scripts/derive-pack.ts <vendor>)
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -13,6 +7,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
+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
+// `src/generated/`. Deterministic: a second run over the same spec writes the same bytes. Never hand-edit what it writes.
+//
+// Usage: twin-standard derive <pack dir> [--out <dir>]   (twin-world: bun scripts/derive-pack.ts <vendor>)
 import { parse as parseYaml } from 'yaml';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -23,7 +24,7 @@ import { fromProto, protoSchema, readProtoFiles } from "./spec-ir-proto.js";
 import { fromRedisCommands } from "./spec-ir-commands.js";
 import { fromClientCalls } from "./spec-ir-client.js";
 import { discoveryMethods, fromDiscovery, isDiscovery } from "./spec-ir-discovery.js";
-import { handlerCitations, quotedPage, urlsIn } from "./check-sources.js";
+import { handlerCitations, quotedPage, sourceHeld, urlsIn } from "./check-sources.js";
 import { applySpecPatch } from "./spec-patches.js";
 import { unitAt } from "./unit.js";
 import { mergeDocuments, readSpecDocuments } from "./spec-documents.js";
@@ -56,12 +57,13 @@ 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 = 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 = 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) => {
     const at = text.search(new RegExp(`^${n.replace(/\./g, '\\.')}\\.  `, 'm'));
@@ -71,7 +73,7 @@ const sectionOf = (n) => {
     return next < 0 ? text.slice(at) : text.slice(at, at + 1 + next);
 };
 const sourcesPath = join(PKG, 'spec', 'sources.json');
-const recorded = existsSync(sourcesPath) ? JSON.parse(readFileSync(sourcesPath, 'utf8')) : {};
+const recorded = existsSync(sourcesPath) ? parseExactJson(readFileSync(sourcesPath, 'utf8')) : {};
 const HTTP_METHODS = new Set(['get', 'put', 'post', 'delete', 'patch', 'head', 'options', 'trace']);
 const specOps = new Map();
 // an operation by its id: the spec's operationId, or the `method_path` slug the IR mints where the spec names none (QStash)
@@ -104,8 +106,25 @@ const wordsIn = (node) => (typeof node === 'string' ? node : node && typeof node
 const bare = (s) => 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) => (ref.startsWith('/') ? ref.split('/').slice(1).map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~')).reduce((n, 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, quote) {
+    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) {
+    // 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`;
@@ -115,10 +134,15 @@ function unheld(source) {
             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 = [];
@@ -127,26 +151,27 @@ 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);
+    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(`semantics/${c.where}: ${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) {
+    for (const p of parseExactJson(readFileSync(patchPath, 'utf8')).patches) {
         if (!p.why?.trim()) {
             console.error(`${vendor}: spec patch ${p.op} ${p.path} gives no why`);
             process.exit(1);
         }
         {
             const s = p.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`)
-                    : urlsIn(p.why).length ? unheld(p.why) : 'it cites no page and quotes nothing';
+            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}`);
         }
@@ -197,7 +222,7 @@ const ir = isDiscovery(doc) ? fromDiscovery(doc) : doc?.format === 'client' ? fr
 // 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')) : {};
+const grouping = existsSync(join(PKG, 'spec', 'grouping.json')) ? parseExactJson(readFileSync(join(PKG, 'spec', 'grouping.json'), 'utf8')) : {};
 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)
@@ -218,10 +243,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();
+let graphqlSchema;
+let graphqlLib;
 if (sdlPath) {
     const { fromGraphQL } = await import("./spec-ir-graphql.js");
     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 });
@@ -314,17 +343,79 @@ if (existsSync(manifestPath)) {
         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;
+            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;
+            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 = graphqlSchema.getQueryType();
+            for (const part of parts) {
+                const field = selections.selections.find((n) => 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 = type.getFields()[field.name.value];
+                type = g.getNamedType(definition.type);
+                selections = field.selectionSet;
+            }
+            const normalize = (value) => 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) => ir.operations.find((o) => o.id === id);
         const ours = (o) => !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 (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.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`];
     });

package/dist/src/gate.js

@@ -1,8 +1,9 @@
+import { unpublishedUnitFiles } from "./conformance.js";
+import { hasOwnSurface } from "./lanes.js";
 // 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.js";
+import { withCheckoutFiles } from "./protocol-3.js";
 import { isPackArtifact } from "./pack-files.js";
 /** Every unit of a pack repository: each pack (a directory with a package.json) and each lane in it (a directory with
  *  its own src/manifest.ts and no package.json). */
@@ -38,7 +40,7 @@ export function unitsOf(repo) {
  *  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, names) {
@@ -55,6 +57,7 @@ export function laneRootFailures(dir) {
     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}`) : []),
@@ -62,6 +65,7 @@ export function laneRootFailures(dir) {
     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) => (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')))
@@ -93,18 +97,20 @@ export function laneRootFailures(dir) {
 }
 /** Each unit's blocking form failures (empty when it may be in the repository). */
 export async function p3Gate(units) {
-    const out = [];
-    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;
+    return withCheckoutFiles(async () => {
+        const out = [];
+        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}`) });
         }
-        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 out;
+    });
 }

package/dist/src/index.d.ts

@@ -1,7 +1,9 @@
 export { grade, STANDARDS, type CriterionGrade, type GradeOptions, type StandardGrade } from './grade.js';
+export { conformance, decisionTableProblems, type ConformanceResult, UNIT_FILES, unitFilesMissing } from './conformance.js';
 export { laneRootFailures, p3Gate, unitsOf } from './gate.js';
-export { gatePublished, vendorOfPackage, type PublishedGate } from './published.js';
-export { handlerName, protocol3, PLANNED } from './protocol-3.js';
-export { sharingLanesIn } from './lanes.js';
+export { conformPublished, gatePublished, vendorOfPackage, type PublishedGate } from './published.js';
+export { handlerName, protocol3, PLANNED, withCheckoutFiles } from './protocol-3.js';
+export { notIndependent, type Verdict } from './verdict.js';
+export { sharingLanesIn, hasOwnSurface } from './lanes.js';
 export { unitAt } from './unit.js';
 export type { Criterion, CriterionResult, GradeUnit, ScoreReport, Standard } from './types.js';

package/dist/src/index.js

@@ -4,8 +4,10 @@
 // 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 } from "./grade.js";
+export { conformance, decisionTableProblems, UNIT_FILES, unitFilesMissing } from "./conformance.js";
 export { laneRootFailures, p3Gate, unitsOf } from "./gate.js";
-export { gatePublished, vendorOfPackage } from "./published.js";
-export { handlerName, protocol3, PLANNED } from "./protocol-3.js";
-export { sharingLanesIn } from "./lanes.js";
+export { conformPublished, gatePublished, vendorOfPackage } from "./published.js";
+export { handlerName, protocol3, PLANNED, withCheckoutFiles } from "./protocol-3.js";
+export { notIndependent } from "./verdict.js";
+export { sharingLanesIn, hasOwnSurface } from "./lanes.js";
 export { unitAt } from "./unit.js";

package/dist/src/lanes.d.ts

@@ -1,2 +1,4 @@
+/** Metadata such as sources.json is not a derivable API of a vendor whose APIs all belong to its lanes. */
+export declare function hasOwnSurface(pkg: string): boolean;
 /** The lanes over a vendor's state in the vendor's directory `pkg`, wherever its repository is. */
 export declare function sharingLanesIn(pkg: string, vendor: string): string[];

package/dist/src/lanes.js

@@ -3,6 +3,13 @@
 // walked, measured and graded through the vendor's life; every other lane keeps its own.
 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) {
+    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) {
     const text = readFileSync(manifestPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');

package/dist/src/p3-rules.js

@@ -11,8 +11,6 @@ const RULES = [
     { 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/dist/src/protocol-3.d.ts

@@ -1,4 +1,5 @@
 import type { Standard } from './types.js';
+export declare function withCheckoutFiles<T>(fn: () => T): T;
 export declare const handlerName: (operationId: string) => string;
 /** Named by "The grade" and decided by no tool yet: counted in no grade until a version of this standard checks them. */
 export declare const PLANNED: string[];

package/dist/src/protocol-3.js

@@ -12,7 +12,10 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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.js";
+import { attributionName, notIndependent } from "./verdict.js";
 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';
@@ -50,31 +53,57 @@ catch {
 } };
 /** 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) {
+    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) {
     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) {
+    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();
+export function withCheckoutFiles(fn) {
+    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, base = dir) {
     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, base = dir, excludeArtifacts = false) {
@@ -110,15 +139,28 @@ const isLane = (unit) => unit.name.includes('/');
 function srcFileInForm(unit, name) {
     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) {
+    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'));
+            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) {
     return entriesOf(unit.dir).filter((name) => {
@@ -157,7 +199,7 @@ const FORBIDDEN_REACH = [
     [/\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
@@ -228,7 +270,7 @@ const criteria = [
             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`);
         },
     },
@@ -274,7 +316,8 @@ const criteria = [
             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('/'))
@@ -283,7 +326,7 @@ const criteria = [
                     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'))) {
@@ -366,6 +409,12 @@ const criteria = [
                         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))
@@ -618,18 +667,15 @@ const criteria = [
             const verdict = readJson(join(journeys, 'customer-life.outline.verdict.json'));
             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');
+            const dependent = notIndependent(verdict);
+            if (dependent)
+                return fail(dependent);
             return pass(`plausible, judge ${verdict.judge.agent}`);
         },
     },
@@ -640,7 +686,7 @@ const criteria = [
             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}`);
         },
     },
     {

package/dist/src/published.d.ts

@@ -1,3 +1,4 @@
+import { type ConformanceResult } from './conformance.js';
 export type PublishedGate = {
     spec: string;
     failures: Array<{
@@ -7,6 +8,11 @@ export type PublishedGate = {
 };
 /** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
 export declare const vendorOfPackage: (name: string) => string;
+/** The conformance of `spec` as the registry serves it: the published tarball with its own dependencies installed,
+ *  served and read against the kernel (kernelDir). */
+export declare function conformPublished(spec: string, opts?: {
+    registry?: string;
+}): Promise<ConformanceResult[]>;
 /** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
 export declare function gatePublished(spec: string, opts?: {
     registry?: string;