@volter/twin-standard 1.0.88 → 1.0.89

package/dist/src/assessment.js

@@ -36,7 +36,7 @@ export async function assessPack(packDir, options = {}) {
     const units = [packDir, ...lanes.map((name) => join(packDir, name))];
     if (packDir.split(/[\\/]/).at(-1) !== vendor)
         throw new Error('Place the artifact in a directory named for its vendor before assessment');
-    usePacks(join(packDir, '..'));
+    usePacks(join(packDir, '..'), { dependenciesFrom: packDir });
     const gates = await p3Gate(units);
     const life = expandFills(read(join(packDir, 'journeys/customer-life.json')));
     if (!Array.isArray(life.steps) || !life.steps.length)

package/dist/src/conformance.js

@@ -356,7 +356,7 @@ async function lifeServed(pack) {
     if (!existsSync(lifePath))
         return ['journeys/customer-life.json is missing'];
     const { inMemoryWorld, usePacks, walk } = await import("./walk/behavior-journey.js");
-    usePacks(dirname(pack));
+    usePacks(dirname(pack), { dependenciesFrom: pack });
     const env = globalThis.process.env;
     const served = async (root, options) => {
         const before = env.VOLTER_WORLD_BOOT_ID;

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

@@ -1,6 +1,8 @@
 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;
+export declare function usePacks(dir: string, options?: {
+    dependenciesFrom?: 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

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

@@ -22,6 +22,8 @@ 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;
+/** Installed companions resolve from the selected pack, including its workspace-local dependencies. */
+let dependenciesRoot;
 /** Where a socket step opens: an absolute `ws://` or `wss://` url on its own host, a path on the life's host otherwise. */
 function socketAt(open, host) {
     if (!/^wss?:\/\//.test(open))
@@ -34,8 +36,9 @@ let walkFacts = baselineFacts;
 let walkHosts = createHostTable(walkFacts).hosts;
 const directories = new Map();
 const installedFacts = new Set();
-export function usePacks(dir) {
+export function usePacks(dir, options = {}) {
     packsRoot = dir;
+    dependenciesRoot = options.dependenciesFrom ?? dir;
     const installed = {};
     for (const name of readdirSync(dir)) {
         const file = join(dir, name, 'generated/pack-facts.json');
@@ -53,9 +56,10 @@ export function usePacks(dir) {
 }
 const packsDir = () => { if (packsRoot === undefined)
     throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
+const dependenciesDir = () => dependenciesRoot ?? packsDir();
 function directoryFor(vendor) {
     if (!directories.has(vendor)) {
-        const directory = walkPackDirectory(packsDir(), vendor);
+        const directory = walkPackDirectory(packsDir(), vendor, dependenciesDir());
         directories.set(vendor, directory);
         if (directory) {
             const name = vendor.split('/')[0];
@@ -119,7 +123,7 @@ function defaultType(body) {
         return 'text/plain;charset=UTF-8';
     }
 }
-const vendorFetch = (vendor) => vendorFetchFrom(packsDir(), vendor);
+const vendorFetch = (vendor) => vendorFetchFrom(packsDir(), vendor, dependenciesDir());
 const shapes = new Map();
 const shapeOf = (vendor) => { if (!shapes.has(vendor))
     shapes.set(vendor, shapeChecker(directoryFor(vendor))); return shapes.get(vendor); };
@@ -218,7 +222,7 @@ export async function walk(journey, root, collect, opts) {
         return {};
     }
     const factory = await vendorFetch(journey.vendor);
-    const views = await vendorAnswerViews(packsDir(), journey.vendor);
+    const views = await vendorAnswerViews(packsDir(), journey.vendor, dependenciesDir());
     if (!factory) {
         collect.push({ step: '(setup)', beat: 'ADAPTER', detail: `no create<Name>TwinFetch adapter enrolled for ${journey.vendor}` });
         return {};
@@ -370,7 +374,7 @@ export async function walk(journey, root, collect, opts) {
                 }
                 const viaServed = served?.stream;
                 if (!viaServed)
-                    streams ??= await vendorStream(packsDir(), journey.vendor);
+                    streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
                 if (!viaServed && !streams) {
                     collect.push({ step: step.name, beat: 'ADAPTER', detail: `no create<Name>TwinStream adapter enrolled for ${journey.vendor}` });
                     return;
@@ -437,7 +441,7 @@ export async function walk(journey, root, collect, opts) {
                 if (served?.stream && Object.keys(step.connect).length)
                     throw new Error('a served RESP walk configures its server, not the client connection');
                 if (!served?.stream)
-                    streams ??= await vendorStream(packsDir(), journey.vendor);
+                    streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
                 const factory = served?.stream ?? (respStream ??= streams?.(root, step.connect));
                 if (!factory)
                     throw new Error('no byte-stream adapter');
@@ -511,7 +515,7 @@ export async function walk(journey, root, collect, opts) {
             let body;
             if (step.signIn) {
                 if (!served?.stream)
-                    streams ??= await vendorStream(packsDir(), journey.vendor);
+                    streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
                 const factory = served?.stream ?? streams?.(root, {});
                 if (!factory)
                     throw new Error(`no create<Name>TwinStream adapter enrolled for ${journey.vendor}`);

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

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

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

@@ -2,14 +2,14 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { installedVendorPacks, isDerivedPack, packVendor } from '@volter/world-core/runtime';
-export function walkPackDirectory(from, vendor) {
+export function walkPackDirectory(from, vendor, dependenciesFrom = from) {
     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);
+        : installedVendorPacks(dependenciesFrom, { 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.d.ts

@@ -7,14 +7,14 @@ export type VendorFetchFactory = (root: string, options?: {
     scenarioPath?: string;
     application?: ApplicationStandIn;
 }) => (request: Request) => Response | Promise<Response>;
-export declare function vendorFetch(twinDir: string, vendor: string): Promise<VendorFetchFactory | undefined>;
+export declare function vendorFetch(twinDir: string, vendor: string, dependenciesFrom?: string): Promise<VendorFetchFactory | undefined>;
 /** Named views of an answer: what a journey step's `view` asserts against. The kit's own: `jwt:<field>`, the payload of the
  *  JSON Web Token at that field of the answer, decoded as the application verifying it reads it (a session token's
  *  claims). A pack's own (`answerViews` in its index) beside them. */
 export type AnswerViews = Record<string, (body: unknown) => unknown>;
-export declare function vendorAnswerViews(twinDir: string, vendor: string): Promise<AnswerViews>;
+export declare function vendorAnswerViews(twinDir: string, vendor: string, dependenciesFrom?: string): Promise<AnswerViews>;
 /** A vendor's byte-stream wire (a line protocol), in process: the pack's `create<Name>TwinStream`, what a
  *  hosted World hands a WebSocket's bytes. The walk drives it for a journey's line steps. */
 export type VendorStreamFactory = (root: string, options?: Record<string, unknown>) => TwinStream;
-export declare function vendorStream(twinDir: string, vendor: string): Promise<VendorStreamFactory | undefined>;
+export declare function vendorStream(twinDir: string, vendor: string, dependenciesFrom?: string): Promise<VendorStreamFactory | undefined>;
 export {};

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

@@ -13,8 +13,8 @@ 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);
+export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
+    const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
     if (!directory)
         return undefined;
     let mod;
@@ -59,9 +59,9 @@ const jwtView = (field) => (body) => {
         return null;
     }
 };
-export async function vendorAnswerViews(twinDir, vendor) {
+export async function vendorAnswerViews(twinDir, vendor, dependenciesFrom = twinDir) {
     let own = {};
-    const directory = walkPackDirectory(twinDir, vendor);
+    const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
     try {
         if (directory)
             own = (await import(__rewriteRelativeImportExtension(join(directory, 'src', 'index.ts')))).answerViews ?? {};
@@ -69,8 +69,8 @@ export async function vendorAnswerViews(twinDir, vendor) {
     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);
+export async function vendorStream(twinDir, vendor, dependenciesFrom = twinDir) {
+    const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
     if (!directory)
         return undefined;
     let mod;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.88",
+  "version": "1.0.89",
   "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.96",
+    "@volter/world-core": "3.0.97",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/assessment.ts

@@ -27,7 +27,7 @@ export async function assessPack(packDir: string, options: AssessmentOptions = {
   const lanes = readdirSync(packDir).filter((name) => existsSync(join(packDir, name, 'src/manifest.ts')) && !existsSync(join(packDir, name, 'package.json')));
   const units = [packDir, ...lanes.map((name) => join(packDir, name))];
   if (packDir.split(/[\\/]/).at(-1) !== vendor) throw new Error('Place the artifact in a directory named for its vendor before assessment');
-  usePacks(join(packDir, '..'));
+  usePacks(join(packDir, '..'), { dependenciesFrom: packDir });
   const gates = await p3Gate(units);
   const life = expandFills(read(join(packDir, 'journeys/customer-life.json'))) as Journey;
   if (!Array.isArray(life.steps) || !life.steps.length) throw new Error('Assessment needs a nonempty customer journey');

package/src/conformance.ts

@@ -318,7 +318,7 @@ async function lifeServed(pack: string): Promise<string[]> {
   const lifePath = join(pack, 'journeys', 'customer-life.json');
   if (!existsSync(lifePath)) return ['journeys/customer-life.json is missing'];
   const { inMemoryWorld, usePacks, walk } = await import('./walk/behavior-journey.ts');
-  usePacks(dirname(pack));
+  usePacks(dirname(pack), { dependenciesFrom: pack });
   const env = (globalThis as { process: { env: Record<string, string | undefined> } }).process.env;
   const served = async (root: string, options: { scenarioPath?: string }) => {
     const before = env.VOLTER_WORLD_BOOT_ID;

package/src/walk/behavior-journey.ts

@@ -24,6 +24,8 @@ 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. */
 let packsRoot: string | undefined;
+/** Installed companions resolve from the selected pack, including its workspace-local dependencies. */
+let dependenciesRoot: string | undefined;
 /** Where a socket step opens: an absolute `ws://` or `wss://` url on its own host, a path on the life's host otherwise. */
 function socketAt(open: string, host: string): { host: string; path: string } {
   if (!/^wss?:\/\//.test(open)) return { host, path: open };
@@ -36,8 +38,9 @@ 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 {
+export function usePacks(dir: string, options: { dependenciesFrom?: string } = {}): void {
   packsRoot = dir;
+  dependenciesRoot = options.dependenciesFrom ?? dir;
   const installed: Record<string, HostFacts[string]> = {};
   for (const name of readdirSync(dir)) {
     const file = join(dir, name, 'generated/pack-facts.json');
@@ -51,9 +54,10 @@ export function usePacks(dir: string): void {
   directories.clear();
 }
 const packsDir = (): string => { if (packsRoot === undefined) throw new Error('usePacks(<packs dir>) first'); return packsRoot; };
+const dependenciesDir = (): string => dependenciesRoot ?? packsDir();
 function directoryFor(vendor: string): string {
   if (!directories.has(vendor)) {
-    const directory = walkPackDirectory(packsDir(), vendor);
+    const directory = walkPackDirectory(packsDir(), vendor, dependenciesDir());
     directories.set(vendor, directory);
     if (directory) {
       const name = vendor.split('/')[0]!;
@@ -107,7 +111,7 @@ function defaultType(body: unknown): string {
   if (typeof body !== 'string') return 'application/json';
   try { parseExactJson(body); return 'application/json'; } catch { return 'text/plain;charset=UTF-8'; }
 }
-const vendorFetch = (vendor: string) => vendorFetchFrom(packsDir(), vendor);
+const vendorFetch = (vendor: string) => vendorFetchFrom(packsDir(), vendor, dependenciesDir());
 const shapes = new Map<string, Promise<ShapeChecker | undefined>>();
 const shapeOf = (vendor: string): Promise<ShapeChecker | undefined> => { if (!shapes.has(vendor)) shapes.set(vendor, shapeChecker(directoryFor(vendor))); return shapes.get(vendor)!; };
 
@@ -210,7 +214,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
   // the life's host is a hostname (the vendor's, `api.x.ai`); a URL there would put a second scheme in every request
   if (journey.host !== undefined && !/^[A-Za-z0-9.-]+(:\d+)?$/.test(journey.host)) { collect.push({ step: '(setup)', beat: 'HOST', detail: `the life's host "${journey.host}" is no hostname: write the vendor's host alone (api.example.com), no scheme or path` }); return {}; }
   const factory = await vendorFetch(journey.vendor);
-  const views = await vendorAnswerViews(packsDir(), journey.vendor);
+  const views = await vendorAnswerViews(packsDir(), journey.vendor, dependenciesDir());
   if (!factory) { collect.push({ step: '(setup)', beat: 'ADAPTER', detail: `no create<Name>TwinFetch adapter enrolled for ${journey.vendor}` }); return {}; }
   // the life's companions (`companions`): the packs its vendor calls, each over this walk's root, on the same World and
   // clock; reached in process by the vendor's ctx.vendorFetch and by a step to a URL their host rules claim
@@ -323,7 +327,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
         // never a way back to the in-process stream (which would pass a listener wired apart from the World)
         if (served?.stream && Object.keys(step.connect).length) { collect.push({ step: step.name, beat: 'CONNECTION', detail: `a served walk opens "${step.on}" as the application does, over TCP to the listener; connect options (${Object.keys(step.connect).join(', ')}) configure only the in-process stream` }); return; }
         const viaServed = served?.stream;
-        if (!viaServed) streams ??= await vendorStream(packsDir(), journey.vendor);
+        if (!viaServed) streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
         if (!viaServed && !streams) { collect.push({ step: step.name, beat: 'ADAPTER', detail: `no create<Name>TwinStream adapter enrolled for ${journey.vendor}` }); return; }
         const opened: Connection = { conn: undefined as unknown as TwinStreamConnection, out: '', closed: false, shape: {} };
         opened.conn = (viaServed ?? streams!(root, step.connect))({ write: (bytes) => { opened.out += decoder.decode(bytes); }, end: () => { opened.closed = true; } }, '127.0.0.1');
@@ -367,7 +371,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     try {
       if (step.connect) {
         if (served?.stream && Object.keys(step.connect).length) throw new Error('a served RESP walk configures its server, not the client connection');
-        if (!served?.stream) streams ??= await vendorStream(packsDir(), journey.vendor);
+        if (!served?.stream) streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
         const factory = served?.stream ?? (respStream ??= streams?.(root, step.connect)); if (!factory) throw new Error('no byte-stream adapter');
         const c = { conn: undefined as unknown as TwinStreamConnection, out: '', closed: false };
         c.conn = factory({ write: (b) => { c.out += redis.binaryText(b); }, end: () => { c.closed = true; } }, '127.0.0.1');
@@ -405,7 +409,7 @@ export async function walk(journey: Journey, root: string, collect: Failure[], o
     try {
       let body: Record<string, unknown> | undefined;
       if (step.signIn) {
-        if (!served?.stream) streams ??= await vendorStream(packsDir(), journey.vendor);
+        if (!served?.stream) streams ??= await vendorStream(packsDir(), journey.vendor, dependenciesDir());
         const factory = served?.stream ?? streams?.(root, {}); if (!factory) throw new Error(`no create<Name>TwinStream adapter enrolled for ${journey.vendor}`);
         let out: number[] = [];
         const conn = factory({ write: (b) => { out.push(...b); }, end: () => {} }, '127.0.0.1');

package/src/walk/pack-directory.ts

@@ -3,13 +3,13 @@ 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 {
+export function walkPackDirectory(from: string, vendor: string, dependenciesFrom = from): 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!);
+    : installedVendorPacks(dependenciesFrom, { 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

@@ -13,8 +13,8 @@ type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
  *  life's application answers stand in for the application the vendor asks (`application`, this fetch's alone). */
 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);
+export async function vendorFetch(twinDir: string, vendor: string, dependenciesFrom = twinDir): Promise<VendorFetchFactory | undefined> {
+  const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
   if (!directory) return undefined;
   let mod: Record<string, unknown>;
   try { mod = (await import(join(directory, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
@@ -52,9 +52,9 @@ const jwtView = (field: string) => (body: unknown): unknown => {
   try { return JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8')); } catch { return null; }
 };
 
-export async function vendorAnswerViews(twinDir: string, vendor: string): Promise<AnswerViews> {
+export async function vendorAnswerViews(twinDir: string, vendor: string, dependenciesFrom = twinDir): Promise<AnswerViews> {
   let own: AnswerViews = {};
-  const directory = walkPackDirectory(twinDir, vendor);
+  const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
   try {
     if (directory) own = ((await import(join(directory, 'src', 'index.ts'))) as { answerViews?: AnswerViews }).answerViews ?? {};
   } catch { /* none of its own */ }
@@ -65,8 +65,8 @@ export async function vendorAnswerViews(twinDir: string, vendor: string): Promis
  *  hosted World hands a WebSocket's bytes. The walk drives it for a journey's line steps. */
 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);
+export async function vendorStream(twinDir: string, vendor: string, dependenciesFrom = twinDir): Promise<VendorStreamFactory | undefined> {
+  const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
   if (!directory) return undefined;
   let mod: Record<string, unknown>;
   try { mod = (await import(join(directory, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }