@volter/world-runtime 3.0.163 → 3.0.165

package/dist/src/native-server-inputs.d.ts

@@ -0,0 +1,16 @@
+import { type NativeMariaDBReference } from './mariadb-supplier.js';
+export interface NativeServerInputs extends NativeMariaDBReference {
+    image: string;
+    declarationSha256: string;
+    snapshotSha256: string;
+}
+export declare function nativeServerReference(value: unknown): NativeServerInputs;
+export declare function nativeServerRuntimeReference(reference: NativeServerInputs): NativeMariaDBReference;
+/** Validate metadata and use these verified owned byte copies at the later write boundary. */
+export declare function readNativeServerInputs(parent: string, value: unknown): {
+    reference: NativeServerInputs;
+    files: ReadonlyMap<string, Buffer>;
+    aliases: string[];
+};
+/** Only World init writes its configuration tree, using the exact bytes it reverified itself. */
+export declare function copyNativeServerInputs(parent: string, reference: NativeServerInputs, world: string): NativeMariaDBReference;

package/dist/src/native-server-inputs.js

@@ -0,0 +1,204 @@
+// World init owns this copy. Custody never initializes a server or admits a program.
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, posix, relative } from 'node:path';
+import { nativeMariaDBReference } from "./mariadb-supplier.js";
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+const hex = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+const record = (value) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Native managed inputs need object metadata');
+    return value;
+};
+const regular = (path) => {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('Native input must be a regular owned file');
+    return readFileSync(path);
+};
+const confined = (root, name) => {
+    if (!name || isAbsolute(name) || name.includes('\\') || name.includes('\0') || posix.normalize(name) !== name
+        || name.split('/').some(part => !part || part === '.' || part === '..'))
+        throw new Error('Native input path is not confined');
+    const path = join(root, name), rel = relative(root, realpathSync(path));
+    if (!rel || rel === '..' || rel.startsWith('../') || isAbsolute(rel))
+        throw new Error('Native input path leaves its owned root');
+    return path;
+};
+export function nativeServerReference(value) {
+    const row = record(value);
+    const { image, declarationSha256, snapshotSha256, ...provider } = row;
+    const reference = nativeMariaDBReference(provider);
+    if (typeof image !== 'string' || !/^docker\.io\/library\/mariadb@sha256:[a-f0-9]{64}$/u.test(image)
+        || !hex(declarationSha256) || !hex(snapshotSha256))
+        throw new Error('Native managed source requires a resolved image and exact snapshot/declaration');
+    return { ...reference, image, declarationSha256, snapshotSha256 };
+}
+export function nativeServerRuntimeReference(reference) {
+    const { image: _image, declarationSha256: _declaration, snapshotSha256: _snapshot, ...provider } = reference;
+    return { ...provider, directory: `native-inputs/${reference.receiptSha256}/${reference.declarationSha256}` };
+}
+/** Validate metadata and use these verified owned byte copies at the later write boundary. */
+export function readNativeServerInputs(parent, value) {
+    const reference = nativeServerReference(value), base = realpathSync(parent);
+    const root = confined(base, reference.directory), stat = lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('Native managed snapshot must be a regular directory');
+    const manifestBytes = regular(confined(root, 'manifest.json'));
+    if (sha(manifestBytes) !== reference.snapshotSha256)
+        throw new Error('Native managed snapshot changed');
+    const manifest = record(JSON.parse(manifestBytes.toString('utf8'))), measured = record(manifest.files);
+    if (manifest.kind !== 'volter.native-server-inputs' || manifest.version !== 1 || manifest.receiptSha256 !== reference.receiptSha256
+        || Object.keys(manifest).some(key => !['kind', 'version', 'receiptSha256', 'files'].includes(key)))
+        throw new Error('Invalid native managed snapshot');
+    const required = ['artifact.json', 'source-receipt.json', 'recipe-inputs/recipe.json', 'recipe-inputs/release.json',
+        'recipe-inputs/image-index.json', 'recipe-inputs/image-manifest.json', 'recipe-inputs/image-config.json', 'declaration.json'];
+    if (Object.keys(measured).sort().join('\0') !== required.sort().join('\0'))
+        throw new Error('Native runtime evidence subset differs');
+    const files = new Map();
+    for (const [name, value] of Object.entries(measured)) {
+        const pin = record(value), bytes = regular(confined(root, name));
+        if (Object.keys(pin).some(key => !['bytes', 'sha256'].includes(key)) || !Number.isSafeInteger(pin.bytes)
+            || pin.bytes !== bytes.length || !hex(pin.sha256) || sha(bytes) !== pin.sha256)
+            throw new Error('Native managed input bytes changed: ' + name);
+        files.set(name, bytes);
+    }
+    const inventory = [];
+    const walk = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                walk(path);
+            else
+                inventory.push(relative(root, path).split(posix.sep).join('/'));
+        }
+    };
+    walk(root);
+    if (inventory.sort().join('\0') !== [...required, 'manifest.json'].sort().join('\0'))
+        throw new Error('Native managed snapshot contains unmeasured files');
+    const receiptBytes = files.get('artifact.json'), receipt = record(JSON.parse(receiptBytes.toString('utf8')));
+    const source = record(receipt.source), recipe = record(receipt.recipe), image = record(receipt.imageBinding), originalMap = record(receipt.files);
+    if (sha(receiptBytes) !== reference.receiptSha256 || receipt.kind !== 'sweep.wali-native-managed-server' || receipt.version !== 1
+        || receipt.complete !== true || receipt.sourceUnchanged !== true || receipt.qualified !== false || receipt.admitted !== false
+        || receipt.target !== 'wasm32-linux-muslwali' || receipt.prefix !== 'prefix/opt/programs/mariadb/' + reference.release
+        || source.version !== reference.release || source.sha256 !== reference.sourceSha256
+        || recipe.path !== reference.recipe.path || recipe.sha256 !== reference.recipe.sha256
+        || sha(files.get('recipe-inputs/recipe.json')) !== reference.recipe.sha256
+        || ![image.indexDigest, image.manifestDigest].includes(reference.image.slice(reference.image.indexOf('@') + 1)))
+        throw new Error('Native managed snapshot differs from its actual original producer');
+    for (const [name, bytes] of files)
+        if (name !== 'artifact.json' && name !== 'declaration.json') {
+            const original = record(originalMap[name]);
+            if (original.bytes !== bytes.length || original.sha256 !== sha(bytes))
+                throw new Error('Native runtime subset is absent from its original receipt map');
+        }
+    files.set('manifest.json', manifestBytes);
+    const declaration = files.get('declaration.json');
+    if (sha(declaration) !== reference.declarationSha256)
+        throw new Error('Native source declaration bytes changed');
+    return { reference, files, aliases: sourceAliases(new TextDecoder('utf-8', { fatal: true }).decode(declaration), reference.release) };
+}
+/** Every parsed source requirement has a disposition; unsupported start behavior refuses before World writes. */
+function sourceAliases(declaration, release) {
+    const service = record(JSON.parse(declaration));
+    // annotated on the name, so each refuse() narrows what follows it (TypeScript's assertion-call rule)
+    const refuse = (field) => { throw new Error(`native MariaDB ${release} provider-start-input gap: ${field}`); };
+    const allowed = ['name', 'image', 'build', 'command', 'entrypoint', 'environment', 'envFiles', 'volumes', 'healthcheck', 'workingDir', 'hostname',
+        'capAdd', 'capDrop', 'privileged', 'user', 'secrets', 'networkMode', 'limits', 'develop', 'ports', 'expose', 'dependsOn', 'hostNames', 'profiles',
+        'ignored', 'connectionBindings', 'environmentInherited'];
+    for (const key of Object.keys(service))
+        if (!allowed.includes(key))
+            refuse(key);
+    for (const key of ['build', 'command', 'entrypoint', 'healthcheck', 'workingDir', 'hostname', 'user', 'networkMode', 'develop', 'connectionBindings'])
+        if (service[key] !== undefined)
+            refuse(key);
+    if (service.privileged === true)
+        refuse('privileged');
+    for (const key of ['envFiles', 'capAdd', 'capDrop', 'secrets', 'dependsOn', 'profiles', 'ignored', 'environmentInherited']) {
+        if (!Array.isArray(service[key]) && service[key] !== undefined)
+            refuse(key);
+        if (Array.isArray(service[key]) && service[key].length)
+            refuse(key);
+    }
+    if (Object.keys(record(service.limits)).length)
+        refuse('limits');
+    if (!Array.isArray(service.volumes) || service.volumes.length > 1)
+        refuse('volumes');
+    for (const item of service.volumes) {
+        const mount = record(item);
+        if (!['named', 'anonymous'].includes(String(mount.kind)) || mount.target !== '/var/lib/mysql' || mount.readOnly !== false)
+            refuse('volume');
+    }
+    for (const key of ['ports', 'expose']) {
+        if (!Array.isArray(service[key]))
+            refuse(key);
+        for (const value of service[key])
+            if (key === 'expose' ? value !== 3306 : record(value).container !== 3306 || record(value).protocol !== 'tcp')
+                refuse(key);
+    }
+    const env = record(service.environment), aliases = [];
+    const values = new Map();
+    for (const [name, value] of Object.entries(env)) {
+        const match = /^(MYSQL|MARIADB)_(DATABASE|USER|PASSWORD|ROOT_PASSWORD)$/u.exec(name);
+        if (!match || typeof value !== 'string' || !value || value.includes('\0'))
+            refuse(name);
+        const field = match[2];
+        if (values.has(field) && values.get(field) !== value)
+            refuse('conflicting credential aliases: ' + field);
+        values.set(field, value);
+        if (match[1] === 'MARIADB')
+            aliases.push(name);
+    }
+    return aliases;
+}
+/** Only World init writes its configuration tree, using the exact bytes it reverified itself. */
+export function copyNativeServerInputs(parent, reference, world) {
+    const snapshot = readNativeServerInputs(parent, reference);
+    const directory = `native-inputs/${reference.receiptSha256}/${reference.declarationSha256}`;
+    const root = join(world, directory);
+    const collection = join(world, 'native-inputs');
+    try {
+        const stat = lstatSync(collection);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('Native World input collection is not owned');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    let exists = true;
+    try {
+        lstatSync(root);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        exists = false;
+    }
+    if (exists)
+        readNativeServerInputs(world, { ...reference, directory });
+    else {
+        mkdirSync(collection, { recursive: true, mode: 0o700 });
+        const producerDirectory = dirname(root);
+        try {
+            const stat = lstatSync(producerDirectory);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error('Native World producer collection is not owned');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            mkdirSync(producerDirectory, { mode: 0o700 });
+        }
+        const staging = root + '.' + randomUUID() + '.partial';
+        mkdirSync(staging, { mode: 0o700 });
+        for (const [name, bytes] of snapshot.files) {
+            const file = join(staging, name);
+            mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+            writeFileSync(file, bytes, { flag: 'wx', mode: 0o400 });
+        }
+        renameSync(staging, root);
+    }
+    // This subset does not pretend the original map's archives/dependency outputs were copied into the World.
+    return nativeServerRuntimeReference(reference);
+}

package/dist/src/origin.js

@@ -55,7 +55,7 @@ export async function fetchFromOrigin(name, options) {
             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');
-        });
+        }, { operation: 'origin fetch' });
     }
     for (const service of services) {
         const controlRoot = join(instance.dirs.data, service);
@@ -90,7 +90,7 @@ export async function fetchFromOrigin(name, options) {
                 const pointer = selected?.origin ?? selected?.parent;
                 appended[service] = Math.max(0, parentLength - before);
                 behind[service] = pointer ? Math.max(0, parentLength - pointer.position) || (pointer.view === head.view ? 0 : 1) : 0;
-            });
+            }, { operation: 'origin fetch' });
             continue;
         }
         // Download one immutable view, then publish its complete cache head. No mixed pages.
