@volter/world-core 3.0.39 → 3.0.41

package/dist/network-policy.cjs

@@ -127,8 +127,10 @@ function allowsWorldNetworkEgress(policy, value, method = 'GET') {
 
 function worldNetworkUsesPassthrough(policy, value) {
   const to = destination(value, true);
-  return !!to && policy.phase === 'build' && policy.passthrough?.includes(to.url.origin) === true
-    && policy.egress.includes(to.url.origin);
+  if (!to || policy.phase !== 'build') return false;
+  // public build artifacts tunnel unopened: native clients (Turbopack's next/font on macOS) trust only the OS store
+  if (policy.publicReads === true && PUBLIC_BUILD_READS.includes(to.url.origin) && !granted(policy.writes ?? [], to)) return true;
+  return policy.passthrough?.includes(to.url.origin) === true && policy.egress.includes(to.url.origin);
 }
 
 /** This authority must be mediated per request; CONNECT is only a path to the inspector. */

package/dist/src/derived.d.ts

@@ -175,5 +175,12 @@ export type BoardFrame = {
     /** set by the kernel, never the pack: whether a built screen of the vendor's (any of its lanes') draws the url */
     drawn?: boolean;
 };
+/** Host-side measurement of actual dispatch, including declared gaps. It changes no request or answer. */
+export type DerivedDispatch = {
+    surface: DerivedSurface;
+    operation: DerivedOperation;
+    owner: DerivedOwner;
+};
+export declare function observeDerivedDispatch(observer: (dispatch: DerivedDispatch) => void): () => void;
 export declare function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch;
 export {};

package/dist/src/derived.js

@@ -144,6 +144,11 @@ export function pathParams(routes, pathname) {
 }
 /** The header the kernel carries a path prefix's named groups in, from routing to the call (never a client's). */
 export const PREFIX_PARAMS_HEADER = 'x-volter-path-prefix-params';
+let dispatchObservers;
+export function observeDerivedDispatch(observer) {
+    (dispatchObservers ??= new Set()).add(observer);
+    return () => { dispatchObservers?.delete(observer); };
+}
 export function createDerivedFetch(options) {
     const handlers = options.handlers ?? {};
     const known = new Set(options.surface.operations.map((o) => o.id));
@@ -161,6 +166,8 @@ export function createDerivedFetch(options) {
             : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
         if (!matched)
             return fallback(request, undefined, 'no operation at this path');
+        for (const observer of dispatchObservers ?? [])
+            observer({ surface: options.surface, operation: matched.operation, owner: handlers[matched.operation.id] ? 'handler' : options.core?.owns(matched.operation) ? 'core' : 'gap' });
         // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
         if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart'))
             tagBody(request, await request.clone().text());

package/dist/src/pack-paths.d.ts

@@ -1,3 +1,8 @@
+/** The vendor is published data, independent of its publisher's npm name. No package code is imported. */
+export declare function packVendor(dir: string): string | undefined;
+/** Nearest installed package wins only over another installation of the SAME package. A World's explicit
+ * package choice wins over a catalog recommendation; different publishers' versions never compete. */
+export declare function installedVendorPacks(from: string): Map<string, string>;
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export declare function installedPackageDir(from: string, name: string): string | undefined;
 /** A pack repository itself, or the P3 repository beside a platform checkout. Applications do not acquire a

package/dist/src/pack-paths.js

@@ -10,6 +10,88 @@ function packageName(dir) {
         return undefined;
     }
 }
+/** The vendor is published data, independent of its publisher's npm name. No package code is imported. */
+export function packVendor(dir) {
+    const facts = join(dir, 'generated', 'pack-facts.json');
+    if (existsSync(facts)) {
+        const document = JSON.parse(readFileSync(facts, 'utf8'));
+        const vendors = Object.keys(document.packs ?? {});
+        if (vendors.length !== 1 || !/^[a-z][a-z0-9-]*$/.test(vendors[0]) || document.packs[vendors[0]].protocol?.declared !== '3')
+            throw new Error(`Invalid pack identity in ${facts}`);
+        return vendors[0];
+    }
+    // Source checkouts predate release facts; their conventional name remains sufficient for development.
+    const match = /^@[^/]+\/twin-([a-z][a-z0-9-]*)$/.exec(packageName(dir) ?? '');
+    return match?.[1] === 'standard' || match?.[1] === 'catalog' ? undefined : match?.[1];
+}
+/** Nearest installed package wins only over another installation of the SAME package. A World's explicit
+ * package choice wins over a catalog recommendation; different publishers' versions never compete. */
+export function installedVendorPacks(from) {
+    const packages = new Map();
+    const seen = new Set();
+    const pins = new Map();
+    let at = resolve(from);
+    for (;;) {
+        const config = join(at, '.volter', 'world.json');
+        if (existsSync(config)) {
+            const document = JSON.parse(readFileSync(config, 'utf8'));
+            for (const service of document.services ?? []) {
+                const name = service.source?.package ?? service.package;
+                if (name && !pins.has(service.id))
+                    pins.set(service.id, name);
+            }
+        }
+        const modules = join(at, 'node_modules');
+        if (existsSync(modules)) {
+            const directories = readdirSync(modules, { withFileTypes: true }).filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith('.')).flatMap((e) => e.name.startsWith('@') ? readdirSync(join(modules, e.name)).map((n) => join(modules, e.name, n)) : [join(modules, e.name)]);
+            for (const dir of directories) {
+                const name = packageName(dir);
+                if (!name || seen.has(name))
+                    continue;
+                seen.add(name);
+                if (!existsSync(join(dir, 'generated', 'pack-facts.json')) && !/^@[^/]+\/twin-/.test(name))
+                    continue;
+                if (!isDerivedPack(dir))
+                    continue;
+                const vendor = packVendor(dir);
+                if (vendor)
+                    packages.set(name, { dir, vendor });
+            }
+        }
+        const parent = dirname(at);
+        if (parent === at)
+            break;
+        at = parent;
+    }
+    const index = installedPackageDir(from, '@volter/twin-catalog');
+    const file = index && join(index, 'recommendations.json');
+    const recommendations = file && existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    const revokedFile = index && join(index, 'revocations.json');
+    const revocations = revokedFile && existsSync(revokedFile) ? JSON.parse(readFileSync(revokedFile, 'utf8')) : [];
+    for (const [id, name] of [...pins]) {
+        const vendor = packages.get(name)?.vendor;
+        if (vendor && vendor !== id) {
+            if (pins.has(vendor) && pins.get(vendor) !== name)
+                throw new Error(`${vendor}: a World must select one package implementation`);
+            pins.set(vendor, name);
+        }
+    }
+    const result = new Map();
+    for (const vendor of new Set([...packages.values()].map((p) => p.vendor))) {
+        const candidates = [...packages.entries()].filter(([, p]) => p.vendor === vendor);
+        const selected = pins.get(vendor) ?? recommendations[vendor];
+        const choice = selected ? candidates.find(([name]) => name === selected) : candidates.length === 1 ? candidates[0] : undefined;
+        if (!choice)
+            throw new Error(`${vendor}: ${selected ? `selected package ${selected} is not installed` : `multiple implementations installed (${candidates.map(([name]) => name).join(', ')})`}; name the chosen source.package in .volter/world.json`);
+        if (!pins.has(vendor)) {
+            const version = JSON.parse(readFileSync(join(choice[1].dir, 'package.json'), 'utf8')).version;
+            if (revocations.some((r) => r.package === choice[0] && r.version === version))
+                throw new Error(`${vendor}: installed ${choice[0]}@${version} is revoked; install an approved release or retain an existing explicit World pin`);
+        }
+        result.set(vendor, choice[1].dir);
+    }
+    return result;
+}
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export function installedPackageDir(from, name) {
     let dir = resolve(from);
@@ -45,14 +127,15 @@ export function packRepository(from) {
 export function vendorPackageDir(from, vendor) {
     if (!/^[a-z][a-z0-9-]*$/.test(vendor))
         return undefined;
-    const candidate = installedPackageDir(from, `@volter/twin-${vendor}`);
-    const installed = candidate && isDerivedPack(candidate) ? candidate : undefined;
+    const installed = installedVendorPacks(from).get(vendor);
     const repo = packRepository(from);
     const checkout = repo === undefined ? undefined : join(repo, vendor);
     if (!checkout || packageName(checkout) !== `@volter/twin-${vendor}` || !isDerivedPack(checkout))
         return installed;
     if (!installed)
         return checkout;
+    if (packageName(installed) !== packageName(checkout))
+        return installed;
     const major = (dir) => {
         try {
             return Number(/^(\d+)/.exec(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version ?? '')?.[1] ?? 0);
@@ -77,7 +160,7 @@ export function vendorOfPackModule(modulePath) {
     for (;;) {
         const name = packageName(dir);
         if (name !== undefined)
-            return name.startsWith('@volter/twin-') ? name.slice('@volter/twin-'.length) : undefined;
+            return packVendor(dir);
         const up = dirname(dir);
         if (up === dir)
             return undefined;

package/dist/src/runtime.d.ts

@@ -1,4 +1,4 @@
-export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './packRegistry.js';
+export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, PACK_ARCHETYPES, protocolStanding } from './packRegistry.js';
 export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from './scenario.js';
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
@@ -6,10 +6,10 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
 export { ORIGINAL_PATH_HEADER } from './sigv4.js';
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
-export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
+export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from './derived.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
 export type { Traceparent } from './trace-context.js';
-export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
+export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.js';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';
@@ -49,7 +49,7 @@ export type { ActionProjection, ProjectedDelivery, ProjectedResource, ProjectedR
 export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from './changeset.js';
 export type { ApplyReceipt, RebaseActionResult, RebaseReport, RebaseTarget, Changeset, ChangesetAction, ChangesetApplication, CompensationEntry, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, ChangesetVerifierResult, LedgerDelta, LedgerPosition, LedgerRef, ReplayActionResult, ReplayReport, ReplayTarget, VendorSummary, WorldMarker, } from './changeset.js';
 export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets, type PackAssetStore } from './pack-assets.js';
-export { installedPackageDir, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.js';
+export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.js';
 export * as git from './git/index.js';
 export * as s3 from './s3/wire.js';
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from './placeholder-remote.js';

package/dist/src/runtime.js

@@ -5,7 +5,7 @@
 // contract: the kernel's root"). Removed v1 entry points fail explicitly. Conformance and validation tooling lives in
 // @volter/world-tooling, a dev dependency.
 // Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
-export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./packRegistry.js";
+export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, PACK_ARCHETYPES, protocolStanding } from "./packRegistry.js";
 // The DELIVER verb (`emit`) — vendor-agnostic engine + CLI glue; packs declare a TwinEmitter
 // (their event catalog, endpoints-from-state, and signed synthesis) on `TwinPack.emitter`.
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
@@ -14,7 +14,7 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
-export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
+export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from "./derived.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from "./events.js";
@@ -68,7 +68,7 @@ export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction
 // world discovery and thin verbs on top.
 export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from "./changeset.js";
 export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets } from "./pack-assets.js";
-export { installedPackageDir, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from "./pack-paths.js";
+export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from "./pack-paths.js";
 // The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
 export * as git from "./git/index.js";
 // S3's wire (contract "S3's wire is a kernel library too"): its XML, CORS, lifecycle, delete batches, ETags, body bytes.

package/network-policy.cjs

@@ -127,8 +127,10 @@ function allowsWorldNetworkEgress(policy, value, method = 'GET') {
 
 function worldNetworkUsesPassthrough(policy, value) {
   const to = destination(value, true);
-  return !!to && policy.phase === 'build' && policy.passthrough?.includes(to.url.origin) === true
-    && policy.egress.includes(to.url.origin);
+  if (!to || policy.phase !== 'build') return false;
+  // public build artifacts tunnel unopened: native clients (Turbopack's next/font on macOS) trust only the OS store
+  if (policy.publicReads === true && PUBLIC_BUILD_READS.includes(to.url.origin) && !granted(policy.writes ?? [], to)) return true;
+  return policy.passthrough?.includes(to.url.origin) === true && policy.egress.includes(to.url.origin);
 }
 
 /** This authority must be mediated per request; CONNECT is only a path to the inspector. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.39",
+  "version": "3.0.41",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/derived.ts

@@ -255,6 +255,14 @@ export type BoardFrame = {
   drawn?: boolean;
 };
 
+/** Host-side measurement of actual dispatch, including declared gaps. It changes no request or answer. */
+export type DerivedDispatch = { surface: DerivedSurface; operation: DerivedOperation; owner: DerivedOwner };
+let dispatchObservers: Set<(dispatch: DerivedDispatch) => void> | undefined;
+export function observeDerivedDispatch(observer: (dispatch: DerivedDispatch) => void): () => void {
+  (dispatchObservers ??= new Set()).add(observer);
+  return () => { dispatchObservers?.delete(observer); };
+}
+
 export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   const handlers = options.handlers ?? {};
   const known = new Set(options.surface.operations.map((o) => o.id));
@@ -271,6 +279,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
       ? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, request.headers)).find(Boolean)
       : matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
     if (!matched) return fallback(request, undefined, 'no operation at this path');
+    for (const observer of dispatchObservers ?? []) observer({ surface: options.surface, operation: matched.operation, owner: handlers[matched.operation.id] ? 'handler' : options.core?.owns(matched.operation) ? 'core' : 'gap' });
     // the body read once, as text, for everything the dispatch does with it (bodyTextOf)
     if (request.method !== 'GET' && request.method !== 'HEAD' && request.body && !(request.headers.get('content-type') ?? '').includes('multipart')) tagBody(request, await request.clone().text());
     // the path prefix's named groups (pack-fetch.ts, `pathPrefix`) are the call's parameters too

package/src/pack-paths.ts

@@ -8,6 +8,78 @@ function packageName(dir: string): string | undefined {
   catch { return undefined; }
 }
 
+/** The vendor is published data, independent of its publisher's npm name. No package code is imported. */
+export function packVendor(dir: string): string | undefined {
+  const facts = join(dir, 'generated', 'pack-facts.json');
+  if (existsSync(facts)) {
+    const document = JSON.parse(readFileSync(facts, 'utf8')) as { packs?: Record<string, { protocol?: { declared?: string } }> };
+    const vendors = Object.keys(document.packs ?? {});
+    if (vendors.length !== 1 || !/^[a-z][a-z0-9-]*$/.test(vendors[0]!) || document.packs![vendors[0]!]!.protocol?.declared !== '3') throw new Error(`Invalid pack identity in ${facts}`);
+    return vendors[0];
+  }
+  // Source checkouts predate release facts; their conventional name remains sufficient for development.
+  const match = /^@[^/]+\/twin-([a-z][a-z0-9-]*)$/.exec(packageName(dir) ?? '');
+  return match?.[1] === 'standard' || match?.[1] === 'catalog' ? undefined : match?.[1];
+}
+
+/** Nearest installed package wins only over another installation of the SAME package. A World's explicit
+ * package choice wins over a catalog recommendation; different publishers' versions never compete. */
+export function installedVendorPacks(from: string): Map<string, string> {
+  const packages = new Map<string, { dir: string; vendor: string }>();
+  const seen = new Set<string>();
+  const pins = new Map<string, string>();
+  let at = resolve(from);
+  for (;;) {
+    const config = join(at, '.volter', 'world.json');
+    if (existsSync(config)) {
+      const document = JSON.parse(readFileSync(config, 'utf8')) as { services?: Array<{ id: string; source?: { package?: string }; package?: string }> };
+      for (const service of document.services ?? []) {
+        const name = service.source?.package ?? service.package;
+        if (name && !pins.has(service.id)) pins.set(service.id, name);
+      }
+    }
+    const modules = join(at, 'node_modules');
+    if (existsSync(modules)) {
+      const directories = readdirSync(modules, { withFileTypes: true }).filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith('.')).flatMap((e) => e.name.startsWith('@') ? readdirSync(join(modules, e.name)).map((n) => join(modules, e.name, n)) : [join(modules, e.name)]);
+      for (const dir of directories) {
+        const name = packageName(dir);
+        if (!name || seen.has(name)) continue;
+        seen.add(name);
+        if (!existsSync(join(dir, 'generated', 'pack-facts.json')) && !/^@[^/]+\/twin-/.test(name)) continue;
+        if (!isDerivedPack(dir)) continue;
+        const vendor = packVendor(dir);
+        if (vendor) packages.set(name, { dir, vendor });
+      }
+    }
+    const parent = dirname(at); if (parent === at) break; at = parent;
+  }
+  const index = installedPackageDir(from, '@volter/twin-catalog');
+  const file = index && join(index, 'recommendations.json');
+  const recommendations = file && existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) as Record<string, string> : {};
+  const revokedFile = index && join(index, 'revocations.json');
+  const revocations = revokedFile && existsSync(revokedFile) ? JSON.parse(readFileSync(revokedFile, 'utf8')) as Array<{ package: string; version: string }> : [];
+  for (const [id, name] of [...pins]) {
+    const vendor = packages.get(name)?.vendor;
+    if (vendor && vendor !== id) {
+      if (pins.has(vendor) && pins.get(vendor) !== name) throw new Error(`${vendor}: a World must select one package implementation`);
+      pins.set(vendor, name);
+    }
+  }
+  const result = new Map<string, string>();
+  for (const vendor of new Set([...packages.values()].map((p) => p.vendor))) {
+    const candidates = [...packages.entries()].filter(([, p]) => p.vendor === vendor);
+    const selected = pins.get(vendor) ?? recommendations[vendor];
+    const choice = selected ? candidates.find(([name]) => name === selected) : candidates.length === 1 ? candidates[0] : undefined;
+    if (!choice) throw new Error(`${vendor}: ${selected ? `selected package ${selected} is not installed` : `multiple implementations installed (${candidates.map(([name]) => name).join(', ')})`}; name the chosen source.package in .volter/world.json`);
+    if (!pins.has(vendor)) {
+      const version = (JSON.parse(readFileSync(join(choice[1].dir, 'package.json'), 'utf8')) as { version?: string }).version;
+      if (revocations.some((r) => r.package === choice[0] && r.version === version)) throw new Error(`${vendor}: installed ${choice[0]}@${version} is revoked; install an approved release or retain an existing explicit World pin`);
+    }
+    result.set(vendor, choice[1].dir);
+  }
+  return result;
+}
+
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export function installedPackageDir(from: string, name: string): string | undefined {
   let dir = resolve(from);
@@ -39,12 +111,12 @@ export function packRepository(from: string): string | undefined {
 /** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */
 export function vendorPackageDir(from: string, vendor: string): string | undefined {
   if (!/^[a-z][a-z0-9-]*$/.test(vendor)) return undefined;
-  const candidate = installedPackageDir(from, `@volter/twin-${vendor}`);
-  const installed = candidate && isDerivedPack(candidate) ? candidate : undefined;
+  const installed = installedVendorPacks(from).get(vendor);
   const repo = packRepository(from);
   const checkout = repo === undefined ? undefined : join(repo, vendor);
   if (!checkout || packageName(checkout) !== `@volter/twin-${vendor}` || !isDerivedPack(checkout)) return installed;
   if (!installed) return checkout;
+  if (packageName(installed) !== packageName(checkout)) return installed;
   const major = (dir: string): number => {
     try { return Number(/^(\d+)/.exec((JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { version?: string }).version ?? '')?.[1] ?? 0); } catch { return 0; }
   };
@@ -64,7 +136,7 @@ export function vendorOfPackModule(modulePath: string): string | undefined {
   let dir = dirname(resolve(modulePath));
   for (;;) {
     const name = packageName(dir);
-    if (name !== undefined) return name.startsWith('@volter/twin-') ? name.slice('@volter/twin-'.length) : undefined;
+    if (name !== undefined) return packVendor(dir);
     const up = dirname(dir);
     if (up === dir) return undefined;
     dir = up;

package/src/runtime.ts

@@ -5,7 +5,7 @@
 // contract: the kernel's root"). Removed v1 entry points fail explicitly. Conformance and validation tooling lives in
 // @volter/world-tooling, a dev dependency.
 // Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
-export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './packRegistry.ts';
+export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, PACK_ARCHETYPES, protocolStanding } from './packRegistry.ts';
 export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.ts';
 // The DELIVER verb (`emit`) — vendor-agnostic engine + CLI glue; packs declare a TwinEmitter
 // (their event catalog, endpoints-from-state, and signed synthesis) on `TwinPack.emitter`.
@@ -15,10 +15,10 @@ export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
 export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
-export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
+export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from './derived.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
 export type { Traceparent } from './trace-context.ts';
-export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
+export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
 export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.ts';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
@@ -291,7 +291,7 @@ export type {
   WorldMarker,
 } from './changeset.ts';
 export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets, type PackAssetStore } from './pack-assets.ts';
-export { installedPackageDir, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.ts';
+export { installedPackageDir, installedVendorPacks, packVendor, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from './pack-paths.ts';
 
 // The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
 export * as git from './git/index.ts';