@volter/world-runtime 3.0.162 → 3.0.164

package/src/native-server-inputs.ts

@@ -0,0 +1,169 @@
+// 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, type NativeMariaDBReference } from './mariadb-supplier.ts';
+
+export interface NativeServerInputs extends NativeMariaDBReference {
+  image: string;
+  declarationSha256: string;
+  snapshotSha256: string;
+}
+const sha = (value: Uint8Array): string => createHash('sha256').update(value).digest('hex');
+const hex = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+const record = (value: unknown): Record<string, unknown> => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Native managed inputs need object metadata');
+  return value as Record<string, unknown>;
+};
+const regular = (path: string): Buffer => {
+  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: string, name: string): string => {
+  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: unknown): NativeServerInputs {
+  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: NativeServerInputs): NativeMariaDBReference {
+  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: string, value: unknown): { reference: NativeServerInputs; files: ReadonlyMap<string, Buffer>; aliases: string[] } {
+  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<string, Buffer>();
+  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: string[] = [];
+  const walk = (directory: string): void => {
+    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: string, release: string): string[] {
+  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: string) => never = (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: string[] = [];
+  const values = new Map<string, string>();
+  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 as string);
+    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: string, reference: NativeServerInputs, world: string): NativeMariaDBReference {
+  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 as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+  let exists = true;
+  try { lstatSync(root); } catch (error) { if ((error as NodeJS.ErrnoException).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 as NodeJS.ErrnoException).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/src/origin.ts

@@ -62,7 +62,7 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
     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');
-    });
+    }, { operation: 'origin fetch' });
   }
   for (const service of services) {
     const controlRoot = join(instance.dirs.data, service);
@@ -93,7 +93,7 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
       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.
@@ -126,7 +126,7 @@ export async function fetchFromOrigin(name: string, options: FetchOptions): Prom
     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_ } });

package/src/original-inputs.ts

@@ -0,0 +1,72 @@
+/** 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 type OriginalInputReference = managedOriginalInputs.OriginalInputReference;
+
+export function readOriginalInputSnapshot(parent: string, value: unknown): { reference: OriginalInputReference; root: string; bytes: Uint8Array; snapshot: ReturnType<typeof managedOriginalInputs.readSnapshot> } {
+  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: string, reference: OriginalInputReference, out: string): OriginalInputReference {
+  const input = readOriginalInputSnapshot(from, reference);
+  const next: OriginalInputReference = { ...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: string, reference: OriginalInputReference): void {
+  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')) as { kind?: unknown; version?: unknown; sha256?: unknown };
+  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: string, reference: OriginalInputReference): void {
+  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: string, reference: OriginalInputReference): void {
+  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/src/pack-facts.ts

@@ -34,7 +34,7 @@ export type PackFacts = {
    *  `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 };
+  managedService?: { 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?: { kind: 'postgres'; arg: string; note: string };
   /** Listeners the twin opens beside its main port, allocated and recorded by the runtime (TwinPack.sidePorts). */