@volter/twin-standard 1.0.29 → 1.0.31

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,8 @@ 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). */
 export function unitsOf(repo) {
@@ -37,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) {
@@ -50,10 +53,11 @@ export function laneRootFailures(dir) {
     const lanes = readdirSync(dir).filter((n) => existsSync(join(dir, n, 'src', 'manifest.ts')));
     if (!lanes.length)
         return ['layout: no src/manifest.ts and no lane: not a Protocol 3 pack'];
-    const stray = readdirSync(dir).filter((n) => !n.startsWith('.') && !ROOT_ENTRIES.has(n) && !lanes.includes(n));
+    const stray = readdirSync(dir).filter((n) => !isPackArtifact(n) && !n.startsWith('.') && !ROOT_ENTRIES.has(n) && !lanes.includes(n));
     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}`) : []),
@@ -61,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')))
@@ -92,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/pack-files.d.ts

@@ -0,0 +1,2 @@
+/** Release outputs and runtime state, relative to the pack directory being listed. */
+export declare function isPackArtifact(path: string): boolean;

package/dist/src/pack-files.js

@@ -0,0 +1,4 @@
+/** Release outputs and runtime state, relative to the pack directory being listed. */
+export function isPackArtifact(path) {
+    return /^(dist|node_modules|\.volter)(\/|$)/.test(path) || path === 'generated/pack-facts.json';
+}

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[];