@volter/world-runtime 2.0.55 → 3.0.0

package/src/origin.ts

@@ -1,11 +1,11 @@
-import { captureHistory, historyDigest, originHead, publishOriginHistory, type HistoryLayout, type HistoryReference, readHistoryView, historyLength, worldPaths } from '@volter/world-core';
+import { captureHistory, historyDigest, originHead, publishOriginHistory, type HistoryLayout, type HistoryReference, readHistoryView, historyLength, worldPaths } from '@volter/world-core/runtime';
 // `volter world clone` and `fetch` — a world's ORIGIN is another world, served (docs/concepts/the-model.md
 // #a-branch-is-a-position-not-a-copy: a clone is a branch whose parent is at a URL): its whole log per twin is this world's PARENT. `clone` records the origin
 // and brings every twin's log in from position zero; `fetch` appends what the origin has past the
 // recorded position. Nothing here touches a vendor: an origin is always a world, the token is the
 // served world's, and what arrives are entries — the parent log grows, the branch log is untouched.
 import { join, resolve } from 'node:path';
-import { appendOriginEntry, appendParentEntry, branchEntries, getActiveWorldStore, landedIds, originEntries, parentEntries, readBranchMeta, type Entry, wholeLog, withAncestryLock, writeBranchMeta } from '@volter/world-core';
+import { appendOriginEntry, appendParentEntry, branchEntries, getActiveWorldStore, landedIds, originEntries, parentEntries, readBranchMeta, type Entry, wholeLog, withHistoryLock, writeBranchMeta } from '@volter/world-core/runtime';
 import { saveWorldInstance, statusWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 import { fetchReady, isPathRemote, localWorld, TOKEN_HEADER } from './served-world.ts';
@@ -55,13 +55,14 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
   const appended: Record<string, number> = {};
   const behind: Record<string, number> = {};
   const snapshots: FetchOutcome['snapshots'] = {};
-  withAncestryLock(() => {
-    for (const service of services) {
-      const controlRoot = join(instance.dirs.data, service);
-      const meta = readBranchMeta(stateServiceOf(controlRoot, service), controlRoot);
+  for (const service of services) {
+    const controlRoot = join(instance.dirs.data, service);
+    const state = stateServiceOf(controlRoot, service);
+    withHistoryLock(worldPaths(state, controlRoot).dir, () => {
+      const meta = readBranchMeta(state, controlRoot);
       if (meta?.parent && !meta.origin) throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
-    }
-  });
+    });
+  }
   for (const service of services) {
     const controlRoot = join(instance.dirs.data, service);
     const state = stateServiceOf(controlRoot, service);
@@ -69,7 +70,8 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
       // A PARENT ON THIS MACHINE is read live through the pointer, like a local branch (contract
       // "Just like Neon", 1): nothing is copied; a clone points at the parent's head, a fetch only
       // says how far the parent has moved past this branch's position
-      withAncestryLock(() => {
+      // under the branch's history lock, as rebase is: a fetch cannot restore a pointer a concurrent rebase advanced
+      withHistoryLock(worldPaths(state, controlRoot).dir, () => {
       const target = localWorld(origin.url);
       const at = join(target.instance.dirs.data, service);
       const parentState = stateServiceOf(at, service);
@@ -109,7 +111,7 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
       page = await pageOf(origin, service, entries.length, options.key, first.view);
     }
     if (historyDigest({ layout: first.layout, entries }) !== first.digest) throw new Error('Origin history digest mismatch');
-    withAncestryLock(() => {
+    withHistoryLock(worldPaths(state, controlRoot).dir, () => {
     const meta = readBranchMeta(state, controlRoot);
       if (meta?.parent && !meta.origin) throw new Error('Cannot attach a first origin to an existing local fork; clone the origin before branching');
     const cached = publishOriginHistory(state, controlRoot, first.view, first.layout, entries);

package/src/pack-facts.ts

@@ -2,7 +2,7 @@
 // (packages/world-core/generated/pack-facts.json, compiled by scripts/pack-facts.ts
 // from each pack's `pack: TwinPack` descriptor).
 //
-// During the descriptor-first migration (adding-a-twin.md §3) (adding-a-twin.md §3 (the descriptor is the one home)), the
+// During the descriptor-first migration (architecture.md, "The descriptor": the descriptor is the one home), the
 // adoption tables here are the UNION of the legacy central maps and the pack declarations.
 // The overlay MUTATES the central tables at module init — every use-site keeps reading the
 // object it always read — and a fact declared in BOTH places throws: dual declaration is the
@@ -10,23 +10,29 @@
 
 import factsDocument from '@volter/world-core/generated/pack-facts.json' with { type: 'json' };
 
-export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[]; tools?: Array<{ package: string; usage: 'build' | 'deployment' }> };
+export type PackAdoption = { sdks?: string[]; pypi?: string[]; scopes?: string[]; envStems?: string[]; worldIds?: string[]; tools?: Array<{ package: string; usage: 'build' | 'deployment' }>; configFiles?: Array<{ file: string; usage: 'application' | 'build' | 'deployment'; when?: string }> };
 export type PackFacts = {
+  serverBacking?: { command: string };
   /** Existing descriptor transport, compiled into the same artifact as endpoint/adoption facts. */
   transport?: string;
-  /** Optional native frontend of the same state owner, selected explicitly on the pack CLI. */
-  nativeTransport?: { protocol: string; flag: string; upstreamEnv: string };
   adoption?: PackAdoption;
   hosts?: Array<{ host?: string; suffix?: string; hostPattern?: string; pathPattern?: string; key?: string; exclude?: true }>;
   hostsNone?: string;
   endpointEnv?: { name: string; templates?: Record<string, string>; note: string };
   endpointEnvNone?: string;
+  /** The door that issues the application a credential the twin accepts (TwinPack.credentialDoor). */
+  credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
+  credentialIssuer?: string;
   /** The pack's colocatable `create<Name>TwinServer` factory export, derived (or descriptor-
    *  declared under ambiguity) by scripts/pack-facts.ts. Consumed by `init` to emit
    *  `colocate:` service entries so a world's twins boot inside ONE host process (R2a). */
   serveExport?: string;
+  /** The managed-infrastructure kind this pack is the World's backing for (architecture.md, "The descriptor"). */
+  managedService?: { kind: 'redis' | 'mongodb'; scheme: string; note: string };
   /** The World's managed database the runtime binds the twin to at boot (TwinPack.managedDatabase). */
   managedDatabase?: { kind: 'postgres'; arg: string; note: string };
+  /** Listeners the twin opens beside its main port, allocated and recorded by the runtime (TwinPack.sidePorts). */
+  sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; note: string }>;
   /** R16: the protocol major the package targets and its standing against the kernel that compiled the artifact. */
   protocol?: { declared?: string; major: number; standing: 'current' | 'deprecated' | 'refused' | 'assumed' };
 };
@@ -36,7 +42,16 @@ export type PackFacts = {
 // core's artifact, imported as a JSON module: the published runtime resolves it beside an installed
 // core, a bundle carries it, and no host needs a filesystem to read it
 export function packFacts(): Record<string, PackFacts> {
-  return (factsDocument as unknown as { packs: Record<string, PackFacts> }).packs;
+  return merged ??= { ...(factsDocument as unknown as { packs: Record<string, PackFacts> }).packs, ...overlaid };
+}
+/** The facts of packs the kernel was not built with: a released pack carries its own (`generated/pack-facts.json`), and
+ *  the catalog overlays them here, vendor by vendor, over the built-in ones (architecture, "The catalog: where twins
+ *  come from"). The central tables overlaid at module init keep the built-in adoption facts. */
+const overlaid: Record<string, PackFacts> = {};
+let merged: Record<string, PackFacts> | undefined;
+export function overlayPackFacts(packs: Record<string, PackFacts>): void {
+  Object.assign(overlaid, packs);
+  merged = undefined;
 }
 
 const dual = (vendor: string, kind: string, key: string, holder: string): Error =>
@@ -99,7 +114,8 @@ export function overlayCoversMaps(maps: {
       maps.scopeVendors[scope] = vendor;
     }
     for (const stemRaw of facts.adoption?.envStems ?? []) {
-      const stem = stemRaw.toLowerCase();
+      // normalized as covers.ts reads a name's stem (`UPSTASH_REDIS_REST_URL` → `upstashredis`)
+      const stem = stemRaw.toLowerCase().replace(/[^a-z0-9]/g, '');
       if (stem in maps.envStemVendors) throw dual(vendor, 'env stem', stem, 'ENV_STEM_VENDORS');
       maps.envStemVendors[stem] = vendor;
     }

package/src/pglite-backing.ts

@@ -18,6 +18,7 @@ import { dirname, join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { findInstalledPackage, packCli } from './catalog.ts';
+import { vendorPackageDir } from '@volter/world-core/runtime';
 
 export interface InfraService { kind: string; hostPort: number }
 
@@ -80,7 +81,7 @@ function pidPath(dataDir: string, kind: string): string {
  *  this runtime was installed with (its dependency, or the checkout's workspace link). */
 export function mongodbTwinCli(worldConfig?: string, froms: string[] = [...(worldConfig ? [dirname(worldConfig)] : []), here()]): string {
   for (const from of froms) {
-    const dir = findInstalledPackage(from, MONGODB_TWIN);
+    const dir = vendorPackageDir(from, 'mongodb') ?? findInstalledPackage(from, MONGODB_TWIN);
     const cli = dir === undefined ? undefined : packCli(dir);
     if (cli !== undefined) return cli;
   }

package/src/placeholder.ts

@@ -9,7 +9,7 @@ import { materializeRoots } from './root.ts';
 import { loadWorldConfig } from './configs.ts';
 import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core';
+import { beginPlaceholderPull, endPlaceholderPull, listEvents, PLACEHOLDER_REMOTE, worldStateRoot } from '@volter/world-core/runtime';
 import { downWorld, runWithWorldEnv, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 
@@ -37,12 +37,21 @@ function placeholderCount(controlRoot: string): number {
   return n;
 }
 
-/** Pull from the placeholder: every twin's window open around the seed entry. */
+/** The twins of a World's config that have a root (a vendor's real account behind them). */
+function rootedTwins(instance: WorldInstance, root: string): string[] {
+  const { config } = loadWorldConfig(existsSync(instance.configPath) ? instance.configPath : instance.config, root);
+  return config.services.filter((s) => (s as { root?: unknown }).root).map((s) => s.id);
+}
+
+/** Pull from the placeholder: every twin's window open around the seed entry (a twin with a root excepted). */
 export async function seedWorld(name: string, options: SeedWorldOptions = {}): Promise<SeedWorldOutcome> {
   const root = resolve(options.root ?? process.cwd());
   const instance = statusWorld(name, root);
   const entry = seedEntryFor(instance, options.entry);
-  const services = Object.keys(instance.services).sort();
+  // a vendor-backed twin is not seeded (architecture, "Refresh"): its state is its root's, and the default data's runner
+  // skips the twins named in VOLTER_SEED_SKIP
+  const rooted = new Set(rootedTwins(instance, root));
+  const services = Object.keys(instance.services).filter((s) => !rooted.has(s)).sort();
   const at = new Date().toISOString();
   for (const service of services) beginPlaceholderPull(service, join(instance.dirs.data, service), at);
   let exitCode = 1;
@@ -55,7 +64,7 @@ export async function seedWorld(name: string, options: SeedWorldOptions = {}): P
       if (major < 22 || (major === 22 && minor < 6)) throw new Error(`${entry} is TypeScript: seeding it under Node needs Node 22.6 or newer (type stripping), or Bun; this is Node ${process.versions.node}`);
     }
     const runner = typeof Bun !== 'undefined' ? ['bun', entry] : [process.execPath, '--experimental-strip-types', '--no-warnings', entry];
-    exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry) });
+    exitCode = await runWithWorldEnv(name, runner, root, { cwd: options.cwd ?? dirname(entry), env: { VOLTER_SEED_SKIP: [...rooted].sort().join(',') } });
   } finally {
     for (const service of services) endPlaceholderPull(service, join(instance.dirs.data, service));
   }

package/src/project-inspect.ts

@@ -21,13 +21,13 @@ export type ProjectInspection = {
 /** npm package → vendor/twin mapping — the shared vendor↔SDK knowledge used by both
  * `inspect-project` (adoption discovery) and `covers` (room-setup coverage proof).
  * The canonical entry for each pack is the real client package that pack's own tests
- * prove the twin against (see each `packages/twin/<pack>/package.json` devDependencies);
+ * prove the twin against (see each pack's package.json devDependencies);
  * the extra aliases are the vendor's other official/first-party clients of the same
  * API surface. */
 export const SDK_TWINS: Record<string, { vendor: string; twin: string }> = {
   // (empty — every entry has moved onto its pack descriptor. See the note below.)
 };
-// descriptor-first migration (adding-a-twin.md §3), COMPLETE for this table: every pack declares its own sdk names
+// descriptor-first migration (architecture.md, "The descriptor"), COMPLETE for this table: every pack declares its own sdk names
 // (`adoption.sdks` on its descriptor, compiled into the committed pack-facts artifact), and the
 // literal above is now empty — the map is populated entirely by the overlay below. It is kept as
 // the overlay's target, not as a home: the exported object identity is what every use site already

package/src/redirect-proxy.ts

@@ -1,4 +1,4 @@
-import { serveHttp, type HttpServer } from '@volter/world-core';
+import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
 import { websocketRelay } from './websocket-relay.ts';
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
@@ -185,6 +185,14 @@ function caPaths(tlsDir: string): CaPaths {
   return { dir: tlsDir, caKey: join(tlsDir, 'ca-key.pem'), caCert: join(tlsDir, 'ca-cert.pem') };
 }
 
+/** Whether this host opens raw sockets to other hosts, which the ambient TLS redirect proxy exists to intercept. A
+ * browser tab's Node (tabnode, which declares `process.versions.webcontainer`) opens none: its TLS is loopback pairing
+ * with no handshake, and a remote HTTPS call leaves through the page's HTTP transport. There no proxy can run and none
+ * is needed: the World's network policy is enforced by the injector in every Node program (world-core inject.cjs). */
+export function hostHasRawEgress(versions: Record<string, string | undefined> = process.versions): boolean {
+  return versions.webcontainer === undefined;
+}
+
 export function opensslAvailable(): boolean {
   // TEST-ONLY seam (TWIN-64): forces "openssl unavailable" deterministically. A PATH-shim (fake
   // `openssl` on PATH) doesn't reliably work here because `spawnSync('openssl', …)` below is called

package/src/redis-backing.ts

@@ -6,13 +6,14 @@
 //
 // Why the twin and not a container: a World's state branches, checkpoints and rolls back as one tree, and a Redis
 // in a container is state outside it (a branch of the World would share the container's queue and cache). The
-// twin keeps each key a subject of the World (packages/twin/redis/src/redis-storage.ts). It needs nothing
+// twin keeps each key a subject of the World (the Redis pack's storage module). It needs nothing
 // installed: no container runtime, no redis-server binary.
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { connect } from 'node:net';
 import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { findInstalledPackage, packCli } from './catalog.ts';
+import { vendorPackageDir } from '@volter/world-core/runtime';
 import type { HostLaunch, InfraService } from './pglite-backing.ts';
 
 const PACKAGE = '@volter/twin-redis';
@@ -21,7 +22,7 @@ const READY_TIMEOUT_MS = 60_000;
 /** The redis twin's cli: installed beside this runtime (its node_modules walk), else beside the World's config. */
 export function redisTwinCli(from: string[]): string | undefined {
   for (const dir of from) {
-    const found = findInstalledPackage(dir, PACKAGE);
+    const found = vendorPackageDir(dir, 'redis') ?? findInstalledPackage(dir, PACKAGE);
     const cli = found === undefined ? undefined : packCli(found);
     if (cli !== undefined && existsSync(cli)) return cli;
   }
@@ -68,6 +69,7 @@ export async function redisTwinUp(services: InfraService[], dataDir: string, cli
     const child = spawn(process.execPath, [...runtime, cli, 'serve', '--port', String(service.hostPort), '--root', root], {
       env: launch.env ?? process.env,
       detached: true,
+      windowsHide: true,
       stdio: ['ignore', logFd, logFd],
     });
     child.unref();

package/src/reflect.ts

@@ -1,4 +1,4 @@
-import { serveHttp, type HttpServer } from '@volter/world-core';
+import { serveHttp, type HttpServer } from '@volter/world-core/runtime';
 import { websocketRelay } from './websocket-relay.ts';
 import { sessionTrustEnv } from './ca-trust.ts';
 // The reflect attachment (docs/guides/route-a-cli-through-the-world.md): attach an UNMODIFIED consumer —

package/src/root.ts

@@ -7,15 +7,16 @@
 // never in a pack, never an env var). `volter world deploy` performs landed entries against each
 // root through the pack's adapters over the kernel executor, with the world's checks in front;
 // `deploy: auto` does the same the moment an entry is appended (the host installs the hook).
+import { randomBytes } from 'node:crypto';
 import { packEntry } from './catalog.ts';
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import {
-  NO_SECRETS_CHECK, authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, observeAppends, readRoot, registerStateSystem, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type PushReport, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
-} from '@volter/world-core';
+  NO_SECRETS_CHECK, authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, observeAppends, readRoot, registerStateSystem, stateDirName, stateSystemFor, type Check, type CredentialPayload, type PerformAction, type RemoteExecute, type RootConfig, type SealedCredential, type TwinAction, validateRemoteOrigin, writeRoot,
+} from '@volter/world-core/runtime';
 import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from './configs.ts';
-import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, type DeployReport, type ObserveReport } from '@volter/world-core';
+import { changesetReadiness, collectObservations, type Observation, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding, userKek, vendorPackageDir, type DeployReport, type ObserveReport } from '@volter/world-core/runtime';
 import { findWorldChangeset, listWorldChangesets } from './changeset.ts';
 import { importModule } from './import-module.ts';
 import { statusWorld } from './runtime.ts';
@@ -23,14 +24,13 @@ import { envNameVendor } from './covers.ts';
 import { parseEnvFile } from './init.ts';
 import { fakeEnvValue } from './fixture-env.ts';
 import { projectManifestDirs } from './project-inspect.ts';
-import { findInstalledPackage, twinPackageName } from './catalog.ts';
 import type { WorldConfig } from './schema.ts';
 
 // ── the user's sealing key ──────────────────────────────────────────────────────────────────
 
 /** `$XDG_CONFIG_HOME/volter/kek`, else `~/.config/volter/kek`: the key every credential this user
  *  seals is wrapped under. Made on first use, 0600, never printed. */
-export { userKek, userKekPath } from '@volter/world-core';
+export { userKek, userKekPath } from '@volter/world-core/runtime';
 
 // ── the sealed credential, beside the world ─────────────────────────────────────────────────
 
@@ -64,13 +64,17 @@ export async function rewrapTwinCredentials(worldRoot: string): Promise<{ rewrap
   return out;
 }
 
-/** Seal a vendor's credential beside the World, bound to `bound` (destinationOf the root's or link's origin): it opens
- *  for that destination only, so pointing the root or link elsewhere never sends it there. */
-export async function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string | undefined, bound: string): Promise<{ placedAt: string; fingerprint: string }> {
+/** Seal a vendor's credential beside the World, under the current sealer (the host's vault, else the key: company
+ *  decision 0034), bound to `bound` (destinationOf the root's or link's origin): it opens for that destination only, so
+ *  pointing the root or link elsewhere never sends it there. Its ingest door's signing secret is sealed with it
+ *  (architecture, "Ingest"): the one the vendor issued, given in the payload (`signingSecret`), else one minted here and
+ *  answered once, to enter at the vendor where the operator chooses the webhook's secret. */
+export async function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string | undefined, bound: string): Promise<{ placedAt: string; fingerprint: string; mintedSigningSecret?: string }> {
   if (!/^origin=https?:\/\/[^/]+$/.test(bound)) throw new Error(`a credential is sealed for a destination (destinationOf its root's or link's origin), not ${JSON.stringify(bound)}`);
-  const sealed = await currentSealer().seal(payload, at ?? new Date().toISOString(), vendor, bound);
+  const minted = typeof payload.signingSecret === 'string' && payload.signingSecret.length >= 8 ? undefined : randomBytes(24).toString('hex');
+  const sealed = await currentSealer().seal(minted ? { ...payload, signingSecret: minted } : payload, at ?? new Date().toISOString(), vendor, bound);
   getActiveWorldStore().write(credentialPath(worldRoot, vendor), `${JSON.stringify(sealed, null, 2)}\n`, { secret: true });
-  return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint };
+  return { placedAt: sealed.placedAt, fingerprint: sealed.fingerprint, ...(minted ? { mintedSigningSecret: minted } : {}) };
 }
 /** The inventory of credentials sealed before bindings, kept sealed beside them (`.legacy-inventory.json`, its own
  *  slot): `pending` maps each such credential to the destination it is bound to, or null when it had none and so is
@@ -353,67 +357,31 @@ async function packModule(vendor: string, from: string): Promise<Record<string,
   const entry = packEntryPath(vendor, from);
   return entry ? await importModule(entry) : null;
 }
-/** The pack's module itself, installed beside the World or in this checkout: its every export (a
- *  mirror's shell and client), where the registry holds only the descriptor. */
-function packEntryPath(vendor: string, from: string): string | null {
-  const installed = findInstalledPackage(from, twinPackageName(vendor));
-  if (installed) return packEntry(installed);
-  const checkout = resolve(import.meta.dir, '..', '..', 'twin', vendor, 'src', 'index.ts');
-  return existsSync(checkout) ? checkout : null;
-}
-/** The pack's mirror module (`src/<vendor>-mirror-ui.ts`: its shell, client and stylesheet), read as the
- *  hosted mirror build reads it (apps/cloud/scripts/mirrors.ts); a pack's index need not re-export them. */
-export async function packMirrorExports(vendor: string, from: string): Promise<Record<string, unknown> | null> {
-  const entry = packEntryPath(vendor, from);
-  if (!entry) return null;
-  const dir = dirname(entry);
-  const file = existsSync(dir) ? readdirSync(dir).find((f) => /-mirror-ui\.(ts|js)$/.test(f) && !f.includes('.test.')) : undefined;
-  return importModule(file ? join(dir, file) : entry);
+/** The pack's directory: installed beside the World, in its pack repository, or in the pack repository beside this
+ *  platform checkout. */
+function packDir(vendor: string, from: string): string | undefined {
+  return vendorPackageDir(from, vendor) ?? vendorPackageDir(import.meta.dir, vendor);
 }
-/** A pack's mirror as the pack builds it (`<vendor>MirrorHtml`, `build<Vendor>MirrorClient`,
- *  `<vendor>MirrorStyles`), found the way a World finds the pack; null when the pack has none. The
- *  client builds at serve under Bun and is served prebuilt under Node, by the pack's own builder. */
-export type PackMirror = { html: () => string; client: () => Promise<string>; styles?: () => Promise<string>; /** the account and a credential its screens sign in with (`<vendor>MirrorSignIn`): the account found in the twin's
-   *  state at `root`, the credential minted for it through the twin's own doors (`twin`), never a stored one read back */
-  signIn?: (as: string, ctx: MirrorSignInContext) => Promise<{ account: string; token: string } | null> | { account: string; token: string } | null };
-/** What a pack's `<vendor>MirrorSignIn` is given: the twin's state root (to find the account) and the twin's own doors
- *  (to mint a credential for it, as the World's seed does through `/_twin/…`). */
-export type MirrorSignInContext = { root: string; twin: (path: string, init?: RequestInit) => Promise<Response> };
-export async function packMirror(vendor: string, from: string): Promise<PackMirror | null> {
-  const installed = findInstalledPackage(from, twinPackageName(vendor));
-  const dir = installed ?? resolve(import.meta.dir, '..', '..', 'twin', vendor);
-  // the pack's mirror module, as the hosted build reads it (its index need not re-export every builder)
-  const src = join(dir, 'src');
-  const file = existsSync(src) ? readdirSync(src).find((f) => f.endsWith('-mirror-ui.ts')) : undefined;
-  const entry = file ? join(src, file) : installed ? packEntry(installed) : join(src, 'index.ts');
-  if (!existsSync(entry)) return null;
-  const mod = await importModule(entry);
-  const pick = (re: RegExp): ((...a: unknown[]) => unknown) | undefined => { const k = Object.keys(mod).find((key) => re.test(key) && typeof mod[key] === 'function'); return k ? mod[k] as (...a: unknown[]) => unknown : undefined; };
-  const html = pick(/^\w+MirrorHtml$/); const client = pick(/^build\w+MirrorClient$/); const styles = pick(/^\w+MirrorStyles$/); const signIn = pick(/^\w+MirrorSignIn$/);
-  if (!html || !client) return null;
-  return { html: html as () => string, client: client as () => Promise<string>, ...(styles ? { styles: styles as () => Promise<string> } : {}), ...(signIn ? { signIn: signIn as PackMirror['signIn'] } : {}) };
+/** The pack's module itself: its every export, where the registry holds only the descriptor. */
+function packEntryPath(vendor: string, from: string): string | null {
+  const dir = packDir(vendor, from);
+  return dir === undefined ? null : packEntry(dir);
 }
-
-/** The real state system's adapters for a vendor: registered with the pack (protocol 2), else the
- *  pack's anchored exports (protocol 1: `perform<Name>Action`, `sync<Name>FromRemote`). */
+/** The real state system's adapters for a vendor: the ones its pack names on its descriptor. */
 export type IngestAdapter = (request: Request, ctx: { root?: string; secret?: string }) => Response | Promise<Response>;
-export async function adaptersFor(vendor: string, from: string): Promise<{ perform?: PerformAction; refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string }) => Promise<unknown>; ingest?: IngestAdapter }> {
+export async function adaptersFor(vendor: string, from: string): Promise<{ perform?: PerformAction; refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string; scope?: string }) => Promise<unknown>; ingest?: IngestAdapter }> {
   const registered = stateSystemFor(vendor);
   // a registration is the whole state system for that twin (a stub in a test, a pack's own
-  // descriptor); only an unregistered twin is resolved from the pack's anchored exports
+  // descriptor); an unregistered twin's are read from its pack's descriptor
   if (registered) return registered;
   const mod = await packModule(vendor, from);
   if (!mod) return {};
-  const pack = mod.pack as { protocol?: string; stateSystem?: { perform?: PerformAction; refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string }) => Promise<unknown> } } | undefined;
+  const pack = mod.pack as { protocol?: string; vendorBacked?: { none: string }; stateSystem?: { perform?: PerformAction; refresh?: (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string; scope?: string }) => Promise<unknown> } } | undefined;
+  if (pack?.vendorBacked?.none) throw new Error(`the ${vendor} pack has no vendor-backed half: ${pack.vendorBacked.none}`);
   if (pack?.stateSystem?.perform) { registerStateSystem(vendor, pack.stateSystem); return pack.stateSystem; }
-  // a protocol 2 pack NAMES its adapters (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin); only a protocol 1
-  // pack is resolved from its anchored exports
-  if (protocolStanding(pack?.protocol).major >= 2) throw new Error(`the ${vendor} pack declares protocol 2 but names no adapters — \`stateSystem: { perform, refresh?, ingest? }\` on its descriptor`);
-  const name = (re: RegExp) => Object.keys(mod).find((k) => re.test(k) && typeof mod[k] === 'function');
-  const performName = name(/^perform\w+Action$/); const refreshName = name(/^refresh\w+$/) ?? name(/^sync\w+FromRemote$/); const ingestName = name(/^ingest\w+Event$/);
-  const out = { ...(performName ? { perform: mod[performName] as PerformAction } : {}), ...(refreshName ? { refresh: mod[refreshName] as (execute: RemoteExecute, opts: { root?: string; origin?: string; credential?: string }) => Promise<unknown> } : {}), ...(ingestName ? { ingest: mod[ingestName] as IngestAdapter } : {}) };
-  if (out.perform) registerStateSystem(vendor, out);
-  return out;
+  // the kernel derives a pack's adapters from its manifest and surface (docs/contributing/architecture.md, "The
+  // real-system adapters"): its index registers packOf(manifest, surface)
+  throw new Error(`the ${vendor} pack derives no adapters: its index registers \`packOf(manifest)\` without its surface (\`create-pack <vendor> --index\` writes it with it), and its resources' \`refresh\` scopes say what a refresh reads`);
 }
 
 // ── the world's checks ──────────────────────────────────────────────────────────────────────
@@ -474,7 +442,7 @@ export async function refreshTwin(opts: { worldRoot: string; vendor: string; con
   const store = getActiveWorldStore();
   let value: unknown; let observations: Observation[];
   try {
-    ({ value, observations } = await collectObservations(() => adapters.refresh!(buildRemoteExecute(origin, credential, authStrategyFor(opts.vendor), getPack(opts.vendor)?.hosts, { custody: rootCustody(opts.root, opts.vendor) }), { root: opts.controlRoot, origin: adapterOrigin, ...(credentialFingerprint ? { credential: credentialFingerprint } : {}) })));
+    ({ value, observations } = await collectObservations(() => adapters.refresh!(buildRemoteExecute(origin, credential, authStrategyFor(opts.vendor), getPack(opts.vendor)?.hosts, { custody: rootCustody(opts.root, opts.vendor), vendor: opts.vendor }), { root: opts.controlRoot, origin: adapterOrigin, ...(opts.root.scope ? { scope: opts.root.scope } : {}), ...(credentialFingerprint ? { credential: credentialFingerprint } : {}) })));
   } catch (error) {
     // the vendor was asked and did not answer: the marker keeps the last fold's numbers and records the
     // failure — its reason and how many in a row — so the status door and the twin's status say so

package/src/runtime-test-support.ts

@@ -10,7 +10,7 @@ import net from 'node:net';
 import { spawnSync } from 'node:child_process';
 import { activateScript, doctorWorld, downWorld, ensureWorldProxy, runWithWorldEnv, runWorld, shareWorld, shareWorldServices, statusWorld, unshareWorld, upWorld, urlsWorld, worldShellEnv } from './runtime.ts';
 import { opensslAvailable } from './redirect-proxy.ts';
-import { stateDirName } from '@volter/world-core';
+import { stateDirName } from '@volter/world-core/runtime';
 
 /** Test-only seam (see runtime.ts `proxyDaemonDeadlineMs`): force the daemon-poll deadline to `ms`
  * for the duration of `fn`, then restore whatever was there before — deterministic, no sleeps. */