@volter/twin-standard 1.0.158 → 1.0.159

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +3 -2
  2. package/client-sdks/package.json +1 -0
  3. package/client-sdks/pnpm-lock.yaml +210 -0
  4. package/dist/client-sdks/package.json +1 -0
  5. package/dist/client-sdks/pnpm-lock.yaml +210 -0
  6. package/dist/src/assessment.d.ts +13 -3
  7. package/dist/src/assessment.js +10 -6
  8. package/dist/src/browser-assessment.js +16 -13
  9. package/dist/src/clients/harness.d.ts +25 -4
  10. package/dist/src/clients/harness.js +184 -22
  11. package/dist/src/clients/jira.js +11 -2
  12. package/dist/src/clients/run.js +19 -14
  13. package/dist/src/conformance.d.ts +2 -0
  14. package/dist/src/conformance.js +392 -184
  15. package/dist/src/consumer.d.ts +22 -1
  16. package/dist/src/consumer.js +91 -26
  17. package/dist/src/credential-issuer-import.d.ts +3 -0
  18. package/dist/src/credential-issuer-import.js +42 -0
  19. package/dist/src/derive.js +3 -0
  20. package/dist/src/gate.js +4 -0
  21. package/dist/src/lanes.d.ts +2 -0
  22. package/dist/src/lanes.js +7 -0
  23. package/dist/src/protocol-3.js +8 -3
  24. package/dist/src/spec-documents.d.ts +4 -0
  25. package/dist/src/spec-documents.js +110 -3
  26. package/dist/src/tools/life-coverage-walk.js +38 -26
  27. package/dist/src/tools/score-pack.js +6 -5
  28. package/dist/src/tools/vendor-examples.js +91 -80
  29. package/dist/src/walk/behavior-journey.d.ts +22 -14
  30. package/dist/src/walk/behavior-journey.js +182 -133
  31. package/dist/src/walk/journey-kit.d.ts +3 -2
  32. package/dist/src/walk/journey-kit.js +6 -2
  33. package/dist/src/walk/replay.d.ts +23 -0
  34. package/dist/src/walk/replay.js +118 -0
  35. package/dist/src/walk/serve-pack.d.ts +2 -2
  36. package/dist/src/walk/serve-pack.js +38 -2
  37. package/dist/src/walk/shape.d.ts +25 -4
  38. package/dist/src/walk/shape.js +166 -56
  39. package/dist/src/walk/vendor-fetch.d.ts +7 -2
  40. package/dist/src/walk/vendor-fetch.js +13 -2
  41. package/dist/src/walk/walk-database.d.ts +9 -1
  42. package/dist/src/walk/walk-database.js +35 -13
  43. package/dist/src/walk/xml-view.d.ts +3 -2
  44. package/dist/src/walk/xml-view.js +5 -4
  45. package/package.json +3 -3
  46. package/src/assessment.ts +12 -8
  47. package/src/browser-assessment.ts +12 -5
  48. package/src/clients/harness.ts +142 -19
  49. package/src/clients/jira.ts +4 -2
  50. package/src/clients/run.ts +17 -15
  51. package/src/conformance.ts +313 -128
  52. package/src/consumer.ts +83 -21
  53. package/src/credential-issuer-import.ts +38 -0
  54. package/src/derive.ts +3 -1
  55. package/src/gate.ts +3 -0
  56. package/src/lanes.ts +7 -0
  57. package/src/protocol-3.ts +7 -3
  58. package/src/spec-documents.ts +92 -3
  59. package/src/tools/life-coverage-walk.ts +32 -22
  60. package/src/tools/score-pack.ts +7 -6
  61. package/src/tools/vendor-examples.ts +88 -75
  62. package/src/walk/behavior-journey.ts +145 -109
  63. package/src/walk/journey-kit.ts +7 -5
  64. package/src/walk/replay.ts +103 -0
  65. package/src/walk/serve-pack.ts +25 -5
  66. package/src/walk/shape.ts +156 -54
  67. package/src/walk/vendor-fetch.ts +16 -4
  68. package/src/walk/walk-database.ts +41 -15
  69. package/src/walk/xml-view.ts +5 -4
@@ -1,4 +1,4 @@
1
- import { hasOwnSurface } from './lanes.ts';
1
+ import { hasOwnSurface, unitsIn } from './lanes.ts';
2
2
  // CONFORMANCE — the deterministic half of the Protocol 3 standard that executes the pack: the contract it serves, run the
3
3
  // way an application calls it, and every rule a pack's author follows that a machine can decide (docs/contributing/
4
4
  // architecture.md, "Conformance"). One command, the same for a contributor, the catalog's admission and its regular
@@ -11,18 +11,26 @@ import { hasOwnSurface } from './lanes.ts';
11
11
  // judges (the life's plausibility) is the proof section's. Each check names the defect it was written against: one
12
12
  // that escaped review once fails here when reintroduced.
13
13
  import { spawn, spawnSync } from 'node:child_process';
14
- import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
14
+ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
15
15
  import { createRequire } from 'node:module';
16
16
  import { connect } from 'node:net';
17
17
  import { tmpdir } from 'node:os';
18
18
  import { basename, dirname, extname, join, matchesGlob, relative, resolve, sep } from 'node:path';
19
19
  // A path relative to another with '/' between its parts on every platform (Windows' relative() joins with '\').
20
20
  const rel = (from: string, to: string): string => relative(from, to).split(sep).join('/');
21
- import type { TwinStream } from '@volter/world-core';
21
+ import type { PackDescriptor, TwinStream } from '@volter/world-core';
22
+ import { hostRules } from '@volter/world-core/host-routing';
23
+ import { twinEnvStem } from '@volter/world-core/vendor-hosts';
24
+ import type { DerivedManifest, ErrorSpec, RemoteExecuteResponse, StateSystemAdapters, TwinAuthStrategy } from '@volter/world-core/runtime';
22
25
  import { citations, sourceHeld, type SourceRecord } from './check-sources.ts';
23
26
  import { fileURLToPath } from 'node:url';
24
- import { servedHttpFetch } from './clients/harness.ts';
27
+ import { parseEnv } from 'node:util';
28
+ import { openWebSocket, readHttpResponse, servedHttpFetch, worldProxy } from './clients/harness.ts';
25
29
  import { servePack as serve, type ServedPack as Served } from './walk/serve-pack.ts';
30
+ import { walkPackDirectory } from './walk/pack-directory.ts';
31
+ import { formBody, sigv4Headers } from './walk/journey-kit.ts';
32
+ import { consumerClientProof, consumerRecipe, runConsumerCommand, type ConsumerResult } from './consumer.ts';
33
+ import { declaredResponseStatuses } from './spec-documents.ts';
26
34
 
27
35
  export type ConformanceResult = { id: string; asks: string; failures: string[]; note?: string };
28
36
 
@@ -39,12 +47,30 @@ type Manifest = {
39
47
  const pascal = (s: string): string => s.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0]!.toUpperCase() + w.slice(1)).join('');
40
48
  const readJson = (p: string): unknown => (existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : undefined);
41
49
 
42
- /** The pack's units: the pack and each lane in it (a directory with its own src/manifest.ts and no package.json). */
43
- function unitsIn(pack: string): string[] {
44
- return [pack, ...readdirSync(pack).sort().map((n) => join(pack, n)).filter((d) => !existsSync(join(d, 'package.json')) && existsSync(join(d, 'src', 'manifest.ts')))];
50
+ /** Exercise the door's declared organization and deployment, as the World renderer does. */
51
+ function credentialDoorBody(door: NonNullable<PackDescriptor['credentialDoor']>): string {
52
+ return JSON.stringify({ ...door.body, ...(door.account ? { [door.account.field]: 'default' } : {}), ...(door.deployment ? { [door.deployment.field]: 'conformance' } : {}) });
45
53
  }
54
+
46
55
  const nameOf = (pack: string, unit: string): string => rel(resolve(pack, '..'), unit);
47
56
 
57
+ /** A credential door's native successful object and nonempty string outputs, through the served HTTP owner. */
58
+ async function credentialFields(server: Served, door: NonNullable<PackDescriptor['credentialDoor']>, host?: string): Promise<{ values: Record<string, unknown>; outputs: Record<string, string> }> {
59
+ await server.managedDatabaseUrl?.();
60
+ const port = server.inspectPort ?? server.port;
61
+ const answer = await readHttpResponse(servedHttpFetch(port), new Request(`http://${host ?? `127.0.0.1:${port}`}${door.path}`, {
62
+ method: 'POST', headers: { 'content-type': 'application/json', 'x-volter-world-activity': 'provisioning' }, body: credentialDoorBody(door),
63
+ }));
64
+ if (answer.bodyError) throw new Error(`credential door ${door.path}: ${answer.bodyError.message}`);
65
+ if (answer.status < 200 || answer.status >= 300) throw new Error(`credential door ${door.path} answered ${answer.status}`);
66
+ const { decodeResponse } = await import('./walk/shape.ts');
67
+ const values = decodeResponse(answer.text, undefined);
68
+ if (!values || typeof values !== 'object' || Array.isArray(values)) throw new Error(`credential door ${door.path} supplies no JSON object`);
69
+ const fields = values as Record<string, unknown>;
70
+ const outputs = Object.fromEntries(Object.entries(door.fill).flatMap(([name, field]) => typeof fields[field] === 'string' && fields[field] ? [[name, fields[field] as string]] : []));
71
+ return { values: fields, outputs };
72
+ }
73
+
48
74
  /** The files conformance reads from a unit: its manifest, its spec's record, its vendor's life and its decision table
49
75
  * (a lane's journeys are its own `journeys/` or else its vendor's). A release publishes each (published()), and a
50
76
  * pack's standing counts it in the form only when every unit holds them (twin-world's scripts/pack-standing.ts, by
@@ -280,10 +306,11 @@ async function allowance(pack: string, runtime: Runtime): Promise<string[]> {
280
306
  }
281
307
 
282
308
  type Runtime = {
283
- getPack: (vendor: string) => { stateSystem?: { perform?: unknown; refresh?: unknown } } | undefined;
309
+ getPack: (vendor: string) => { stateSystem?: StateSystemAdapters } | undefined;
284
310
  DEFAULT_RATE_BUDGET: NonNullable<Manifest['rateBudget']>;
311
+ worldNow: () => string;
312
+ vendorError: (manifest: DerivedManifest, error: ErrorSpec) => Response;
285
313
  };
286
- const within = <T>(ms: number, p: Promise<T>): Promise<T | 'timeout'> => Promise.race([p, new Promise<'timeout'>((r) => setTimeout(() => r('timeout'), ms))]);
287
314
 
288
315
  /** Served by its server.ts as a World runs it (its boot id set), the pack answers HTTP and the boot probe, and every socket
289
316
  * its manifests declare takes an upgrade. Escaped twice: serveHttp never took the upgrade a pack's fetch carries, then
@@ -294,24 +321,23 @@ async function standalone(pack: string): Promise<string[]> {
294
321
  const sockets: Array<{ unit: string; path: string; host?: string }> = [];
295
322
  for (const unit of unitsIn(pack)) for (const s of (await manifestOf(unit)).sockets ?? []) sockets.push({ unit: nameOf(pack, unit), path: s.path, ...(s.host ? { host: s.host } : {}) });
296
323
  // served the way a World runs it: the boot id set, so the seam wraps the fetch with the World's boot probe
297
- const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
298
- const before = env.VOLTER_WORLD_BOOT_ID;
299
- env.VOLTER_WORLD_BOOT_ID = 'conformance';
300
- let server: Served;
301
- try { server = await serve(pack, {}); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
324
+ const server = await serve(pack, {});
302
325
  try {
303
- const http = await within(5000, fetch(`http://127.0.0.1:${(server.inspectPort ?? server.port)}/`).then((r) => r.status, (e: Error) => e.message));
304
- if (http === 'timeout' || typeof http === 'string') out.push(`served as a World runs it, it answers no HTTP request (${http})`);
305
- const boot = await within(5000, fetch(`http://127.0.0.1:${(server.inspectPort ?? server.port)}/__volter/world-boot`).then((r) => r.json() as Promise<{ boot?: string }>, (): { boot?: string } => ({})));
306
- if (boot === 'timeout' || boot.boot !== 'conformance') out.push("served as a World runs it, it does not answer the World's boot probe (/__volter/world-boot)");
326
+ const http = servedHttpFetch(server.inspectPort ?? server.port);
327
+ const probe = (path: string) => readHttpResponse(http, new Request(`http://127.0.0.1:${server.inspectPort ?? server.port}${path}`, { signal: AbortSignal.timeout(5000) }));
328
+ try {
329
+ const answer = await probe('/');
330
+ if (answer.bodyError) out.push(`served as a World runs it, its HTTP response failed (${answer.bodyError.message})`);
331
+ } catch (error) { out.push(`served as a World runs it, it answers no HTTP request (${String(error)})`); }
332
+ try {
333
+ const boot = await probe('/__volter/world-boot');
334
+ if (boot.bodyError || (JSON.parse(boot.text) as { boot?: string }).boot !== 'conformance') throw new Error('missing boot identity');
335
+ } catch { out.push("served as a World runs it, it does not answer the World's boot probe (/__volter/world-boot)"); }
307
336
  for (const s of sockets) {
308
- const upgraded = await new Promise<string | undefined>((done) => {
309
- const ws = new WebSocket(`ws://127.0.0.1:${server.port}${s.path}`, { headers: s.host ? { host: s.host } : {} } as unknown as string[]);
310
- const timer = setTimeout(() => { ws.close(); done('no upgrade in 5 s'); }, 5000);
311
- ws.onopen = () => { clearTimeout(timer); ws.close(); done(undefined); };
312
- ws.onerror = () => { clearTimeout(timer); done('the upgrade was refused'); };
313
- });
314
- if (upgraded) out.push(`${s.unit}: the socket at ${s.host ?? ''}${s.path}: ${upgraded}`);
337
+ const ws = new WebSocket(`ws://127.0.0.1:${server.port}${s.path}`, { headers: s.host ? { host: s.host } : {} } as unknown as string[]);
338
+ const upgraded = await openWebSocket(ws);
339
+ if (upgraded) ws.close();
340
+ else out.push(`${s.unit}: the socket at ${s.host ?? ''}${s.path}: no upgrade in 5 s or the upgrade was refused`);
315
341
  }
316
342
  } finally { await server.stop(); }
317
343
  return out;
@@ -321,7 +347,6 @@ type SweptOperation = {
321
347
  id: string; method: string; path: string; basePath?: string; pathParams?: string[];
322
348
  query?: Array<{ name: string; type?: string; required?: boolean }>; body?: Array<{ name: string; required?: boolean }>;
323
349
  bodyEncoding?: string; headers?: Record<string, string | null>; discriminator?: Record<string, string | null>;
324
- responseMedia?: Record<string, string[]>; answers?: unknown;
325
350
  };
326
351
 
327
352
  /** The request an application's first call of an operation sends when it knows nothing yet: every path parameter, every
@@ -337,109 +362,292 @@ function sweepRequest(op: SweptOperation, basePath: string, host: string, creden
337
362
  const headers = new Headers(credential);
338
363
  for (const [name, value] of Object.entries(op.headers ?? {})) headers.set(name, value ?? fill(name));
339
364
  const method = op.method.toUpperCase();
340
- let body: string | undefined;
365
+ let body: BodyInit | undefined;
341
366
  if (op.bodyEncoding === 'form') { headers.set('content-type', 'application/x-www-form-urlencoded'); body = ''; }
342
367
  else if (op.bodyEncoding === 'xml') { headers.set('content-type', 'application/xml'); body = ''; }
343
- else if (op.bodyEncoding === 'json' || op.bodyEncoding === 'multipart') { headers.set('content-type', 'application/json'); body = '{}'; }
368
+ else if (op.bodyEncoding === 'json') { headers.set('content-type', 'application/json'); body = '{}'; }
369
+ else if (op.bodyEncoding === 'multipart') { const formed = formBody({ parts: [] }, {}); headers.set('content-type', formed.contentType); body = formed.bytes; }
344
370
  return new Request(url, { method, headers, ...(body !== undefined && !['GET', 'HEAD'].includes(method) ? { body } : {}) });
345
371
  }
346
372
 
373
+ /** Obtain authorization through the existing customer recipe, with any declared issuer on the same World as the API. */
374
+ async function consumerAuthorization(pack: string, scratch: string, root: string, server: Served, descriptor: PackDescriptor, outputs: Record<string, string>, claimsAuthorization: (hostname: string, pathname: string) => boolean, consumer?: ConsumerResult): Promise<{ headers: Record<string, string>; url: URL }> {
375
+ const vendor = (await manifestOf(pack)).vendor ?? basename(pack);
376
+ const issuer = descriptor.credentialIssuer;
377
+ const companion = issuer ? walkPackDirectory(dirname(pack), issuer, pack) : undefined;
378
+ if (issuer && !companion) throw new Error(`${vendor}: its declared credential issuer ${issuer} is not installed`);
379
+ const issuerDoor = companion ? ((await manifestOf(companion)) as { descriptor?: PackDescriptor }).descriptor?.credentialDoor : undefined;
380
+ if (companion && !issuerDoor) throw new Error(`${issuer}: its declared credential door is missing`);
381
+ const recipe = consumerRecipe(vendor, pack);
382
+ if (!consumer) throw new Error(`${vendor}: native authorization requires its prepared installed customer application`);
383
+ mkdirSync(scratch, { recursive: true });
384
+ const appDir = consumer.appDir;
385
+ for (const [path, contents] of Object.entries(recipe.files)) if (path !== 'package.json' && path !== '.gitignore' && readFileSync(join(appDir, path), 'utf8') !== contents) throw new Error(`${vendor}: its prepared customer file ${path} differs from its native first-use recipe`);
386
+ const proxies: Array<Awaited<ReturnType<typeof worldProxy>>> = [];
387
+ let servedIssuer: Served | undefined;
388
+ let granted: { headers: Record<string, string>; url: URL } | undefined;
389
+ const { forwardableHeaders } = await import('@volter/world-runtime');
390
+ try {
391
+ const env = { ...outputs };
392
+ if (companion && issuerDoor) {
393
+ servedIssuer = await serve(companion, { root });
394
+ Object.assign(env, (await credentialFields(servedIssuer, issuerDoor)).outputs);
395
+ }
396
+ const credentialNames = new Set([...Object.keys(descriptor.credentialDoor?.fill ?? {}), ...Object.keys(issuerDoor?.fill ?? {})]);
397
+ for (const name of Object.keys(parseEnv(recipe.files['.env.example']!))) if (credentialNames.has(name) && !env[name]) throw new Error(`${vendor}: its native credential doors supplied no ${name}`);
398
+ const selectedProxy = await worldProxy(server.inspectPort ?? server.port, (request, response) => {
399
+ const url = new URL(request.url);
400
+ if (response.status >= 200 && response.status < 300 && !url.pathname.startsWith('/_twin/') && claimsAuthorization(url.hostname, url.pathname)) {
401
+ const headers = forwardableHeaders(request.headers);
402
+ for (const name of [...headers.keys()]) if (/^(host|forwarded|x-forwarded-.*|x-volter-.*|x-twins-key|proxy-.*|via|content-.*|digest)$/i.test(name)) headers.delete(name);
403
+ granted = { headers: Object.fromEntries(headers), url };
404
+ }
405
+ });
406
+ proxies.push(selectedProxy);
407
+ const selected = [{ vendor, dir: pack, port: selectedProxy.port }];
408
+ if (issuer && companion && servedIssuer) {
409
+ const issuerProxy = await worldProxy(servedIssuer.inspectPort ?? servedIssuer.port);
410
+ proxies.push(issuerProxy);
411
+ selected.push({ vendor: issuer, dir: companion, port: issuerProxy.port });
412
+ }
413
+ const { compilePackFacts, renderPackFacts } = await import('./pack-facts.ts');
414
+ const facts = await compilePackFacts(selected.map(({ vendor, dir }) => ({ vendor, dir })));
415
+ if (facts.undeclared.length) throw new Error('Customer authorization requires declared pack descriptors');
416
+ const packFacts = join(scratch, 'pack-facts.json');
417
+ writeFileSync(packFacts, renderPackFacts(facts));
418
+ const instance = join(scratch, 'instance.json');
419
+ writeFileSync(instance, JSON.stringify({ packFacts: [packFacts] }));
420
+ const routes = Object.fromEntries(selected.flatMap(({ vendor, port }) => (facts.packs[vendor]?.hosts ?? []).map((rule) => [rule.key ?? vendor, `http://127.0.0.1:${port}`])));
421
+ const endpoints = Object.fromEntries(Object.entries(routes).map(([key, url]) => [`${twinEnvStem(key)}_TWIN_URL`, url]));
422
+ const require = createRequire(join(pack, 'package.json'));
423
+ const inject = require.resolve('@volter/world-core/inject');
424
+ const result = await runConsumerCommand(recipe.run, appDir, {
425
+ ...process.env, ...endpoints, ...env, VOLTER_WORLD_INSTANCE: instance,
426
+ TWIN_INJECT: Object.entries(routes).map(([name, url]) => `${name}=${url}`).join(','),
427
+ NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require ${JSON.stringify(inject)}`.trim(),
428
+ VOLTER_TWIN_STRICT_EGRESS: '1',
429
+ }, AbortSignal.timeout(10_000));
430
+ if (result.exitCode !== 0) throw new Error(`${vendor}: its native first-use command exited ${result.exitCode}`);
431
+ if (!granted) throw new Error(`${vendor}: its native first-use command made no successful authorized request to the selected API`);
432
+ return granted;
433
+ } finally {
434
+ const cleanup = await Promise.allSettled([...proxies.map((proxy) => proxy.stop()), ...(servedIssuer ? [Promise.resolve().then(() => servedIssuer!.stop())] : [])]);
435
+ const failed = cleanup.find((result) => result.status === 'rejected');
436
+ if (failed?.status === 'rejected') throw failed.reason;
437
+ }
438
+ }
439
+
347
440
  /** Every operation the pack serves, called over HTTP as an application calls it, against its server.ts served as a World
348
441
  * runs it: once plainly and once with a scenario loaded (an empty one, as a World that scripts nothing loads it). Each
349
442
  * answers within 10 s, never with a 500 the spec does not declare, never with a field of the twin's own (`_`
350
443
  * bookkeeping, the kernel's `updatedAt`) and, answered successfully, in the shape the spec gives the operation; and every
351
- * refresh list a fresh account can read (one with no parameter in its path) answers it successfully, so a World rooted
352
- * at this twin reads its resources back. Escaped before: the scenario hang (a served pack given a scenario answered
444
+ * refresh list a fresh account can read (one with no parameter in its path) succeeds or remains unread under the
445
+ * native 403 contract while another read succeeds, or matches the pack's own removal at the World clock.
446
+ * Escaped before: the scenario hang (a served pack given a scenario answered
353
447
  * nothing), leaked kernel fields in answers no life step read, and refresh scopes on operations the pack answered with
354
448
  * the gap. The life walks what a customer does; this calls what the pack declares it serves. */
355
- async function surfaceSwept(pack: string, scratch: string): Promise<{ failures: string[]; note: string }> {
449
+ async function surfaceSwept(pack: string, scratch: string, runtime: Runtime, consumer?: ConsumerResult): Promise<{ failures: string[]; note: string }> {
356
450
  const out: string[] = [];
357
- const descriptor = ((await manifestOf(pack)) as { descriptor?: { hosts?: Array<{ host?: string }>; credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> } } }).descriptor;
451
+ const descriptor = ((await manifestOf(pack)) as { descriptor?: PackDescriptor }).descriptor;
358
452
  const fetchOf = ((await import(join(pack, 'src', 'fetch.ts'))) as Record<string, unknown>)[fetchName(pack)] as (() => { owners?: () => Owners; ownersByUnit?: () => Record<string, Owners> }) | undefined;
359
453
  const root = fetchOf?.();
360
454
  const byUnit = root?.ownersByUnit?.() ?? { '': root?.owners?.() ?? {} };
361
- const { shapeChecker } = await import('./walk/shape.ts');
362
- const { leaked } = await import('./walk/behavior-journey.ts');
455
+ const { decodeResponse, responseProblems, shapeChecker, vendorFieldsOf } = await import('./walk/shape.ts');
363
456
  const shape = await shapeChecker(pack);
364
- type Unit = { name: string; host: string; basePath: string; ops: SweptOperation[]; refreshLists: Array<{ resource: string; id: string }>; auth?: { header: string; scheme: string } };
457
+ type Unit = { name: string; lane: string; hosts: NonNullable<PackDescriptor['hosts']>; basePath: string; manifest: DerivedManifest; ops: SweptOperation[]; responseStatuses: Map<string, Set<string>>; refreshLists: Array<{ resource: string; id: string }>; refreshReads: string[]; auth?: { header: string; scheme: string }; strategy?: TwinAuthStrategy; removedAt?: (operation: string, now: number) => ErrorSpec | undefined };
365
458
  const units: Unit[] = [];
366
- const vendorFields = new Set<string>();
459
+ const vendorFields = await vendorFieldsOf(pack);
367
460
  for (const unit of unitsIn(pack).filter(hasOwnSurface)) {
368
- const surface = readJson(join(unit, 'src', 'generated', 'surface.gen.json')) as { format?: string; basePath?: string; operations?: SweptOperation[]; resources?: Array<{ fields: Array<{ name: string }> }> } | undefined;
369
- for (const r of surface?.resources ?? []) for (const f of r.fields) vendorFields.add(f.name);
461
+ const surface = readJson(join(unit, 'src', 'generated', 'surface.gen.json')) as { format?: string; basePath?: string; operations?: SweptOperation[] } | undefined;
462
+ const m = (await manifestOf(unit)) as Manifest & { hosts?: PackDescriptor['hosts']; descriptor?: Omit<PackDescriptor, 'vendor'>; auth?: { header: string; scheme: string } };
370
463
  // a line protocol and a command table ride in no path of their own: the life's line steps and the examples read them
371
464
  if (!surface?.operations || ['command-reply', 'command-table'].includes(String(surface.format))) continue;
372
- const m = (await manifestOf(unit)) as Manifest & { hosts?: Array<{ host?: string }>; auth?: { header: string; scheme: string } };
373
- const host = m.hosts?.find((h) => h.host)?.host ?? descriptor?.hosts?.find((h) => h.host)?.host;
374
- if (!host) { out.push(`${nameOf(pack, unit)}: no host is named (its manifest's hosts or the descriptor's) for an application to call it at`); continue; }
465
+ const hosts = m.hosts ?? m.descriptor?.hosts ?? descriptor?.hosts ?? [];
466
+ if (!hosts.length) { out.push(`${nameOf(pack, unit)}: no host is claimed (its manifest's hosts or the descriptor's) for an application to call it at`); continue; }
375
467
  const owners = byUnit[unit === pack ? '' : basename(unit)] ?? {};
376
468
  const refreshLists = Object.entries(m.resources ?? {}).flatMap(([resource, decl]) => (decl.refresh?.list ? [{ resource, id: decl.refresh.list }] : []));
377
- units.push({ name: nameOf(pack, unit), host, basePath: surface.basePath ?? '', ops: surface.operations.filter((o) => owners[o.id] !== undefined && owners[o.id] !== 'gap'), refreshLists, ...(m.auth ? { auth: m.auth } : {}) });
469
+ const refreshReads = Object.values(m.resources ?? {}).flatMap((decl) => [decl.refresh?.list, decl.refresh?.get, decl.refresh?.detail].filter((id): id is string => !!id));
470
+ const declaredAuth = m.descriptor?.auth ?? descriptor?.auth;
471
+ const strategy = declaredAuth?.in === 'lanes' ? declaredAuth.lanes[unit === pack ? '' : basename(unit)] : declaredAuth;
472
+ const shared = join(unit, 'src/semantics/shared.ts');
473
+ const removedAt = existsSync(shared) ? ((await import(shared)) as { removedAt?: Unit['removedAt'] }).removedAt : undefined;
474
+ units.push({ name: nameOf(pack, unit), lane: unit === pack ? '' : basename(unit), hosts, basePath: surface.basePath ?? '', manifest: m as DerivedManifest, ops: surface.operations.filter((o) => owners[o.id] !== undefined && owners[o.id] !== 'gap'), responseStatuses: declaredResponseStatuses(join(unit, 'spec')), refreshLists, refreshReads, ...(m.auth ? { auth: m.auth } : {}), ...(strategy ? { strategy } : {}), ...(typeof removedAt === 'function' ? { removedAt } : {}) });
378
475
  }
379
476
  if (!units.length) return { failures: out, note: 'no unit serves an operation on a path of its own' };
380
- const tally = { calls: 0, ok: 0, refused: 0 };
381
- const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
477
+ const tally = { calls: 0, ok: 0, refused: 0, unread: 0, removed: 0 };
478
+ const replayedHeaders = new Set<string>();
382
479
  const scenarioPath = join(scratch, 'surface-scenario.json');
383
480
  writeFileSync(scenarioPath, '{"handlers":[]}');
384
481
  for (const mode of ['plain', 'scenario'] as const) {
385
- const before = env.VOLTER_WORLD_BOOT_ID;
386
- env.VOLTER_WORLD_BOOT_ID = 'conformance';
387
- let server: Served;
388
- try { server = await serve(pack, { root: join(scratch, `surface-${mode}`), ...(mode === 'scenario' ? { scenarioPath } : {}) }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
482
+ const root = join(scratch, `surface-${mode}`);
483
+ const server = await serve(pack, { root, ...(mode === 'scenario' ? { scenarioPath } : {}) });
389
484
  const http = servedHttpFetch(server.inspectPort ?? server.port);
390
- const send = async (request: Request): Promise<Response | 'timeout' | Error> => {
485
+ const send = async (request: Request): Promise<Awaited<ReturnType<typeof readHttpResponse>> | Error> => {
391
486
  await server.managedDatabaseUrl?.();
392
- const abort = new AbortController();
393
- try { return await within(10_000, http(request, { signal: abort.signal })); } catch (error) { return error as Error; } finally { abort.abort(); }
487
+ try { return await readHttpResponse(http, request); } catch (error) { return error instanceof Error ? error : new Error(String(error)); }
394
488
  };
395
489
  try {
490
+ const said = mode === 'scenario' ? ' with a scenario loaded' : '';
396
491
  // the account an application holds: the key the credential door issues, sent as the vendor reads its credential
397
492
  let issued: string | undefined;
493
+ let nativeHeaders: Record<string, string> | undefined;
494
+ let recipeAuthorized = false;
495
+ let nativeUrl: URL | undefined;
496
+ const outputs: Record<string, string> = {};
398
497
  if (descriptor?.credentialDoor) {
399
498
  const door = descriptor.credentialDoor;
400
- const answer = await send(new Request(`https://${descriptor.hosts?.find((h) => h.host)?.host ?? units[0]!.host}${door.path}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(door.body) }));
401
- const fields = answer instanceof Response ? ((await answer.json().catch(() => ({}))) as Record<string, unknown>) : {};
402
- issued = Object.values(door.fill).map((f) => fields[f]).find((v): v is string => typeof v === 'string');
499
+ const fields = await credentialFields(server, door);
500
+ const values = fields.values;
501
+ Object.assign(outputs, fields.outputs);
502
+ issued = Object.values(door.fill).map((f) => values[f]).find((v): v is string => typeof v === 'string' && v.length > 0);
503
+ if (typeof values.authorization === 'string' && values.authorization) {
504
+ nativeHeaders = { authorization: values.authorization };
505
+ if (typeof values.url === 'string') {
506
+ try { nativeUrl = new URL(values.url); } catch { out.push(`${nameOf(pack, pack)}: credential door supplies an invalid native url`); continue; }
507
+ if (nativeUrl.protocol !== 'https:' || nativeUrl.username || nativeUrl.password) { out.push(`${nameOf(pack, pack)}: credential door supplies a native url without a vendor HTTPS origin`); continue; }
508
+ }
509
+ }
510
+ }
511
+ const headerUnits = units.filter((unit) => !unit.strategy);
512
+ const ambiguousHeaderCredential = !nativeHeaders && new Set(Object.values(outputs)).size > 1 && headerUnits.length > 0
513
+ && Object.keys(parseEnv(consumerRecipe((await manifestOf(pack)).vendor ?? basename(pack), pack).files['.env.example']!)).some((name) => outputs[name]);
514
+ if (descriptor && (descriptor.credentialIssuer || ambiguousHeaderCredential)) {
515
+ const headerClaims = headerUnits.map((unit) => hostRules(unit.hosts));
516
+ const otherClaims = units.filter((unit) => unit.strategy).map((unit) => hostRules(unit.hosts));
517
+ const claimsAuthorization = descriptor.credentialIssuer ? hostRules(descriptor.hosts ?? []).takes
518
+ : (host: string, path: string) => headerClaims.some((claims) => claims.takes(host, path)) && !otherClaims.some((claims) => claims.takes(host, path));
519
+ const granted = await consumerAuthorization(pack, join(scratch, `authorization-${mode}`), root, server, descriptor, outputs, claimsAuthorization, consumer);
520
+ nativeHeaders = granted.headers;
521
+ recipeAuthorized = true;
522
+ for (const name of Object.keys(nativeHeaders)) replayedHeaders.add(name);
523
+ nativeUrl = granted.url;
524
+ issued = undefined;
525
+ }
526
+ const endpoints = Object.values(outputs).flatMap((value) => {
527
+ try { const url = new URL(value); return url.protocol === 'https:' && !url.username && !url.password ? [url] : []; } catch { return []; }
528
+ });
529
+ const claimsNativeUrl = (u: Unit): boolean => {
530
+ return nativeUrl !== undefined && hostRules(u.hosts).takes(nativeUrl.hostname, nativeUrl.pathname);
531
+ };
532
+ if (nativeUrl && !units.some(claimsNativeUrl)) { out.push(`${units.map((u) => u.name).join(', ')}: credential door native url ${nativeUrl.origin} matches no selected unit's declared host rules${said}`); continue; }
533
+ const hostCandidates = (u: Unit): string[] => {
534
+ const claims = hostRules(u.hosts);
535
+ const remote = u.manifest.remoteHost;
536
+ const remoteHost = remote?.template.replace(/\{([^}]+)\}/g, (_match, name: string) => Object.values(remote.values?.[name] ?? {})[0] ?? 'conformance');
537
+ if (remoteHost && !claims.names(new URL(`https://${remoteHost}`).hostname)) throw new Error(`${u.name}: its remote host ${remoteHost} matches none of its declared host rules`);
538
+ return [...new Set([
539
+ ...(nativeUrl && claimsNativeUrl(u) ? [nativeUrl.host] : []),
540
+ ...endpoints.map((url) => url.host),
541
+ ...(remoteHost ? [remoteHost] : []),
542
+ ...u.hosts.flatMap((rule) => 'host' in rule && rule.exclude !== true ? [rule.host] : []),
543
+ ])];
544
+ };
545
+ const answers = new Map<Unit, Map<string, number>>(units.map((u) => [u, new Map<string, number>()]));
546
+ const removed = new Set<string>();
547
+ const callOperation = async (u: Unit, op: SweptOperation | undefined, request: Request): Promise<RemoteExecuteResponse | undefined> => {
548
+ const now = Date.parse(runtime.worldNow());
549
+ const signing = u.strategy?.in === 'signature' && u.strategy.algorithm === 'aws-sigv4' ? u.strategy : undefined;
550
+ if (signing) {
551
+ const keyPart = (suffix: string): string | undefined => {
552
+ const values = [...new Set(Object.entries(outputs).filter(([name]) => name === suffix || name.endsWith(`_${suffix}`)).map(([, value]) => value))];
553
+ return values.length === 1 && values[0] ? values[0] : undefined;
554
+ };
555
+ const accessKeyId = keyPart('ACCESS_KEY_ID');
556
+ const secretAccessKey = keyPart('SECRET_ACCESS_KEY');
557
+ if (!accessKeyId || !secretAccessKey) { out.push(`${u.name}: its SigV4 credential door supplies no unambiguous access-key-id and secret-access-key pair${said}`); return undefined; }
558
+ const url = new URL(request.url);
559
+ const headers = Object.fromEntries(request.headers);
560
+ const body = request.body === null ? undefined : await request.clone().text();
561
+ const scope = typeof signing.scope === 'function' ? signing.scope({ method: request.method, path: url.pathname + url.search, host: url.host, headers, ...(body === undefined ? {} : { body }) }) : signing.scope;
562
+ const signed = sigv4Headers({ accessKeyId, secretAccessKey, ...scope }, {}, request.method, request.url, headers, body, now);
563
+ request = new Request(request, { headers: { ...headers, ...signed } });
564
+ }
565
+ const where = `${u.name}: ${op?.id ?? 'GraphQL refresh'} (${request.method} ${new URL(request.url).pathname})`;
566
+ const graphqlBody = request.method === 'POST' && u.manifest.graphql?.paths.includes(new URL(request.url).pathname)
567
+ ? await request.clone().json().catch(() => undefined) : undefined;
568
+ const res = await send(request);
569
+ if (res instanceof Error) { out.push(`${where}: the connection failed${said} (${res.message})`); return undefined; }
570
+ if (op) answers.get(u)!.set(op.id, res.status);
571
+ if (mode === 'plain') { tally.calls++; if (res.status < 300) tally.ok++; else tally.refused++; }
572
+ if (res.bodyError) { out.push(`${where}: response body failed${said} (${res.bodyError.message})`); return undefined; }
573
+ const text = res.text;
574
+ const response = { status: res.status, headers: res.headers, body: text, bodyBytes: res.bodyBytes };
575
+ const removal = op ? u.removedAt?.(op.id, Math.floor(now / 1000)) : undefined;
576
+ if (removal) {
577
+ const expected = runtime.vendorError(u.manifest, removal);
578
+ if (res.status === expected.status && text === await expected.text()) removed.add(`${u.name}:${op!.id}`);
579
+ else out.push(`${where} does not match its declared native removal at ${new Date(now).toISOString()}${said}: expected ${removal.status} and its exact native body, received ${res.status}: ${text.slice(0, 160)}`);
580
+ }
581
+ const statuses = op ? u.responseStatuses.get(op.id) : undefined;
582
+ if (res.status === 500 && !statuses?.has('500') && !statuses?.has('5XX') && !statuses?.has('default')) out.push(`${where} answered 500${said}, which the spec does not declare: ${text.slice(0, 160)}`);
583
+ const type = res.headers['content-type'];
584
+ const judged = responseProblems(shape, vendorFields, { method: request.method, path: request.url, requestHeaders: Object.fromEntries(request.headers), graphqlBody,
585
+ status: res.status, mediaType: type, body: decodeResponse(text, type), text });
586
+ for (const key of judged.leaks) out.push(`${where} answers the twin's own field ${key}${said}`);
587
+ for (const detail of judged.shape) out.push(`${where}: ${detail}${said}`);
588
+ return response;
589
+ };
590
+ const refreshed = new Set<string>();
591
+ const nativeRefreshOwnsReads = recipeAuthorized && nativeHeaders !== undefined && units.some((unit) => unit.refreshReads.length > 0);
592
+ if (nativeRefreshOwnsReads) {
593
+ const vendor = (await manifestOf(pack)).vendor ?? basename(pack);
594
+ const refresh = runtime.getPack(vendor)?.stateSystem?.refresh;
595
+ if (!refresh) throw new Error(`${vendor}: its registered native refresh adapter is missing`);
596
+ try { await refresh(async (call) => {
597
+ const u = units.find((unit) => unit.lane === (call.lane ?? ''));
598
+ if (!u) throw new Error(`${vendor}: its native refresh names no selected unit`);
599
+ const url = hostCandidates(u).map((host) => new URL(call.path, `https://${host}`)).find((candidate) => hostRules(u.hosts).takes(candidate.hostname, candidate.pathname));
600
+ if (!url) throw new Error(`${u.name}: its native refresh request matches no declared host`);
601
+ const headers = { ...call.headers, ...(claimsNativeUrl(u) ? nativeHeaders : {}) };
602
+ const request = new Request(url, { method: call.method, headers, ...(call.body === undefined ? {} : { body: call.body as BodyInit }) });
603
+ const operation = shape?.operationOf(call.method, url.href, Object.fromEntries(request.headers));
604
+ const op = (operation?.lane ?? '') === u.lane ? u.ops.find((candidate) => candidate.id === operation?.op.id) : undefined;
605
+ const graphql = call.method.toUpperCase() === 'POST' && u.manifest.graphql?.paths.includes(url.pathname);
606
+ if (!op && !graphql) throw new Error(`${u.name}: its native refresh matches no served operation or declared GraphQL endpoint`);
607
+ if (op) refreshed.add(`${u.name}:${op.id}`);
608
+ const response = await callOperation(u, op, request);
609
+ if (!response) throw new Error(`${u.name}: its native refresh request failed`);
610
+ return response;
611
+ }, { root }); }
612
+ catch (error) {
613
+ const detail = error instanceof Error ? error.message : String(error);
614
+ const secrets = Object.values(nativeHeaders!).flatMap((value) => [value, value.split(/\s+/).slice(1).join(' ')]).filter(Boolean);
615
+ out.push(`${vendor}: its native refresh adapter failed${said}: ${secrets.reduce((message, secret) => message.replaceAll(secret, '[redacted]'), detail)}`);
616
+ }
403
617
  }
404
- const said = mode === 'scenario' ? ' with a scenario loaded' : '';
405
618
  for (const u of units) {
406
- // a unit whose manifest declares no `auth` checks its key in its own front: the key goes as most vendors read
407
- // one, a bearer token, and a refusal of it is no finding of the refresh below
619
+ // A front that checks its own key receives the door's token as a bearer.
408
620
  const auth = u.auth ?? { header: 'authorization', scheme: 'Bearer' };
409
- const credential: Record<string, string> = issued ? { [auth.header]: auth.scheme ? `${auth.scheme} ${issued}` : issued } : {};
410
- const answered = new Map<string, number>();
621
+ const native = nativeHeaders !== undefined && (!nativeUrl || claimsNativeUrl(u));
622
+ const credential: Record<string, string> = native ? nativeHeaders! : issued ? { [auth.header]: auth.scheme ? `${auth.scheme} ${issued}` : issued } : {};
623
+ const signing = u.strategy?.in === 'signature' && u.strategy.algorithm === 'aws-sigv4' ? u.strategy : undefined;
624
+ if (!signing && u.auth && !native && !issued) { out.push(`${u.name}: its credential door supplies no nonempty credential for ${auth.header}${said}`); continue; }
625
+ const claims = hostRules(u.hosts);
626
+ let hosts: string[];
627
+ try { hosts = hostCandidates(u); } catch (error) { out.push(`${(error as Error).message}${said}`); continue; }
411
628
  for (const op of u.ops) {
412
- const request = sweepRequest(op, u.basePath, u.host, credential);
413
- const where = `${u.name}: ${op.id} (${request.method} ${new URL(request.url).pathname})`;
414
- const res = await send(request);
415
- if (res === 'timeout') { out.push(`${where} answered nothing in 10 s${said}`); continue; }
416
- if (res instanceof Error) { out.push(`${where}: the connection failed${said} (${res.message})`); continue; }
417
- answered.set(op.id, res.status);
418
- if (mode === 'plain') { tally.calls++; if (res.status < 300) tally.ok++; else tally.refused++; }
419
- const text = await res.text();
420
- if (res.status === 500 && !op.responseMedia?.['500'] && !op.responseMedia?.['5XX']) { out.push(`${where} answered 500${said}, which the spec does not declare: ${text.slice(0, 160)}`); continue; }
421
- if (mode === 'scenario') continue;
422
- const type = res.headers.get('content-type') ?? '';
423
- let body: unknown;
424
- if (/json/.test(type)) { try { body = JSON.parse(text); } catch { body = undefined; } }
425
- for (const key of leaked(body, vendorFields, '', !op.answers || res.status >= 300)) out.push(`${where} answers the twin's own field ${key}`);
426
- if (res.status >= 200 && res.status < 300 && shape) {
427
- const hit = shape.operationOf(request.method, request.url, Object.fromEntries(request.headers));
428
- if (hit) for (const detail of shape.failures(hit.op, body, type, request.headers.get('accept') ?? undefined, res.status, { method: request.method, responseText: text })) out.push(`${where}: ${detail}`);
429
- }
430
- }
431
- if (mode === 'plain') for (const r of u.refreshLists) {
432
- const op = u.ops.find((o) => o.id === r.id);
433
- if (!op || op.path.includes('{') || (op.basePath ?? '').includes('{')) continue;
434
- const status = answered.get(r.id);
435
- if (status !== undefined && (status === 401 || status === 403) && (!u.auth || !issued)) continue;
436
- if (status !== undefined && (status < 200 || status >= 300)) out.push(`${u.name}: ${r.resource}'s refresh lists by ${r.id}, which answered a fresh account ${status}: a World rooted at this twin reads nothing back`);
629
+ if (refreshed.has(`${u.name}:${op.id}`)) continue;
630
+ const request = hosts.map((host) => sweepRequest(op, u.basePath, host, signing ? {} : credential)).find((candidate) => {
631
+ const url = new URL(candidate.url);
632
+ return claims.takes(url.hostname, url.pathname);
633
+ });
634
+ if (!request) { out.push(`${u.name}: ${op.id} has no concrete declared host or issued HTTPS endpoint matching its host rules${said}`); continue; }
635
+ await callOperation(u, op, request);
437
636
  }
438
637
  }
638
+ const readSomething = units.some((u) => u.refreshReads.some((id) => { const status = answers.get(u)?.get(id); return status !== undefined && status >= 200 && status < 300; }));
639
+ if (mode === 'plain' && !nativeRefreshOwnsReads) for (const u of units) for (const r of u.refreshLists) {
640
+ const op = u.ops.find((o) => o.id === r.id);
641
+ if (!op || op.path.includes('{') || (op.basePath ?? '').includes('{')) continue;
642
+ const status = answers.get(u)?.get(r.id);
643
+ if (removed.has(`${u.name}:${r.id}`)) { tally.removed++; continue; }
644
+ if (status === 403 && readSomething) { tally.unread++; continue; }
645
+ if (status !== undefined && (status < 200 || status >= 300)) out.push(`${u.name}: ${r.resource}'s refresh lists by ${r.id}, which answered a fresh account ${status}: a World rooted at this twin reads nothing back`);
646
+ }
439
647
  } finally { await server.stop(); }
440
648
  }
441
649
  // one defect repeated over a surface reads as one: the first 40 findings, and how many more
442
- return { failures: out.length > 40 ? [...out.slice(0, 40), `… ${out.length - 40} more`] : out, note: `${tally.calls} served operations called, twice each: ${tally.ok} answered successfully, ${tally.refused} refused, unscripted` };
650
+ return { failures: out.length > 40 ? [...out.slice(0, 40), `… ${out.length - 40} more`] : out, note: `${tally.calls} served operations called, twice each: ${tally.ok} answered successfully, ${tally.refused} refused, unscripted; ${tally.unread} refresh resources unread (403), ${tally.removed} match declared native removals${replayedHeaders.size ? `; replayed application headers (values redacted): ${[...replayedHeaders].sort().join(', ')}` : ''}` };
443
651
  }
