@volter/twin-standard 1.0.30 → 1.0.31

package/dist/src/published.js

@@ -2,14 +2,17 @@
 // 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 } from "./conformance.js";
 import { p3Gate } from "./gate.js";
 /** The vendor a package twins: its name without its scope and the `twin-` prefix (`@volter/twin-supabase` is supabase). */
 export const vendorOfPackage = (name) => 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, opts = {}) {
+/** `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(spec, opts, use) {
     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' });
@@ -22,15 +25,66 @@ export async function gatePublished(spec, opts = {}) {
         const name = JSON.parse(readFileSync(join(tmp, 'package', 'package.json'), 'utf8')).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) => 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) {
+    for (const from of [import.meta.url, join(process.cwd(), 'package.json')]) {
+        let at;
+        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')).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, opts = {}) {
+    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')).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, opts = {}) {
+    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) => u.slice(tmp.length + 1);
+        return { spec, failures: results.filter((r) => r.failures.length).map((r) => ({ unit: unit(r.unit), failures: r.failures })) };
+    });
+}

package/dist/src/spec-documents.js

@@ -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
@@ -17,7 +18,7 @@ export function readSpecDocuments(specDir) {
     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}`);

package/dist/src/spec-ir-client.d.ts

@@ -1,10 +1,13 @@
-import type { SpecIR } from './spec-ir.js';
+import type { IrOperation, IrResource, SpecIR } from './spec-ir.js';
 export type ClientCall = {
     /** the client method that makes the call, and its line */
     client: string;
     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';
@@ -16,5 +19,6 @@ export type ClientOpsSpec = {
     format: 'client';
     version: string;
     calls: ClientCall[];
+    resources?: IrResource[];
 };
 export declare function fromClientCalls(spec: ClientOpsSpec): SpecIR;

package/dist/src/spec-ir-client.js

@@ -36,6 +36,14 @@ export function fromClientCalls(spec) {
             byRoute.set(key, { first: call, path, labels, calls: [call] });
     }
     const operations = [...byRoute.values()].map(({ first, path, labels, calls }) => {
+        const declared = (key) => {
+            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();
         const body = new Map();
         const encodings = new Set();
@@ -62,7 +70,9 @@ export function fromClientCalls(spec) {
             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
@@ -73,5 +83,5 @@ export function fromClientCalls(spec) {
         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/dist/src/spec-ir.d.ts

@@ -1,5 +1,7 @@
 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 declare const binaryMedia: (media: string) => boolean;
 export declare const CRUD_CLASSES: ReadonlySet<OperationClass>;
 /** 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. */
@@ -7,8 +9,8 @@ export type IrParam = {
     name: string;
     type: string;
     required: boolean;
-    minimum?: number;
-    maximum?: number;
+    minimum?: number | string;
+    maximum?: number | string;
 };
 export type IrOperation = {
     /** The spec's operationId, or the `method_path` slug when the spec has none. */
@@ -36,6 +38,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`). */

package/dist/src/spec-ir.js

@@ -1,14 +1,11 @@
-// 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`
-// reads an AWS Smithy JSON model
-// (OpenAPI 3.x; Stripe's vendor extensions `x-resourceId` and `x-expandableFields` are read where
-// present). Pure and deterministic: the same document always yields the same IR, byte for byte.
+import { isExactIntegerValue } from '@volter/world-core/exact-json';
+/** Binary media whose resource shape is the response bytes, rather than JSON metadata. */
+export const binaryMedia = (media) => /^(?:application\/(?:octet-stream|pdf|zip|gzip)|(?:image|audio|video)\/[^/]+)$/.test(media.toLowerCase());
 export const CRUD_CLASSES = new Set(['create', 'retrieve', 'list', 'update', 'delete']);
 /** A schema's stated numeric bounds, when it states any. */
 function boundsOf(doc, schema) {
     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 } : {}) };
 }
 // every operation an OpenAPI path item may hold (a HEAD is as published as a GET: Vercel's /v8/artifacts/{hash})
 const METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options', 'trace'];
@@ -180,6 +177,19 @@ function successOf(doc, op, resources) {
     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).
@@ -218,7 +228,17 @@ function paramsOf(doc, op, pathItem) {
     return { pathParams, query };
 }
 function bodyOf(doc, op) {
-    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) => {
+        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' };
     const encoding = content[mediaOf.json] ? 'json' : content[mediaOf.form] ? 'form' : content[mediaOf.multipart] ? 'multipart' : 'none';
     if (encoding === 'none')
@@ -384,8 +404,8 @@ export function fromOpenAPI(spec) {
             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] : [];
         };
@@ -408,6 +428,17 @@ export function fromOpenAPI(spec) {
             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 ?? []);
             const scopes = [...new Set(security.flatMap((req) => Object.values(req ?? {}).flat()))].sort();
@@ -426,6 +457,7 @@ export function fromOpenAPI(spec) {
                 ...body,
                 ...(scalars ? { scalars } : {}),
                 successStatus: success.status,
+                ...(Object.keys(responseMedia).length ? { responseMedia, ...(Object.keys(defaultResponseMedia).length ? { defaultResponseMedia } : {}) } : {}),
                 ...(success.empty ? { emptySuccess: true } : {}),
                 ...(streams ? { streams: true } : {}),
                 ...(scopes.length ? { scopes } : {}),

package/dist/src/verdict.d.ts

@@ -0,0 +1,14 @@
+/** Committed attribution names people or author roles, never execution identities. */
+export declare function attributionName(name: string | undefined): string | undefined;
+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 declare function notIndependent(verdict: Verdict, author?: string): string | undefined;

package/dist/src/verdict.js

@@ -0,0 +1,30 @@
+// 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) {
+    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;
+}
+/** 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, author) {
+    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;
+}

package/dist/src/walk/behavior-journey.d.ts

@@ -0,0 +1,47 @@
+import { type TwinStream } from '@volter/world-core/runtime';
+import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type RespStep } from './journey-kit.js';
+export declare function usePacks(dir: string): void;
+/** The walk's World: the twin's own code on its in-memory World and blob stores (the backends a serverless
+ *  entry runs on), so a walk of any length is state changes in memory and never touches the disk; the World
+ *  clock, pinned to 2026-01-01, is world state in the same store, and the World is sealed. Each root is a fresh key
+ *  space in it.
+ *  Restored after ONE run: this module is imported by journey-walk.test.ts, and a store or clock left active
+ *  would leak into whichever suite the sweep runs next. */
+export declare function inMemoryWorld(label: string): {
+    root: () => string;
+    restore: () => void;
+};
+export type Failure = {
+    step: string;
+    beat: string;
+    detail: string;
+};
+/** What a caller that scores a walk observes around each step: the step, its resolved path and body,
+ *  and (after) the answer and the failures the step produced. */
+export type StepHooks = {
+    before?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, body: unknown) => void;
+    after?: (step: JourneyStep | LineStep | GitStep | RespStep, path: string, answer: {
+        status: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }, failures: Failure[]) => void;
+};
+/** A pack served for a walk the way a World runs it (its server.ts on a port, the World's root and scenario its options):
+ *  the walk's requests go to it over HTTP, the vendor's host in their Host header, instead of to the fetch in process;
+ *  its sockets are WebSockets to that port, and a line connection (`stream`) is a TCP connection to its protocol port. */
+export type ServedTwin = (root: string, options: {
+    scenarioPath?: string;
+}) => Promise<{
+    fetch: (request: Request) => Promise<Response>;
+    stop: () => void;
+    socket?: (url: string, headers: Record<string, string>) => WebSocket;
+    stream?: TwinStream;
+}>;
+export declare function walk(journey: Journey, root: string, collect: Failure[], opts: {
+    beats: boolean;
+    verbose?: boolean;
+    hooks?: StepHooks;
+    captured?: Captured;
+    served?: ServedTwin;
+}): Promise<Captured>;
+export declare function withPinnedWorldDraws<T>(fn: () => Promise<T>): Promise<T>;