@@ -133,7 +133,7 @@ export async function fetchFromOrigin(name, options) {
             const pointer = selected?.origin ?? selected?.parent;
             // Changed same-length snapshots are still drift; offsets are scoped to a view.
             behind[service] = pointer ? Math.max(0, entries.length - pointer.position) || (pointer.remoteView === first.view ? 0 : 1) : 0;
-        });
+        }, { operation: 'origin fetch' });
     }
     saveWorldInstance({ ...instance, origin: { ...origin, ...(options.full ? { clonedAt: at_ } : instance.origin?.clonedAt ? { clonedAt: instance.origin.clonedAt } : {}), fetchedAt: at_ } });
     // a clone names its remote where `volter remote add` does (world.json, as git config holds a remote): one record of

package/dist/src/original-inputs.d.ts

@@ -0,0 +1,14 @@
+/** Retained original-input custody, separate from the managed service's mutable data. */
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+export type OriginalInputReference = managedOriginalInputs.OriginalInputReference;
+export declare function readOriginalInputSnapshot(parent: string, value: unknown): {
+    reference: OriginalInputReference;
+    root: string;
+    bytes: Uint8Array;
+    snapshot: ReturnType<typeof managedOriginalInputs.readSnapshot>;
+};
+export declare function copyOriginalInputSnapshot(from: string, reference: OriginalInputReference, out: string): OriginalInputReference;
+/** A retained store cannot silently acquire another source declaration on resume. */
+export declare function verifyOriginalInputState(root: string, reference: OriginalInputReference): void;
+export declare function bindOriginalInputState(root: string, reference: OriginalInputReference): void;
+export declare function preflightOriginalInputState(root: string, reference: OriginalInputReference): void;

