@volter/world-runtime 2.0.55 → 3.0.1

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

@@ -8,16 +8,18 @@ export type PackAdoption = {
         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;
@@ -34,16 +36,37 @@ export type PackFacts = {
         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;
@@ -52,6 +75,7 @@ export type PackFacts = {
     };
 };
 export declare function packFacts(): Record<string, PackFacts>;
+export declare function overlayPackFacts(packs: Record<string, PackFacts>): void;
 /** Overlay descriptor-declared npm SDK names onto the central SDK_TWINS map (project-inspect.ts). */
 /** The PyPI half of the SDK map, built the same way from each descriptor's `adoption.pypi`
  *  (PEP 503 names). One name belongs to one pack; a second claim refuses at load. */

package/dist/src/pack-facts.js

@@ -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
@@ -13,7 +13,16 @@ import factsDocument from '@volter/world-core/generated/pack-facts.json' with {
 // 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() {
-    return factsDocument.packs;
+    return merged ??= { ...factsDocument.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 = {};
+let merged;
+export function overlayPackFacts(packs) {
+    Object.assign(overlaid, packs);
+    merged = undefined;
 }
 const dual = (vendor, kind, key, holder) => new Error(`pack-facts: ${kind} "${key}" is declared BOTH on the ${vendor} pack descriptor AND in the central ${holder} table — ` +
     `the migration rule is one home per fact. Delete the central entry (the descriptor wins).`);
@@ -65,7 +74,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/dist/src/pglite-backing.js

@@ -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.js";
+import { vendorPackageDir } from '@volter/world-core/runtime';
 /** Parse the services out of world.infrastructure.yml. This is NOT a YAML
  * parser: init's renderComposeFile emits a deterministic shape, and this
  * reads exactly that shape back (service key at 2-space indent = the kind;
@@ -83,7 +84,7 @@ function pidPath(dataDir, kind) {
  *  this runtime was installed with (its dependency, or the checkout's workspace link). */
 export function mongodbTwinCli(worldConfig, froms = [...(worldConfig ? [dirname(worldConfig)] : []), here()]) {
     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/dist/src/placeholder.d.ts

@@ -12,7 +12,7 @@ export type SeedWorldOutcome = {
 };
 /** The seed entry `init` emits beside the world config, unless the caller names one. */
 export declare function seedEntryFor(instance: WorldInstance, entry?: string): string;
-/** Pull from the placeholder: every twin's window open around the seed entry. */
+/** Pull from the placeholder: every twin's window open around the seed entry (a twin with a root excepted). */
 export declare function seedWorld(name: string, options?: SeedWorldOptions): Promise<SeedWorldOutcome>;
 /** Back to the defaults: down with purge, up from the same config and env file, seed. */
 export declare function resetWorld(name: string, options?: SeedWorldOptions): Promise<SeedWorldOutcome & {

package/dist/src/placeholder.js

@@ -9,7 +9,7 @@ import { materializeRoots } from "./root.js";
 import { loadWorldConfig } from "./configs.js";
 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.js";
 /** The seed entry `init` emits beside the world config, unless the caller names one. */
 export function seedEntryFor(instance, entry) {
@@ -36,12 +36,20 @@ function placeholderCount(controlRoot) {
     }
     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, root) {
+    const { config } = loadWorldConfig(existsSync(instance.configPath) ? instance.configPath : instance.config, root);
+    return config.services.filter((s) => s.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, options = {}) {
     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);
@@ -56,7 +64,7 @@ export async function seedWorld(name, options = {}) {
                 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)

package/dist/src/project-inspect.d.ts

@@ -19,7 +19,7 @@ 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 declare const SDK_TWINS: Record<string, {

package/dist/src/project-inspect.js

@@ -5,13 +5,13 @@ import { normalizePypiName, overlayPypiTwins, overlaySdkTwins } from "./pack-fac
 /** 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 = {
 // (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/dist/src/redirect-proxy.d.ts

@@ -48,6 +48,11 @@ type CaPaths = {
     caKey: string;
     caCert: string;
 };
+/** 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 declare function hostHasRawEgress(versions?: Record<string, string | undefined>): boolean;
 export declare function opensslAvailable(): boolean;
 /** Generate (once) a throwaway CA in `tlsDir`. Idempotent: reuses an existing CA so a re-activate in
  * the same world trusts the same cert. Session/project-scoped — it lives under the instance dir and

package/dist/src/redirect-proxy.js

@@ -1,4 +1,4 @@
-import { serveHttp } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core/runtime';
 import { worldNetworkPolicyFromEnv, allowsWorldNetworkEgress } from '@volter/world-core/network-policy';
 import { websocketRelay } from "./websocket-relay.js";
 // The ambient TLS redirect proxy — the substance of "any CLI, zero config" (WORLD_ACTIVATE.md §"How
@@ -191,6 +191,13 @@ function shouldBlockUntwinned(value, env) {
 function caPaths(tlsDir) {
     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 = process.versions) {
+    return versions.webcontainer === undefined;
+}
 export function opensslAvailable() {
     // 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/dist/src/redis-backing.js

@@ -6,19 +6,20 @@
 //
 // 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.js";
+import { vendorPackageDir } from '@volter/world-core/runtime';
 const PACKAGE = '@volter/twin-redis';
 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) {
     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;
@@ -69,6 +70,7 @@ export async function redisTwinUp(services, dataDir, cli, launch = {}) {
         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/dist/src/reflect.js

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

package/dist/src/root.d.ts

@@ -1,9 +1,9 @@
-import { type Check, type CredentialPayload, type PerformAction, type RemoteExecute, type RootConfig } from '@volter/world-core';
-import { loadChecks, type DeployReport, type ObserveReport } from '@volter/world-core';
+import { type Check, type CredentialPayload, type PerformAction, type RemoteExecute, type RootConfig } from '@volter/world-core/runtime';
+import { loadChecks, type DeployReport, type ObserveReport } from '@volter/world-core/runtime';
 import type { WorldConfig } from './schema.js';
 /** `$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';
 export declare function credentialPath(worldRoot: string, vendor: string): string;
 /** Rewrap every credential sealed beside the World (each vendor's and each link's) under the newest version of the key
  *  that wrapped it: an operator's act after rotating the key, so no record still needs an old version. `current` is only
@@ -15,11 +15,15 @@ export declare function rewrapTwinCredentials(worldRoot: string): Promise<{
     current: string[];
     left: string[];
 }>;
-/** 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. */
+/** 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 declare function sealTwinCredential(worldRoot: string, vendor: string, payload: CredentialPayload, at: string | undefined, bound: string): Promise<{
     placedAt: string;
     fingerprint: string;
+    mintedSigningSecret?: string;
 }>;
 /** Bind each credential sealed before bindings to its destination, keeping its placedAt, fingerprint and rotatedAt,
  *  and only over the record that was read; and move every record still under the host's own key (v1) to the vault,
@@ -73,34 +77,7 @@ export declare function materializeRoots(config: WorldConfig, dataDir: string, w
 /** The root a state service under `controlRoot` is bound to — its own root.json, else a sibling
  *  state's (slack records under `chat`; the root was written under `slack`). */
 export declare function rootForControlRoot(controlRoot: string, service: string): MaterializedRoot | 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 declare function packMirrorExports(vendor: string, from: string): Promise<Record<string, unknown> | null>;
-/** 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 declare function packMirror(vendor: string, from: string): Promise<PackMirror | null>;
-/** 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;
@@ -111,6 +88,7 @@ export declare function adaptersFor(vendor: string, from: string): Promise<{
         root?: string;
         origin?: string;
         credential?: string;
+        scope?: string;
     }) => Promise<unknown>;
     ingest?: IngestAdapter;
 }>;

package/dist/src/root.js

@@ -7,13 +7,14 @@
 // 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.js";
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import { authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, readRoot, registerStateSystem, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core';
+import { authStrategyFor, currentSealer, destinationOf, sealsThroughVault, openSealedAt, getActiveWorldStore, getPack, buildRemoteExecute, clearRoot, readRoot, registerStateSystem, stateDirName, stateSystemFor, validateRemoteOrigin, writeRoot, } from '@volter/world-core/runtime';
 import { loadWorldConfig, worldChangesetRules, writeWorldConfig } from "./configs.js";
-import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, protocolStanding } from '@volter/world-core';
+import { changesetReadiness, collectObservations, foldObservations, loadChecks, openRootCredential, performEntries, rootCustody, vendorPackageDir } from '@volter/world-core/runtime';
 import { findWorldChangeset, listWorldChangesets } from "./changeset.js";
 import { importModule } from "./import-module.js";
 import { statusWorld } from "./runtime.js";
@@ -21,11 +22,10 @@ import { envNameVendor } from "./covers.js";
 import { parseEnvFile } from "./init.js";
 import { fakeEnvValue } from "./fixture-env.js";
 import { projectManifestDirs } from "./project-inspect.js";
-import { findInstalledPackage, twinPackageName } from "./catalog.js";
 // ── 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 ─────────────────────────────────────────────────
 export function credentialPath(worldRoot, vendor) {
     return join(resolve(worldRoot), stateDirName(), 'credentials', `${vendor}.json`);
@@ -77,14 +77,18 @@ export async function rewrapTwinCredentials(worldRoot) {
     }
     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. */
+/** 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, vendor, payload, at, bound) {
     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
@@ -424,70 +428,35 @@ async function packModule(vendor, from) {
     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, from) {
-    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, from) {
-    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, from) {
+    return vendorPackageDir(from, vendor) ?? vendorPackageDir(import.meta.dir, vendor);
 }
-export async function packMirror(vendor, from) {
-    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) => { const k = Object.keys(mod).find((key) => re.test(key) && typeof mod[key] === 'function'); return k ? mod[k] : 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, client: client, ...(styles ? { styles: styles } : {}), ...(signIn ? { signIn: signIn } : {}) };
+/** The pack's module itself: its every export, where the registry holds only the descriptor. */
+function packEntryPath(vendor, from) {
+    const dir = packDir(vendor, from);
+    return dir === undefined ? null : packEntry(dir);
 }
 export async function adaptersFor(vendor, from) {
     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;
+    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) => 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] } : {}), ...(refreshName ? { refresh: mod[refreshName] } : {}), ...(ingestName ? { ingest: mod[ingestName] } : {}) };
-    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 ──────────────────────────────────────────────────────────────────────
 /** `.volter/checks/*.ts|js`: each exports `check` (or default) as `{ name, run }`. The shipped
@@ -550,7 +519,7 @@ export async function refreshTwin(opts) {
     let value;
     let observations;
     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

package/dist/src/runtime-test-support.js

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import net from 'node:net';
 import { downWorld, statusWorld } from "./runtime.js";
-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. */
 export async function withProxyDeadline(ms, fn) {

package/dist/src/runtime.d.ts

@@ -78,8 +78,10 @@ export declare function sharingClaimAlive(claim: SharingClaim): boolean;
  *  run code that is not Volter's (a World's apps, a command attached to a World, a tunnel, a dependency install) are
  *  given an environment without it. */
 export declare function withoutVaultSignIn<T extends Record<string, string | undefined>>(env: T): T;
-/** The process's environment as the world admits it: what `stripEnv` names stays outside. */
 export declare function admittedEnv(strip: string[] | undefined, env?: NodeJS.ProcessEnv): Record<string, string>;
+/** The names a twin of this World was to issue and did not (its door failed): kept out of every command's env, so a
+ *  caller's own value (a real key in their shell) never stands in for the credential the World meant to issue. */
+export declare const UNISSUED_ENV = "VOLTER_WORLD_UNISSUED";
 export declare function saveWorldInstance(instance: WorldInstance): void;
 /**
  * THE MANAGED-DATABASE BINDING (architecture.md, managed infrastructure: the data plane's declared exception): for a
@@ -197,12 +199,16 @@ export declare function listWorlds(root?: string): Array<{
     degraded?: boolean;
     config?: string;
 }>;
+/** The env with each `$app-url` value made the application URL its booter recorded. Unrecorded, the name is left
+ *  unset (the application's own env files decide) and the command is told how to record it: never a guess. */
+export declare function withAppUrl<E extends Record<string, string | undefined>>(name: string, root: string, env: E): E;
 /** Runs the command in the world's env in the foreground and resolves to its exit code. The child is
  *  awaited, not blocked on: a runtime that runs no synchronous child (the browser engine) still runs
  *  this one, and the caller sees no difference — stdio is inherited either way. */
 export declare function runWithWorldEnv(name: string, command: string[], root?: string, options?: {
     cwd?: string;
     verbose?: boolean;
+    env?: Record<string, string>;
 }): Promise<number>;
 /** Local CLI attachment with one instance-bound consumer record per concurrent command.
  * The synchronous SDK method remains compatible; its consumers are explicitly untracked. */