@volter/twin-standard 1.0.30 → 1.0.32

package/src/published.ts

@@ -2,9 +2,11 @@
 // twins come from"): its tarball fetched from the registry, unpacked under its vendor's name (so its lanes are read as
 // the vendor's), and every unit in it — the pack and each lane — put through the gate.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { conformance, type ConformanceResult } from './conformance.ts';
 import { p3Gate } from './gate.ts';
 
 export type PublishedGate = { spec: string; failures: Array<{ unit: string; failures: string[] }> };
@@ -12,8 +14,9 @@ export type PublishedGate = { spec: string; failures: Array<{ unit: string; fail
 /** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
 export const vendorOfPackage = (name: string): string => name.replace(/^@[^/]+\//, '').replace(/^twin-/, '');
 
-/** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
-export async function gatePublished(spec: string, opts: { registry?: string } = {}): Promise<PublishedGate> {
+/** `spec` (`<name>@<version>`) as the registry serves it, unpacked under its vendor's name in a scratch directory, handed
+ *  to `use`; throws when it cannot be fetched or unpacked. */
+async function withPublished<T>(spec: string, opts: { registry?: string }, use: (dir: string, tmp: string) => Promise<T>): Promise<T> {
   const tmp = mkdtempSync(join(tmpdir(), 'twin-standard-'));
   try {
     const pack = spawnSync('npm', ['pack', spec, '--pack-destination', tmp, '--silent', ...(opts.registry ? ['--registry', opts.registry] : [])], { encoding: 'utf8' });
@@ -24,14 +27,59 @@ export async function gatePublished(spec: string, opts: { registry?: string } =
     const name = (JSON.parse(readFileSync(join(tmp, 'package', 'package.json'), 'utf8')) as { name: string }).name;
     const dir = join(tmp, vendorOfPackage(name));
     renameSync(join(tmp, 'package'), dir);
-    const lanes = readdirSync(dir).filter((l) => existsSync(join(dir, l, 'src', 'manifest.ts')) && !existsSync(join(dir, l, 'package.json'))).map((l) => join(dir, l));
-    const results = await p3Gate([dir, ...lanes]);
-    const unit = (u: string): string => u.slice(tmp.length + 1);
-    return {
-      spec,
-      failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })),
-    };
+    return await use(dir, tmp);
   } finally {
     rmSync(tmp, { recursive: true, force: true });
   }
 }
+
+/** A platform package a published pack is served with (`@volter/world-core`, `@volter/world-ui`): the one beside this
+ *  standard (twin-world's, where the catalog clones it), else one the caller installed. Found by its package's entry,
+ *  walked up to its root (an `exports` that names no `./package.json` is refused by Node). */
+function platformDir(name: string): string | undefined {
+  for (const from of [import.meta.url, join(process.cwd(), 'package.json')]) {
+    let at: string;
+    try { at = dirname(createRequire(from).resolve(name)); } catch { continue; }
+    for (; at !== dirname(at); at = dirname(at)) {
+      const pkg = join(at, 'package.json');
+      if (existsSync(pkg) && (JSON.parse(readFileSync(pkg, 'utf8')) as { name?: string }).name === name) return at;
+    }
+  }
+  return undefined;
+}
+
+/** 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 async function conformPublished(spec: string, opts: { registry?: string } = {}): Promise<ConformanceResult[]> {
+  const kernel = platformDir('@volter/world-core');
+  if (!kernel) throw new Error('no @volter/world-core to serve the pack with: install it beside the standard');
+  return withPublished(spec, opts, async (dir) => {
+    // what the pack depends on: the platform's packages (`@volter/*`) the same as the kernel, every other (react for its
+    // screens, a database client) installed as an application installing the pack gets it
+    const deps = (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { dependencies?: Record<string, string> }).dependencies ?? {};
+    const platform = Object.keys(deps).filter((d) => d.startsWith('@volter/'));
+    const others = Object.entries(deps).filter(([d]) => !d.startsWith('@volter/')).map(([d, v]) => `${d}@${v}`);
+    if (others.length) {
+      const install = spawnSync('npm', ['install', '--no-save', '--omit=dev', '--omit=peer', '--ignore-scripts', '--no-audit', '--no-fund', '--no-package-lock', ...(opts.registry ? ['--registry', opts.registry] : []), ...others], { cwd: dirname(dir), encoding: 'utf8' });
+      if (install.status !== 0) throw new Error(`${spec}: its dependencies do not install (${String(install.stderr).trim().split('\n').at(-1) ?? ''})`);
+    }
+    mkdirSync(join(dir, 'node_modules', '@volter'), { recursive: true });
+    for (const name of ['@volter/world-core', ...platform]) {
+      const at = name === '@volter/world-core' ? kernel : platformDir(name);
+      if (!at) throw new Error(`${spec}: depends on ${name}, which is not beside the standard`);
+      rmSync(join(dir, 'node_modules', name), { recursive: true, force: true });
+      symlinkSync(at, join(dir, 'node_modules', name));
+    }
+    return conformance(dir);
+  });
+}
+
+/** The gate over `spec` (`<name>@<version>`) as the registry serves it; throws when it cannot be fetched or unpacked. */
+export async function gatePublished(spec: string, opts: { registry?: string } = {}): Promise<PublishedGate> {
+  return withPublished(spec, opts, async (dir, tmp) => {
+    const lanes = readdirSync(dir).filter((l) => existsSync(join(dir, l, 'src', 'manifest.ts')) && !existsSync(join(dir, l, 'package.json'))).map((l) => join(dir, l));
+    const results = await p3Gate([dir, ...lanes]);
+    const unit = (u: string): string => u.slice(tmp.length + 1);
+    return { spec, failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })) };
+  });
+}