444
652
 
445
653
  /** A line protocol's connection over TCP, in the walk's stream shape. A line drew its replies when bytes arrived and then
@@ -479,31 +687,22 @@ async function lifeServed(pack: string): Promise<string[]> {
479
687
  if (!existsSync(lifePath)) return ['journeys/customer-life.json is missing'];
480
688
  const { inMemoryWorld, usePacks, walk } = await import('./walk/behavior-journey.ts');
481
689
  usePacks(dirname(pack), { dependenciesFrom: pack });
482
- const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
483
690
  const served = async (root: string, options: { scenarioPath?: string }) => {
484
- const before = env.VOLTER_WORLD_BOOT_ID;
485
- env.VOLTER_WORLD_BOOT_ID = 'conformance';
486
- let server: Served;
487
- try { server = await serve(pack, { root, ...options }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
691
+ const server = await serve(pack, { root, ...options });
488
692
  const port = server.inspectPort ?? server.port;
489
693
  const http = servedHttpFetch(port);
490
694
  return {
491
695
  // the vendor's URL as the application called it, sent to the served pack: its host carried in the Host header
492
- fetch: Object.assign(async (request: Request): Promise<Response> => {
493
- await server.managedDatabaseUrl?.();
494
- const abort = new AbortController();
495
- try {
496
- const answer = await within(10_000, http(request, { signal: abort.signal }));
497
- return answer === 'timeout' ? new Response(`no answer in 10 s from the served pack (${request.method} ${new URL(request.url).pathname})`, { status: 599 }) : answer;
498
- } finally { abort.abort(); }
499
- }, server.managedDatabaseUrl ? { managedDatabaseUrl: server.managedDatabaseUrl } : {}),
696
+ fetch: Object.assign(http, {
697
+ managedDatabaseUrl: server.managedDatabaseUrl,
698
+ managedDatabaseClock: server.managedDatabaseClock,
699
+ managedDatabaseConnection: server.managedDatabaseConnection,
700
+ }),
500
701
  // a socket opened as an application opens it: a WebSocket to the served port, the vendor's host in its Host header
501
702
  socket: (url: string, headers: Record<string, string>) => new WebSocket(`ws://127.0.0.1:${port}${url}`, { headers } as unknown as string[]),
502
703
  // TCP to the native wire: a separate listener beside HTTP, or the primary protocol port.
503
704
  stream: lineConnection(server.wirePort ?? server.port),
504
- // bounded: Bun's server.stop(true) never settles once a WebSocket peer has closed under it (discord's life, Bun
505
- // 1.3.11: the walk ended and the stop spun at full CPU for 45 minutes), so the check waits 5 s and goes on
506
- stop: async () => { await within(5000, Promise.resolve(server.stop())); },
705
+ stop: () => server.stop(),
507
706
  };
508
707
  };
509
708
  const world = inMemoryWorld(`conform-${basename(pack)}`);
@@ -516,50 +715,36 @@ async function lifeServed(pack: string): Promise<string[]> {
516
715
 
517
716
  /** The pack driven by the vendor's own client (clients/<vendor>.ts): served as a World runs it, its credentials issued
518
717
  * by its credential door, the cases run in Node as an application runs the vendor's SDK (clients/run.ts), each the
519
- * vendor's documented behaviour. A vendor whose descriptor names npm clients and has no cases fails it, unless the
520
- * descriptor's clientCasesNone says why none is owed. */
521
- async function clientCases(pack: string, scratch: string): Promise<{ failures: string[]; note?: string }> {
718
+ * vendor's documented behaviour. Without a built-in module, the current installed workflow can supply that proof;
719
+ * otherwise a vendor naming npm clients needs cases or clientCasesNone saying why none is owed. */
720
+ async function clientCases(pack: string, scratch: string, consumer?: ConsumerResult): Promise<{ failures: string[]; note?: string }> {
522
721
  const vendor = (await manifestOf(pack)).vendor ?? basename(pack);
523
722
  const clients = join(dirname(fileURLToPath(import.meta.url)), 'clients');
524
723
  const extension = extname(fileURLToPath(import.meta.url));
525
724
  if (!existsSync(join(clients, `${vendor}${extension}`))) {
526
- // a vendor whose descriptor names npm clients (adoption.sdks) is held to them: no case is no proof the SDK works,
527
- // unless the descriptor says why none is owed (clientCasesNone: no official SDK, or none the demand's applications
528
- // use); one an application calls with no SDK of the vendor's (a raw HTTP catalog) has no client to drive
529
725
  const descriptor = ((await manifestOf(pack)) as { descriptor?: { adoption?: { sdks?: string[] }; clientCasesNone?: string } }).descriptor;
530
726
  const sdks = descriptor?.adoption?.sdks ?? [];
531
727
  if (descriptor?.clientCasesNone) return { failures: [], note: `${vendor} owes no client case: ${descriptor.clientCasesNone}` };
532
- return sdks.length
533
- ? { failures: [`${vendor} names npm clients (${sdks.join(', ')}) and has no client cases: add packages/twin-standard/src/clients/${vendor}.ts, the SDK driving the pack as an application does, or the descriptor's clientCasesNone saying why none is owed`] }
534
- : { failures: [], note: `${vendor} declares no SDK of its own` };
728
+ if (!sdks.length) return { failures: [], note: `${vendor} declares no SDK of its own` };
729
+ const proof = consumerClientProof(pack, vendor, sdks, consumer);
730
+ return { ...proof, failures: proof.failures.map((failure) => `${vendor} names npm clients (${sdks.join(', ')}) and has no built-in client cases: ${failure}`) };
535
731
  }
536
- const descriptor = ((await manifestOf(pack)) as { descriptor?: { hosts?: Array<{ host?: string; suffix?: string }>; hostsNone?: string; credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> } } }).descriptor;
732
+ const descriptor = ((await manifestOf(pack)) as { descriptor?: PackDescriptor }).descriptor;
537
733
  // the first host that names one: a descriptor may lead with a suffix (a region's hosts under one domain), which no
538
734
  // request addresses; the case's client reaches whatever host its issued credentials name
539
735
  // a raw protocol's pack (hostsNone: SMTP, whose relay is whatever host the operator names) is reached by its TCP
540
736
  // connection alone; its client names a stand-in host the connection never resolves
541
- const host = descriptor?.hosts?.find((h) => h.host)?.host ?? (descriptor?.hostsNone ? 'relay.world.test' : undefined);
737
+ const host = descriptor?.hosts?.flatMap((h) => 'host' in h && h.exclude !== true ? [h.host] : [])[0] ?? (descriptor?.hostsNone ? 'relay.world.test' : undefined);
542
738
  if (!host) return { failures: ['the descriptor names no host for its client to address'] };
543
739
  const scenarioPath = join(scratch, 'client-scenario.json');
544
740
  writeFileSync(scenarioPath, '{"handlers":[]}');
545
- const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
546
- const before = env.VOLTER_WORLD_BOOT_ID;
547
- env.VOLTER_WORLD_BOOT_ID = 'conformance';
548
- let server: Served;
549
- try { server = await serve(pack, { root: join(scratch, 'client-world'), scenarioPath }); } finally { if (before === undefined) delete env.VOLTER_WORLD_BOOT_ID; else env.VOLTER_WORLD_BOOT_ID = before; }
741
+ const server = await serve(pack, { root: join(scratch, 'client-world'), scenarioPath });
550
742
  try {
551
743
  // the World's credentials: what the pack's credential door issues, by the variable a World sets each in
552
744
  const issued: Record<string, string> = {};
553
745
  const door = descriptor?.credentialDoor;
554
746
  if (door) {
555
- // a door that answers nothing is the pack's failure, never conform's hang (a pack served with a scenario that answered
556
- // nothing once held this request open for good)
557
- const abort = new AbortController();
558
- const asked = await within(10_000, fetch(`http://127.0.0.1:${server.port}${door.path}`, { method: 'POST', headers: { host, 'content-type': 'application/json' }, body: JSON.stringify(door.body), signal: abort.signal }).then((r) => r.json().catch(() => ({}))));
559
- abort.abort();
560
- if (asked === 'timeout') return { failures: [`the credential door (POST ${door.path}) answered nothing in 10 s, served with a scenario loaded`] };
561
- const answer = asked as Record<string, unknown>;
562
- for (const [name, field] of Object.entries(door.fill)) if (answer[field] !== undefined) issued[name] = String(answer[field]);
747
+ Object.assign(issued, (await credentialFields(server, door, host)).outputs);
563
748
  }
564
749
  const job = join(scratch, 'client-job.json');
565
750
  // a release carries its facts (generated/pack-facts.json, `twin-standard facts`); a source checkout does not, so its
@@ -624,7 +809,7 @@ function records(pack: string): string[] {
624
809
 
625
810
  /** Every check over the pack at `dir`, in order. */
626
811
  /** `onCheck` hears each check's id as it starts, so a caller can show where a long run stands. */
627
- export async function conformance(dir: string, options: { onCheck?: (id: string) => void } = {}): Promise<ConformanceResult[]> {
812
+ export async function conformance(dir: string, options: { onCheck?: (id: string) => void; consumer?: ConsumerResult } = {}): Promise<ConformanceResult[]> {
628
813
  const pack = resolve(dir);
629
814
  if (!existsSync(join(pack, 'package.json'))) throw new Error(`${dir} is no pack (no package.json): conformance takes a pack's directory`);
630
815
  // the kernel the pack itself resolves: one registry, one serve seam, the pack's own
@@ -647,11 +832,11 @@ export async function conformance(dir: string, options: { onCheck?: (id: string)
647
832
  await (async (): Promise<ConformanceResult> => {
648
833
  options.onCheck?.('client');
649
834
  const asks = "driven by the vendor's own client (its official SDK), served as a World runs it, the vendor's documented behaviour holds";
650
- try { const r = await clientCases(pack, scratch); return { id: 'client', asks, failures: r.failures, ...(r.note ? { note: r.note } : {}) }; } catch (error) { return { id: 'client', asks, failures: [`the check could not run: ${(error as Error).message.split('\n')[0]}`] }; }
835
+ try { const r = await clientCases(pack, scratch, options.consumer); return { id: 'client', asks, failures: r.failures, ...(r.note ? { note: r.note } : {}) }; } catch (error) { return { id: 'client', asks, failures: [`the check could not run: ${(error as Error).message.split('\n')[0]}`] }; }
651
836
  })(),
652
837
  await run('life', 'the life walked over HTTP against the pack served as a World runs it, with its scenario: every check held', () => lifeServed(pack)),
653
838
  await run('standalone', 'served by its server.ts as a World runs it, the pack answers HTTP and the boot probe, and each declared socket upgrades', () => standalone(pack)),
654
- await run('surface', 'every served operation called over HTTP as an application calls it, plainly and with a scenario loaded: answered within 10 s, no undeclared 500, no field of the twin\'s own, a success in the spec\'s shape, and every refresh list a fresh account reads answering', () => surfaceSwept(pack, scratch)),
839
+ await run('surface', 'every served operation called over HTTP as an application calls it, plainly and with a scenario loaded: answered within 10 s, no undeclared 500, no field of the twin\'s own, a success in the spec\'s shape, and every refresh list answering, remaining unread under the native 403 contract, or matching its declared removal at the World clock', () => surfaceSwept(pack, scratch, runtime, options.consumer)),
655
840
  await run('records', 'each demand row cites the line it was read at, the spec\'s record names a vendored file that is there, the life names its author, the package has its README', () => records(pack)),
656
841
  await run('form', 'every unit passes the form section of the grade (the gate): the layout, the handler and kernel contracts, the manifest as data, the rules an author\'s code holds', () => formOf(pack)),
657
842
  ];