@volter/twin-standard 1.0.84 → 1.0.86

package/dist/src/walk/behavior-journey.js

@@ -18,6 +18,7 @@ import { createHostTable } from '@volter/world-core/host-routing';
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 import { isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from "./journey-kit.js";
 import { lanesOf, lineShape, shapeChecker } from "./shape.js";
+import { walkPackDirectory } from "./pack-directory.js";
 import { xmlMembers } from "./xml-view.js";
 /** The pack repository the walk finds a vendor's pack in, set by the caller before its first walk. */
 let packsRoot;
@@ -31,6 +32,8 @@ function socketAt(open, host) {
 const baselineFacts = packFactsDocument.packs;
 let walkFacts = baselineFacts;
 let walkHosts = createHostTable(walkFacts).hosts;
+const directories = new Map();
+const installedFacts = new Set();
 export function usePacks(dir) {
     packsRoot = dir;
     const installed = {};
@@ -40,12 +43,34 @@ export function usePacks(dir) {
             Object.assign(installed, JSON.parse(readFileSync(file, 'utf8')).packs);
     }
     walkFacts = { ...baselineFacts, ...installed };
+    installedFacts.clear();
+    for (const vendor of Object.keys(installed))
+        installedFacts.add(vendor);
     walkHosts = createHostTable(walkFacts, Object.keys(installed)).hosts;
     shapes.clear();
     fieldsByVendor.clear();
+    directories.clear();
 }
 const packsDir = () => { if (packsRoot === undefined)
     throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
+function directoryFor(vendor) {
+    if (!directories.has(vendor)) {
+        const directory = walkPackDirectory(packsDir(), vendor);
+        directories.set(vendor, directory);
+        if (directory) {
+            const name = vendor.split('/')[0];
+            const root = vendor.includes('/') ? join(directory, '..') : directory;
+            const facts = join(root, 'generated', 'pack-facts.json');
+            if (existsSync(facts)) {
+                const document = JSON.parse(readFileSync(facts, 'utf8'));
+                walkFacts = { ...walkFacts, ...document.packs };
+                installedFacts.add(name);
+                walkHosts = createHostTable(walkFacts, [...installedFacts]).hosts;
+            }
+        }
+    }
+    return directories.get(vendor) ?? join(packsDir(), vendor);
+}
 /** 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
@@ -97,10 +122,11 @@ function defaultType(body) {
 const vendorFetch = (vendor) => vendorFetchFrom(packsDir(), vendor);
 const shapes = new Map();
 const shapeOf = (vendor) => { if (!shapes.has(vendor))
-    shapes.set(vendor, shapeChecker(join(packsDir(), vendor))); return shapes.get(vendor); };
+    shapes.set(vendor, shapeChecker(directoryFor(vendor))); return shapes.get(vendor); };
 /** The routing keys a pack answers under: its descriptor's host rules (pack-facts), each rule's `key` or the vendor's own
  *  name, as vendor-hosts.cjs compiles them. */
 function routingKeys(vendor) {
+    directoryFor(vendor);
     const name = vendor.split('/')[0];
     const hosts = walkFacts[name]?.hosts ?? [];
     return [...new Set(hosts.map((rule) => rule.key ?? name))].filter((key) => walkHosts[key] !== undefined);
@@ -151,7 +177,8 @@ const fieldsByVendor = new Map();
 function specFields(vendor) {
     if (!fieldsByVendor.has(vendor)) {
         // the pack's surface and each of its lanes' (a walk reaches a lane through the pack's router)
-        const files = [join(packsDir(), vendor), ...lanesOf(join(packsDir(), vendor))].map((dir) => join(dir, 'src', 'generated', 'surface.gen.json')).filter((f) => existsSync(f));
+        const directory = directoryFor(vendor);
+        const files = [directory, ...lanesOf(directory)].map((dir) => join(dir, 'src', 'generated', 'surface.gen.json')).filter((f) => existsSync(f));
         const surfaces = files.map((f) => parseExactJson(readFileSync(f, 'utf8')));
         fieldsByVendor.set(vendor, new Set(surfaces.flatMap((surface) => (surface.resources ?? []).flatMap((r) => r.fields.map((f) => f.name)))));
     }
@@ -213,7 +240,7 @@ export async function walk(journey, root, collect, opts) {
     const companionOf = (url) => (claims(ownKeys, url) ? undefined : companions.find((c) => claims(c.keys, url)));
     // the life's scenario is the World's: written into the walk's World store, which the pack reads it from as a World's
     // handlers/<vendor>.json is read
-    const scenarioPath = journey.scenario ? join(packsDir(), journey.vendor, 'journeys', journey.scenario) : undefined;
+    const scenarioPath = journey.scenario ? join(directoryFor(journey.vendor), 'journeys', journey.scenario) : undefined;
     if (scenarioPath)
         getActiveWorldStore().write(scenarioPath, readFileSync(scenarioPath, 'utf8'));
     // the application the vendor asks (ctx.ask) is the life's stand-in, this walk's fetch's alone: its answers, in order,
@@ -311,7 +338,7 @@ export async function walk(journey, root, collect, opts) {
     // replies each line drew; its answer is checked as a request's is (status, SHAPE, captures, expectations).
     const connections = new Map();
     let streams;
-    const lines = lineShape(join(packsDir(), journey.vendor));
+    const lines = lineShape(directoryFor(journey.vendor));
     const encoder = new TextEncoder();
     const decoder = new TextDecoder();
     const speak = async (step) => {
@@ -953,7 +980,7 @@ export async function walk(journey, root, collect, opts) {
                 }
             }
             const serving = companionOf(path)?.vendor ?? journey.vendor;
-            const graphqlBody = existsSync(join(packsDir(), serving, 'src', 'generated', 'graphql-sdl.gen.json'));
+            const graphqlBody = existsSync(join(directoryFor(serving), 'src', 'generated', 'graphql-sdl.gen.json'));
             let body;
             let headers;
             // a form's bytes, built before anything signs the request, so a signature covers what is sent

package/dist/src/walk/pack-directory.d.ts

@@ -0,0 +1 @@
+export declare function walkPackDirectory(from: string, vendor: string): string | undefined;

package/dist/src/walk/pack-directory.js

@@ -0,0 +1,15 @@
+// Source siblings and installed companions use the kernel's existing package identity and selection rules.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { installedVendorPacks, isDerivedPack, packVendor } from '@volter/world-core/runtime';
+export function walkPackDirectory(from, vendor) {
+    if (!/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?$/.test(vendor))
+        return undefined;
+    const [name, lane] = vendor.split('/');
+    const sibling = join(from, name);
+    const root = isDerivedPack(sibling) && packVendor(sibling) === name
+        ? sibling
+        : installedVendorPacks(from, { vendors: [name] }).get(name);
+    const unit = root && (lane ? join(root, lane) : root);
+    return unit && existsSync(join(unit, 'src', 'index.ts')) ? unit : undefined;
+}

package/dist/src/walk/vendor-fetch.js

@@ -12,10 +12,14 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { join } from 'node:path';
 import { startPgliteHost } from "./walk-database.js";
 import { worldNow } from '@volter/world-core/runtime';
+import { walkPackDirectory } from "./pack-directory.js";
 export async function vendorFetch(twinDir, vendor) {
+    const directory = walkPackDirectory(twinDir, vendor);
+    if (!directory)
+        return undefined;
     let mod;
     try {
-        mod = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts'))));
+        mod = (await import(__rewriteRelativeImportExtension(join(directory, 'src', 'index.ts'))));
     }
     catch {
         return undefined;
@@ -57,16 +61,21 @@ const jwtView = (field) => (body) => {
 };
 export async function vendorAnswerViews(twinDir, vendor) {
     let own = {};
+    const directory = walkPackDirectory(twinDir, vendor);
     try {
-        own = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts')))).answerViews ?? {};
+        if (directory)
+            own = (await import(__rewriteRelativeImportExtension(join(directory, 'src', 'index.ts')))).answerViews ?? {};
     }
     catch { /* none of its own */ }
     return new Proxy(own, { get: (views, name) => (typeof name === 'string' && name.startsWith('jwt:') ? jwtView(name.slice(4)) : views[name]) });
 }
 export async function vendorStream(twinDir, vendor) {
+    const directory = walkPackDirectory(twinDir, vendor);
+    if (!directory)
+        return undefined;
     let mod;
     try {
-        mod = (await import(__rewriteRelativeImportExtension(join(twinDir, vendor, 'src', 'index.ts'))));
+        mod = (await import(__rewriteRelativeImportExtension(join(directory, 'src', 'index.ts'))));
     }
     catch {
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.84",
+  "version": "1.0.86",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.92",
+    "@volter/world-core": "3.0.94",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/walk/behavior-journey.ts

@@ -19,6 +19,7 @@ import { createHostTable, type HostFacts } from '@volter/world-core/host-routing
 import packFactsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 import { type Captured, type GitStep, type Journey, type JourneyStep, type LineStep, type SocketStep, type SqlStep, type RespStep, type MysqlStep, isMysql, isResp, at, captureAt, echoFailures, expandFills, expectFailures, fill, fillJson, formBody, isGit, isLine, isSql, isSocket, isWait, jwtAuthorization, oauth1Authorization, presignedPath, sigv4Headers, waitMs } from './journey-kit.ts';
 import { lanesOf, lineShape, shapeChecker, type LineConnection, type ShapeChecker } from './shape.ts';
+import { walkPackDirectory } from './pack-directory.ts';
 import { xmlMembers } from './xml-view.ts';
 
 /** The pack repository the walk finds a vendor's pack in, set by the caller before its first walk. */
@@ -33,6 +34,8 @@ function socketAt(open: string, host: string): { host: string; path: string } {
 const baselineFacts = packFactsDocument.packs as unknown as HostFacts;
 let walkFacts: HostFacts = baselineFacts;
 let walkHosts = createHostTable(walkFacts).hosts;
+const directories = new Map<string, string | undefined>();
+const installedFacts = new Set<string>();
 export function usePacks(dir: string): void {
   packsRoot = dir;
   const installed: Record<string, HostFacts[string]> = {};
@@ -41,10 +44,31 @@ export function usePacks(dir: string): void {
     if (existsSync(file)) Object.assign(installed, JSON.parse(readFileSync(file, 'utf8')).packs);
   }
   walkFacts = { ...baselineFacts, ...installed };
+  installedFacts.clear();
+  for (const vendor of Object.keys(installed)) installedFacts.add(vendor);
   walkHosts = createHostTable(walkFacts, Object.keys(installed)).hosts;
   shapes.clear(); fieldsByVendor.clear();
+  directories.clear();
 }
 const packsDir = (): string => { if (packsRoot === undefined) throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
+function directoryFor(vendor: string): string {
+  if (!directories.has(vendor)) {
+    const directory = walkPackDirectory(packsDir(), vendor);
+    directories.set(vendor, directory);
+    if (directory) {
+      const name = vendor.split('/')[0]!;
+      const root = vendor.includes('/') ? join(directory, '..') : directory;
+      const facts = join(root, 'generated', 'pack-facts.json');
+      if (existsSync(facts)) {
+        const document = JSON.parse(readFileSync(facts, 'utf8')) as { packs: HostFacts };
+        walkFacts = { ...walkFacts, ...document.packs };
+        installedFacts.add(name);
+        walkHosts = createHostTable(walkFacts, [...installedFacts]).hosts;
+      }
+    }
+  }
+  return directories.get(vendor) ?? join(packsDir(), vendor);
+}
 
 /** 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
@@ -85,11 +109,12 @@ function defaultType(body: unknown): string {
 }
 const vendorFetch = (vendor: string) => vendorFetchFrom(packsDir(), vendor);
 const shapes = new Map<string, Promise<ShapeChecker | undefined>>();
-const shapeOf = (vendor: string): Promise<ShapeChecker | undefined> => { if (!shapes.has(vendor)) shapes.set(vendor, shapeChecker(join(packsDir(), vendor))); return shapes.get(vendor)!; };
+const shapeOf = (vendor: string): Promise<ShapeChecker | undefined> => { if (!shapes.has(vendor)) shapes.set(vendor, shapeChecker(directoryFor(vendor))); return shapes.get(vendor)!; };
 
 /** The routing keys a pack answers under: its descriptor's host rules (pack-facts), each rule's `key` or the vendor's own
  *  name, as vendor-hosts.cjs compiles them. */
 function routingKeys(vendor: string): string[] {
+  directoryFor(vendor);
   const name = vendor.split('/')[0]!;
   const hosts = walkFacts[name]?.hosts ?? [];
   return [...new Set(hosts.map((rule) => rule.key ?? name))].filter((key) => walkHosts[key] !== undefined);
@@ -132,7 +157,8 @@ const fieldsByVendor = new Map<string, Set<string>>();
 function specFields(vendor: string): Set<string> {
   if (!fieldsByVendor.has(vendor)) {
     // the pack's surface and each of its lanes' (a walk reaches a lane through the pack's router)
-    const files = [join(packsDir(), vendor), ...lanesOf(join(packsDir(), vendor))].map((dir) => join(dir, 'src', 'generated', 'surface.gen.json')).filter((f) => existsSync(f));
+    const directory = directoryFor(vendor);
+    const files = [directory, ...lanesOf(directory)].map((dir) => join(dir, 'src', 'generated', 'surface.gen.json')).filter((f) => existsSync(f));
     const surfaces = files.map((f) => parseExactJson(readFileSync(f, 'utf8')) as { resources?: Array<{ fields: Array<{ name: string }> }> });
     fieldsByVendor.set(vendor, new Set(surfaces.flatMap((surface) => (surface.resources ?? []).flatMap((r) => r.fields.map((f) => f.name)))));
   }
@@ -200,7 +226,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
   const companionOf = (url: string) => (claims(ownKeys, url) ? undefined : companions.find((c) => claims(c.keys, url)));
   // the life's scenario is the World's: written into the walk's World store, which the pack reads it from as a World's
   // handlers/<vendor>.json is read
-  const scenarioPath = journey.scenario ? join(packsDir(), journey.vendor, 'journeys', journey.scenario) : undefined;
+  const scenarioPath = journey.scenario ? join(directoryFor(journey.vendor), 'journeys', journey.scenario) : undefined;
   if (scenarioPath) getActiveWorldStore().write(scenarioPath, readFileSync(scenarioPath, 'utf8'));
   // the application the vendor asks (ctx.ask) is the life's stand-in, this walk's fetch's alone: its answers, in order,
   // by method and URL prefix, each request header it declares checked as sent; a question none takes is unreachable, as
@@ -276,7 +302,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
   // replies each line drew; its answer is checked as a request's is (status, SHAPE, captures, expectations).
   const connections = new Map<string, Connection>();
   let streams: VendorStreamFactory | undefined;
-  const lines = lineShape(join(packsDir(), journey.vendor));
+  const lines = lineShape(directoryFor(journey.vendor));
   const encoder = new TextEncoder();
   const decoder = new TextDecoder();
   const speak = async (step: LineStep): Promise<void> => {
@@ -662,7 +688,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     // a presigned URL is signed again with the key that presigned it, as its client's SDK signed it
     if (step.presign) { try { path = presignedPath(step.presign, captured, step.method, path, host, fillJson({ ...(step.bodyBase64 === undefined ? { 'content-type': defaultType(step.body) } : {}), ...(journey.headers ?? {}), ...(step.headers ?? {}) }, captured) as Record<string, string>); } catch (e) { collect.push({ step: step.name, beat: 'CAPTURE', detail: (e as Error).message }); continue; } }
     const serving = companionOf(path)?.vendor ?? journey.vendor;
-    const graphqlBody = existsSync(join(packsDir(), serving, 'src', 'generated', 'graphql-sdl.gen.json'));
+    const graphqlBody = existsSync(join(directoryFor(serving), 'src', 'generated', 'graphql-sdl.gen.json'));
     let body: unknown;
     let headers: Record<string, string> | undefined;
     // a form's bytes, built before anything signs the request, so a signature covers what is sent

package/src/walk/pack-directory.ts

@@ -0,0 +1,15 @@
+// Source siblings and installed companions use the kernel's existing package identity and selection rules.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { installedVendorPacks, isDerivedPack, packVendor } from '@volter/world-core/runtime';
+
+export function walkPackDirectory(from: string, vendor: string): string | undefined {
+  if (!/^[a-z][a-z0-9-]*(?:\/[a-z][a-z0-9-]*)?$/.test(vendor)) return undefined;
+  const [name, lane] = vendor.split('/');
+  const sibling = join(from, name!);
+  const root = isDerivedPack(sibling) && packVendor(sibling) === name
+    ? sibling
+    : installedVendorPacks(from, { vendors: [name!] }).get(name!);
+  const unit = root && (lane ? join(root, lane) : root);
+  return unit && existsSync(join(unit, 'src', 'index.ts')) ? unit : undefined;
+}

package/src/walk/vendor-fetch.ts

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { type PgliteHost, startPgliteHost } from './walk-database.ts';
 import { type TwinStream, worldNow } from '@volter/world-core/runtime';
 import type { PackFetchOptions } from '@volter/world-core';
+import { walkPackDirectory } from './pack-directory.ts';
 
 type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
 
@@ -13,8 +14,10 @@ type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
 export type VendorFetchFactory = (root: string, options?: { scenarioPath?: string; application?: ApplicationStandIn }) => (request: Request) => Response | Promise<Response>;
 
 export async function vendorFetch(twinDir: string, vendor: string): Promise<VendorFetchFactory | undefined> {
+  const directory = walkPackDirectory(twinDir, vendor);
+  if (!directory) return undefined;
   let mod: Record<string, unknown>;
-  try { mod = (await import(join(twinDir, vendor, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
+  try { mod = (await import(join(directory, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
   // a pack exports create<Name>Fetch (its generated fetch.ts)
   const name = Object.keys(mod).find((k) => /^create\w+?Fetch$/.test(k) && !/TwinFetch$/.test(k) && typeof mod[k] === 'function');
   if (!name) return undefined;
@@ -51,8 +54,9 @@ const jwtView = (field: string) => (body: unknown): unknown => {
 
 export async function vendorAnswerViews(twinDir: string, vendor: string): Promise<AnswerViews> {
   let own: AnswerViews = {};
+  const directory = walkPackDirectory(twinDir, vendor);
   try {
-    own = ((await import(join(twinDir, vendor, 'src', 'index.ts'))) as { answerViews?: AnswerViews }).answerViews ?? {};
+    if (directory) own = ((await import(join(directory, 'src', 'index.ts'))) as { answerViews?: AnswerViews }).answerViews ?? {};
   } catch { /* none of its own */ }
   return new Proxy(own, { get: (views, name) => (typeof name === 'string' && name.startsWith('jwt:') ? jwtView(name.slice(4)) : views[name as string]) });
 }
@@ -62,8 +66,10 @@ export async function vendorAnswerViews(twinDir: string, vendor: string): Promis
 export type VendorStreamFactory = (root: string, options?: Record<string, unknown>) => TwinStream;
 
 export async function vendorStream(twinDir: string, vendor: string): Promise<VendorStreamFactory | undefined> {
+  const directory = walkPackDirectory(twinDir, vendor);
+  if (!directory) return undefined;
   let mod: Record<string, unknown>;
-  try { mod = (await import(join(twinDir, vendor, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
+  try { mod = (await import(join(directory, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
   const name = Object.keys(mod).find((k) => /^create\w+TwinStream$/.test(k) && typeof mod[k] === 'function');
   if (!name) return undefined;
   const factory = mod[name] as (options: Record<string, unknown>) => TwinStream;