package/src/spec-documents.ts

@@ -1,3 +1,4 @@
+import { parseExactJson, exactInteger } from '@volter/world-core/exact-json';
 // One API published as several OpenAPI documents (Upstash publishes QStash's and Workflow's, both served on
 // qstash-{region}.upstash.io with one key set, and sharing endpoints): the pack vendors each as published under
 // `spec/openapi/<name>.{json,yaml}[.gz]`, patches address a document as `/documents/<name>/...`, and the documents are
@@ -21,7 +22,7 @@ export function readSpecDocuments(specDir: string): SpecDocuments | undefined {
   for (const f of readdirSync(dir).filter((f) => /\.(json|ya?ml)(\.gz)?$/.test(f)).sort()) {
     const bytes = readFileSync(join(dir, f));
     const text = (f.endsWith('.gz') ? gunzipSync(bytes) : bytes).toString('utf8');
-    documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseYaml(text) : JSON.parse(text);
+    documents[f.replace(/\.(json|ya?ml)(\.gz)?$/, '')] = /\.ya?ml(\.gz)?$/.test(f) ? parseExactJson(JSON.stringify(parseYaml(text, { intAsBigInt: true }), (_, v) => typeof v === 'bigint' ? exactInteger(String(v)) : v)) : parseExactJson(text);
   }
   if (Object.keys(documents).length < 2) throw new Error(`${dir}: one API in several documents needs at least two; a single document is spec/openapi.{json,yaml}`);
   return { documents };

package/src/spec-ir-client.ts

@@ -11,7 +11,7 @@
 // The calls at one method and path are one operation, their query and body keys together. The client says nothing
 // of what an answer holds, so an operation answers no resource here: its answers are the vendor's pages' examples.
 
-import type { IrOperation, IrParam, SpecIR } from './spec-ir.ts';
+import type { IrOperation, IrParam, IrResource, SpecIR } from './spec-ir.ts';
 
 export type ClientCall = {
   /** the client method that makes the call, and its line */
@@ -19,10 +19,13 @@ export type ClientCall = {
   line: number;
   method: string;
   url: string;
+  /** Response declarations supplied by cited reference-page patches, absent from extracted calls. */
+  answers?: IrOperation['answers'];
+  resource?: string;
   query?: Record<string, string | null>;
   body?: { encoding: 'json' | 'form' | 'raw'; fields?: Record<string, string | null>; passes?: string };
 };
-export type ClientOpsSpec = { format: 'client'; version: string; calls: ClientCall[] };
+export type ClientOpsSpec = { format: 'client'; version: string; calls: ClientCall[]; resources?: IrResource[] };
 
 /** A label's name from the expression the client interpolates: `quote(datasource_name, safe='')` is
  *  `datasource_name`, `workspace['id']` is `workspace_id`. */
@@ -51,6 +54,12 @@ export function fromClientCalls(spec: ClientOpsSpec): SpecIR {
     else byRoute.set(key, { first: call, path, labels, calls: [call] });
   }
   const operations: IrOperation[] = [...byRoute.values()].map(({ first, path, labels, calls }) => {
+    const declared = <K extends 'answers' | 'resource'>(key: K): ClientCall[K] => {
+      const values = calls.map((c) => c[key]).filter((v) => v !== undefined);
+      if (values.some((v) => JSON.stringify(v) !== JSON.stringify(values[0]))) throw new Error(`client response declarations conflict at ${first.method} ${path}: ${key}`);
+      return values[0];
+    };
+    const answers = declared('answers'); const resource = declared('resource') ?? answers?.resource;
     const query = new Map<string, IrParam>();
     const body = new Map<string, IrParam>();
     const encodings = new Set<string>();
@@ -72,7 +81,9 @@ export function fromClientCalls(spec: ClientOpsSpec): SpecIR {
       body: [...body.values()].sort((a, b) => a.name.localeCompare(b.name)),
       bodyEncoding,
       successStatus: 200,
-      class: 'action',
+      class: first.method.toUpperCase() === 'GET' && answers ? (answers.list ? 'list' : 'retrieve') : 'action',
+      ...(answers ? { answers } : {}),
+      ...(resource ? { resource } : {}),
     };
   });
   // two routes whose first calls share a client method (one method calling twice) keep distinct ids
@@ -82,5 +93,5 @@ export function fromClientCalls(spec: ClientOpsSpec): SpecIR {
     seen.set(o.id, n);
     if (n > 1) o.id = `${o.id}_${n}`;
   }
-  return { format: 'client', version: spec.version, resources: [], operations };
+  return { format: 'client', version: spec.version, resources: spec.resources ?? [], operations };
 }

package/src/spec-ir.ts

@@ -1,3 +1,4 @@
+import { isExactIntegerValue } from '@volter/world-core/exact-json';
 // THE SPEC IR — one representation of a vendor's published surface, beneath every spec format, that
 // the derived-pack generator reads (docs/contributing/architecture.md, "Protocol 3"). A front end
 // turns a spec into the IR; the generator only ever sees the IR. `fromOpenAPI` is the first front end, and `fromSmithy`
@@ -8,16 +9,19 @@
 type Json = any;
 
 export type OperationClass = 'create' | 'retrieve' | 'list' | 'update' | 'delete' | 'action' | 'computed' | 'non-resource';
+/** Binary media whose resource shape is the response bytes, rather than JSON metadata. */
+export const binaryMedia = (media: string): boolean => /^(?:application\/(?:octet-stream|pdf|zip|gzip)|(?:image|audio|video)\/[^/]+)$/.test(media.toLowerCase());
+
 export const CRUD_CLASSES: ReadonlySet<OperationClass> = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
 
 /** A parameter or body field: its name, type and whether it is required, and the numeric bounds the spec states
  *  (`minimum`, `maximum`), which a strict body (the manifest's `body.strict`, `ctx.fields`) refuses outside of. */
-export type IrParam = { name: string; type: string; required: boolean; minimum?: number; maximum?: number };
+export type IrParam = { name: string; type: string; required: boolean; minimum?: number | string; maximum?: number | string };
 
 /** A schema's stated numeric bounds, when it states any. */
-function boundsOf(doc: Json, schema: Json): { minimum?: number; maximum?: number } {
+function boundsOf(doc: Json, schema: Json): { minimum?: number | string; maximum?: number | string } {
   const s = deref(doc, schema);
-  return { ...(typeof s?.minimum === 'number' ? { minimum: s.minimum } : {}), ...(typeof s?.maximum === 'number' ? { maximum: s.maximum } : {}) };
+  return { ...((typeof s?.minimum === 'number' || typeof s?.minimum === 'string' && isExactIntegerValue(s.minimum)) ? { minimum: s.minimum } : {}), ...((typeof s?.maximum === 'number' || typeof s?.maximum === 'string' && isExactIntegerValue(s.maximum)) ? { maximum: s.maximum } : {}) };
 }
 
 export type IrOperation = {
@@ -46,6 +50,9 @@ export type IrOperation = {
   /** A form-encoded operation's number and boolean fields, by bracket path (formScalarsOf). */
   scalars?: Record<string, 'integer' | 'number' | 'boolean'>;
   successStatus: number;
+  /** Binary media types declared by each response status, independent of the twin’s response headers. */
+  responseMedia?: Record<string, string[]>;
+  defaultResponseMedia?: Record<string, string>;
   /** the success is documented with no content at all (a 200 with nothing in it) */
   emptySuccess?: true;
   /** The success answer may be a server-sent event stream (`text/event-stream`). */
@@ -245,6 +252,17 @@ function successOf(doc: Json, op: Json, resources: Map<string, string>): { statu
   const items = s?.type === 'array' ? s.items : s?.properties?.data?.type === 'array' ? s.properties.data.items : undefined;
   const listed = items ? resourcesOfSchema(doc, items, resources) : [];
   if (listed.length) return { status, answers: answer(listed, true) };
+  // a single object under `data` (X's create: a thin data object beside partial errors); a `data` that is an array, named
+  // by reference or inline, is a list's envelope, read below
+  if (s?.properties?.data && deref(doc, s.properties.data)?.type !== 'array') {
+    const payload = s.properties.data;
+    const name = refName(payload);
+    const found = resourcesOfSchema(doc, payload, resources);
+    if (found.length) return { status, answers: answer(found, false, 'data') };
+    if (name && propsOf(doc, payload).id) return { status, answers: answer([name], false, 'data') };
+    // A data payload without a modeled identity cannot make the accompanying errors the resource.
+    return { status };
+  }
   // An envelope that holds exactly one resource, or one list of them, under a named property, beside
   // at most a few scalars (`ok`, a cursor). An object with an `id` of its own, or with other objects
   // in it, is not an envelope: it is something that embeds another (a Pages site, a branch).
@@ -281,7 +299,16 @@ function paramsOf(doc: Json, op: Json, pathItem: Json): { pathParams: string[];
 }
 
 function bodyOf(doc: Json, op: Json): { body: IrParam[]; bodyEncoding: IrOperation['bodyEncoding'] } {
-  const content = deref(doc, op.requestBody)?.content ?? {};
+  const request = deref(doc, op.requestBody);
+  const content = request?.content ?? {};
+  // A whole binary body is the payload itself, not a JSON object with no fields. Keep the existing blob contract so
+  // the kernel leaves its bytes opaque even when a caller labels them application/json.
+  const representations = Object.values(content);
+  const binary = representations.length > 0 && representations.every((media: Json) => {
+    const schema = deref(doc, media?.schema);
+    return schema?.type === 'string' && schema.format === 'binary';
+  });
+  if (binary) return { body: [{ name: 'body', type: 'blob', required: request?.required === true }], bodyEncoding: 'none' };
   const mediaOf = { json: 'application/json', form: 'application/x-www-form-urlencoded', multipart: 'multipart/form-data' } as const;
   const encoding = content[mediaOf.json] ? 'json' : content[mediaOf.form] ? 'form' : content[mediaOf.multipart] ? 'multipart' : 'none';
   if (encoding === 'none') return { body: [], bodyEncoding: 'none' };
@@ -412,7 +439,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
       const d = deref(doc, schema);
       if (d?.type === 'array') return named(d.items);
       const props = propsOf(doc, schema);
-      if (props.data && deref(doc, props.data)?.type === 'array') return named(deref(doc, props.data).items);
+      if (props.data) return deref(doc, props.data)?.type === 'array' ? named(deref(doc, props.data).items) : named(props.data);
       const held = Object.values(props).filter((p) => !envelopeMeta(doc, p)).map((p) => (deref(doc, p)?.type === 'array' ? named(deref(doc, p).items) : named(p))).filter((n) => n.length);
       return held.length === 1 ? held[0]! : [];
     };
@@ -434,6 +461,16 @@ export function fromOpenAPI(spec: Json): SpecIR {
       const op = (item as Json)[method];
       if (!op) continue;
       const success = successOf(doc, op, resourceBySchema);
+      const responseMedia = Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, response]) => {
+        const media = Object.keys(deref(doc, response)?.content ?? {}).filter(binaryMedia).sort();
+        return media.length ? [[code, media]] : [];
+      }));
+      const defaultResponseMedia = Object.fromEntries(Object.entries(op.responses ?? {}).flatMap(([code, response]) => {
+        if (!responseMedia[code]) return [];
+        const media = Object.keys(deref(doc, response)?.content ?? {});
+        const defaultMedia = media.includes('application/json') ? 'application/json' : media.length === 1 ? media[0] : undefined;
+        return defaultMedia ? [[code, defaultMedia]] : [];
+      }));
       const streams = Object.entries(op.responses ?? {}).some(([code, r]) => /^2\d\d$/.test(code) && deref(doc, r)?.content?.['text/event-stream']);
       const security = (op.security ?? doc.security ?? []) as Json[];
       const scopes = [...new Set(security.flatMap((req: Json) => Object.values(req ?? {}).flat() as string[]))].sort();
@@ -452,6 +489,7 @@ export function fromOpenAPI(spec: Json): SpecIR {
         ...body,
         ...(scalars ? { scalars } : {}),
         successStatus: success.status,
+        ...(Object.keys(responseMedia).length ? { responseMedia, ...(Object.keys(defaultResponseMedia).length ? { defaultResponseMedia } : {}) } : {}),
         ...(success.empty ? { emptySuccess: true as const } : {}),
         ...(streams ? { streams: true } : {}),
         ...(scopes.length ? { scopes } : {}),

package/src/verdict.ts

@@ -0,0 +1,28 @@
+// A JUDGE'S INDEPENDENCE (the grade's outline-judged and life-judged, the published examples' verdict): a verdict rules
+// only when it names its judge (`judge.agent`) and the authors of what it judges (`authors`), and the judge is none of
+// them. The dispatcher stamps author names consistently; a judge started independently
+// (scripts/judge-brief.ts prints its brief) names its reviewer role (`judge.name`). One judging per pack: the
+// verdict stands, and later changes to what it judged keep it (architecture, "Writing a life", Judge).
+
+/** Committed attribution names people or author roles, never execution identities. */
+export function attributionName(name: string | undefined): string | undefined {
+  if (name === undefined) return undefined;
+  if (/\bcx-|\bt_[0-9a-f]{8}|wt\/|\/root(?:\/|$|[: )])|\b(?:pane|session)[ -:]|[0-9a-f]{8}-[0-9a-f-]{27}|\b[0-9a-f]{16,64}\b/i.test(name)) throw new Error('attribution must use an author name, not an execution identifier');
+  return name;
+}
+export type Verdict = { judge?: { agent?: string; name?: string; session?: string; review?: string }; authors?: string[] };
+
+/** Why the verdict is no verdict, or undefined when it rules. `author` is the name the judged file itself names as
+ *  its author (a life's `author`). */
+export function notIndependent(verdict: Verdict, author?: string): string | undefined {
+  const agent = attributionName(verdict.judge?.agent);
+  verdict.authors?.forEach(attributionName);
+  attributionName(author);
+  attributionName(verdict.judge?.session);
+  attributionName(verdict.judge?.review);
+  const session = attributionName(verdict.judge?.name ?? verdict.judge?.session);
+  if (/self-judged/i.test(session ?? '') || (!!author && session === author)) return 'self-judged (not a verdict)';
+  if (!agent || !verdict.authors?.length) return 'unattributed (the dispatcher has not stamped judge.agent and authors)';
+  if (verdict.authors.includes(agent)) return `the judge is among the authors (${agent})`;
+  return undefined;
+}