package/dist/src/original-inputs.js

@@ -0,0 +1,84 @@
+/** Retained original-input custody, separate from the managed service's mutable data. */
+import * as managedOriginalInputs from '@volter/world-core/managed-original-inputs';
+import { randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export function readOriginalInputSnapshot(parent, value) {
+    const reference = managedOriginalInputs.referenceOf(value);
+    let root = resolve(parent);
+    for (const part of reference.root.split('/')) {
+        root = join(root, part);
+        const stat = lstatSync(root);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('Original-input root traverses a host symlink');
+    }
+    const file = join(root, reference.manifest), stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024 * 1024)
+        throw new Error('Invalid original-input manifest file');
+    const bytes = readFileSync(file), objectsDir = join(root, 'objects'), directory = lstatSync(objectsDir);
+    if (!directory.isDirectory() || directory.isSymbolicLink())
+        throw new Error('Invalid original-input objects directory');
+    const snapshot = managedOriginalInputs.readSnapshot(bytes, reference.sha256, (path, size) => {
+        const file = join(root, path), stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== size)
+            throw new Error('Original-input object differs');
+        return readFileSync(file);
+    });
+    if (snapshot.manifest.inventoryDigest !== reference.inventoryDigest || readdirSync(root).sort().join('\0') !== 'manifest.json\0objects'
+        || readdirSync(objectsDir).sort().join('\0') !== [...snapshot.objects.keys()].sort().join('\0'))
+        throw new Error('Original-input closed inventory differs');
+    return { reference, root, bytes, snapshot };
+}
+export function copyOriginalInputSnapshot(from, reference, out) {
+    const input = readOriginalInputSnapshot(from, reference);
+    const next = { ...reference, root: `original-inputs/${reference.sha256}` };
+    const parent = join(out, 'original-inputs');
+    if (existsSync(parent) && (!lstatSync(parent).isDirectory() || lstatSync(parent).isSymbolicLink()))
+        throw new Error('Original-input output parent is not an owned directory');
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const destination = join(out, next.root);
+    if (existsSync(destination)) {
+        readOriginalInputSnapshot(out, next);
+        return next;
+    }
+    const staging = destination + '.' + randomUUID() + '.partial';
+    mkdirSync(join(staging, 'objects'), { recursive: true, mode: 0o700 });
+    for (const [sha256, bytes] of input.snapshot.objects)
+        writeFileSync(join(staging, 'objects', sha256), bytes, { mode: 0o400, flag: 'wx' });
+    writeFileSync(join(staging, 'manifest.json'), input.bytes, { mode: 0o400, flag: 'wx' });
+    renameSync(staging, destination);
+    chmodSync(join(destination, "objects"), 0o500);
+    chmodSync(destination, 0o500);
+    return next;
+}
+/** A retained store cannot silently acquire another source declaration on resume. */
+export function verifyOriginalInputState(root, reference) {
+    const marker = join(root, '.original-inputs.json');
+    const stat = lstatSync(marker);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096)
+        throw new Error('Invalid retained original-input state identity');
+    const value = JSON.parse(readFileSync(marker, 'utf8'));
+    if (value.kind !== 'volter.managed-original-input-state' || value.version !== 1 || value.sha256 !== reference.sha256)
+        throw new Error('Retained managed state belongs to different original inputs; use an explicit fresh World or reset');
+}
+export function bindOriginalInputState(root, reference) {
+    const marker = join(root, '.original-inputs.json');
+    if (existsSync(marker)) {
+        verifyOriginalInputState(root, reference);
+        return;
+    }
+    if (readdirSync(root).length)
+        throw new Error('Retained managed state has no original-input identity; a fresh source-bound state is required');
+    writeFileSync(marker, JSON.stringify({ kind: 'volter.managed-original-input-state', version: 1, sha256: reference.sha256 }) + '\n', { flag: 'wx', mode: 0o600 });
+}
+export function preflightOriginalInputState(root, reference) {
+    if (!existsSync(root))
+        return;
+    const directory = lstatSync(root);
+    if (!directory.isDirectory() || directory.isSymbolicLink())
+        throw new Error('Managed original-input state root is not an owned directory');
+    if (existsSync(join(root, '.original-inputs.json')))
+        verifyOriginalInputState(root, reference);
+    else if (readdirSync(root).length)
+        throw new Error('Retained managed state has no original-input identity; a fresh source-bound state is required');
+}

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

@@ -58,9 +58,17 @@ export type PackFacts = {
     serveExport?: string;
     /** The managed-infrastructure kind this pack is the World's backing for (architecture.md, "The descriptor"). */
     managedService?: {
-        kind: 'redis' | 'mongodb';
+        kind: 'redis' | 'mongodb' | 'clickhouse';
         scheme: string;
         note: string;
+        configurationArg?: '--configuration';
+        originalInputs?: {
+            version: 1;
+            manifestArg: '--original-inputs';
+            rootArg: '--original-root';
+            digestArg: '--original-inputs-sha256';
+            paths: string[];
+        };
     };
     /** The World's managed database the runtime binds the twin to at boot (TwinPack.managedDatabase). */
     managedDatabase?: {

package/dist/src/pglite-backing.d.ts

@@ -1,20 +1,7 @@
 import { type WorldDatabasePrepare } from './schema.js';
-export interface InfraService {
-    kind: string;
-    hostPort: number;
-    replicaSet?: string;
-    postgres?: {
-        user: string;
-        database: string;
-        password?: string;
-    };
-}
-/** Read the generated definition's loopback port mappings. MongoDB may explicitly request
- *  one replica-set member through its Compose-compatible command; other mongod options are refused. */
-export declare function parseInfraDefinition(text: string): InfraService[];
-/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
- * whose protocol and loopback port match a declared service belong to this lifecycle. */
-export declare function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string>;
+import type { InfraService } from './infra-definition.js';
+export { parseInfraDefinition, infraConnections } from './infra-definition.js';
+export type { InfraService } from './infra-definition.js';
 export declare function containerlessDataDirectory(kind: string): string | undefined;
 /** How a backing starts its hosts: the environment they run in (the World's service environment, which
  *  the runtime computes for the infrastructure service: admitted host env, the World's env, the service's own, less
@@ -25,6 +12,8 @@ export interface HostLaunch {
     env?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
     note?: (what: string) => void;
+    /** Said once the database's cluster is chosen, placed and its server spawned, before its readiness is waited on (S2 R79). */
+    onPlaced?: () => void;
 }
 /** The kinds this backing cannot serve, or [] when it can serve the world. */
 export declare function unsupportedKinds(services: InfraService[]): string[];
@@ -51,11 +40,41 @@ export declare function preparedCluster(worldConfig: string): {
  * another password takes the same cluster and authenticates against its own. Extensions are loaded into the module
  * at each open, never created in the cluster by the open path.
  */
+/**
+ * A managed store other than the cluster that a step run with the World up may have written (architecture, "A step
+ * may need the World"): where the preparation stages it, beside the cluster, and its stamp.
+ */
+export declare function preparedStore(worldConfig: string, name: string): {
+    directory: string;
+    stamp: string;
+};
+/** The state directory a preparation with the World up runs in, beside the World's own (native-postgres-backing.ts). */
+export declare const PREPARE_STATE_DIRECTORY = ".volter-prepare";
+/** The stamp of a staged store: the migration it was written by. */
+export declare function preparedStoreStamp(migration: PreparedMigration): string;
+/**
+ * Place a staged store where its service serves from, at `up`: only into a place that holds nothing, and only when
+ * its stamp is the migration this World expects (the rule a prepared cluster is taken by). Anything else leaves the
+ * service to start empty, and the note says why.
+ */
+export declare function takePreparedStore(worldConfig: string | undefined, env: NodeJS.ProcessEnv, name: string, target: string): {
+    placed: boolean;
+    note?: string;
+};
 /** A prepared cluster's migration, as its stamp records it: the step's command and the digest of each of its inputs. */
+/** What a prepared cluster was migrated by: the step's command, its inputs' digests and, for a step run with the
+ *  World up (`with: "world"`), the twins that were up for it, each by its version. */
 export interface PreparedMigration {
     command: string[];
     inputs: Record<string, string>;
+    world?: Record<string, string>;
 }
+/**
+ * The twins a step declared `with: "world"` runs beside, each by the version the World names: part of what the
+ * cluster was migrated with, so a World whose twins moved does not take a cluster another set of them wrote into.
+ * Read from the document itself, in id order.
+ */
+export declare function preparedWorldServices(worldConfig: string): Record<string, string>;
 /**
  * The SHA-256 of each of a migration step's inputs, under its cwd in the app's tree: a file's bytes; a directory's
  * sorted relative paths, each with its type, its mode and its bytes (a link, its target). What the image build records
@@ -64,6 +83,8 @@ export interface PreparedMigration {
 export declare function migrationInputDigests(cwd: string, inputs: readonly string[]): Record<string, string>;
 /** The World's declared migration step for its prepared database, if any (runtime.database.prepare). */
 export declare function databasePrepareOf(worldConfig: string): WorldDatabasePrepare | undefined;
+/** `NAME=value` lines (an image's environment, VOLTER_WORLD_APP_ENV), as an environment. */
+export declare function environmentFile(path: string): Record<string, string>;
 /**
  * The World's declared step (runtime.database.prepare) run once against a prepared cluster its backing is serving on
  * the World's port: the declared command in the app's tree, with the image's environment and the World's values over
@@ -81,6 +102,8 @@ export declare function databasePrepareOf(worldConfig: string): WorldDatabasePre
 export declare function keepFailureEvidence(name: string, evidence: string | {
     file: string;
 }, env: NodeJS.ProcessEnv): string;
+/** A package script's own path: each `node_modules/.bin` from the working directory up to the application's root. */
+export declare function packageScriptPath(cwd: string, appRoot: string): string[];
 export declare function runDatabasePrepare(step: WorldDatabasePrepare, worldConfig: string, launch: HostLaunch): Promise<PreparedMigration>;
 /** Run the host's open path once into the World's prepared directory; replaces an earlier preparation. */
 export declare function pglitePrepare(service: InfraService, worldConfig: string, launch?: HostLaunch): Promise<string>;
@@ -125,8 +148,9 @@ export declare const DEVELOPMENT_MIGRATION_NOTICE = "development World: its data
 export declare function takePreparedCluster(prepared: {
     directory: string;
     stamp: string;
-}, expected: string | ((stamp: string) => boolean), serviceData: string, mismatch: string, migration?: PreparedMigration): {
+}, expected: string | ((stamp: string) => boolean), serviceData: string, mismatch: string, migration?: PreparedMigration, copy?: (from: string, to: string) => void): {
     placed: boolean;
+    copied?: boolean;
     note?: string;
 };
 export declare function pgliteUp(services: InfraService[], dataDir: string, launch?: HostLaunch): Promise<void>;