@volter/world-runtime 3.0.166 → 3.0.167

package/dist/src/managed-api-needs.js

@@ -0,0 +1,312 @@
+/** Needs9 metadata only. Plain CLI init without a live trusted source reader still refuses version9. No I/O, issuer or runtime attachment here. */
+import { referenceOf } from '@volter/world-core/managed-original-inputs';
+import { composeCredentialDoor, isScalarCredentialField } from "./credential-door.js";
+import { goMysqlBindingFields } from "./go-mysql-binding.js";
+import { nativeServerReference } from "./native-server-inputs.js";
+import { assertWorldConfig, isEnvironmentName, worldConfigDocument } from "./schema.js";
+const APPLICATION_REASONS = ['the declared application service', 'builds this Dockerfile', 'the service the stack builds', "runs the project's own image", "the stack's only service runs an image", 'the one service that publishes a port with an image of no family'];
+function object(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new Error(`${label} must be a JSON object`);
+    for (const key of Reflect.ownKeys(value)) {
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (typeof key !== 'string' || !property.enumerable || !Object.hasOwn(property, 'value'))
+            throw new Error(`${label} has a non-JSON property`);
+    }
+    return value;
+}
+function shape(value, required, optional, label) {
+    const row = object(value, label);
+    if (required.some(key => !Object.hasOwn(row, key)) || Object.keys(row).some(key => !required.includes(key) && !optional.includes(key)))
+        throw new Error(`${label} has missing or unknown fields`);
+    return row;
+}
+function list(value, label, read) {
+    if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype)
+        throw new Error(`${label} must be a JSON array`);
+    if (Reflect.ownKeys(value).some(key => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length)))
+        throw new Error(`${label} has an unknown array field`);
+    const result = [];
+    for (let i = 0; i < value.length; i++) {
+        const property = Object.getOwnPropertyDescriptor(value, String(i));
+        if (!property || !property.enumerable || !Object.hasOwn(property, 'value'))
+            throw new Error(`${label}[${i}] is missing or not JSON data`);
+        result.push(read(property.value, `${label}[${i}]`));
+    }
+    return result;
+}
+function text(value, label, empty = false) {
+    if (typeof value !== 'string' || !empty && !value.length || typeof value === 'string' && value.includes('\0'))
+        throw new Error(`${label} must be ${empty ? 'a' : 'a non-empty'} string without NUL`);
+    return value;
+}
+function name(value, label) {
+    if (!isEnvironmentName(value))
+        throw new Error(`${label} must name an environment variable`);
+    return value;
+}
+function service(value, label) {
+    const out = text(value, label);
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(out))
+        throw new Error(`${label} must name a service`);
+    return out;
+}
+function unique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw new Error(`${label} has duplicate names`);
+    return values;
+}
+function names(value, label) { return unique(list(value, label, name), label); }
+function strings(value, label) { return list(value, label, (item, at) => text(item, at, true)); }
+function stringMap(value, label, read = (item, at) => text(item, at, true)) {
+    return Object.fromEntries(Object.entries(object(value, label)).map(([key, item]) => [name(key, label), read(item, `${label}.${key}`)]));
+}
+function port(value, label) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65535)
+        throw new Error(`${label} must be a protocol port`);
+    return value;
+}
+/** Validate every JSON property before copying; neither getters nor toJSON functions execute. */
+function json(value, label, ancestors = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value !== 'object' || value === null || ancestors.has(value))
+        throw new Error(`${label} must be acyclic JSON data`);
+    const next = new Set(ancestors);
+    next.add(value);
+    if (Array.isArray(value))
+        return list(value, label, (item, at) => json(item, at, next));
+    return Object.fromEntries(Object.entries(object(value, label)).map(([key, item]) => [key, json(item, `${label}.${key}`, next)]));
+}
+function equalJson(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((item, i) => equalJson(item, b[i]));
+    const left = Object.keys(a).sort(), right = Object.keys(b).sort();
+    return left.length === right.length && left.every((key, i) => key === right[i] && equalJson(a[key], b[key]));
+}
+function door(value, label, required) {
+    const row = shape(value, required ? ['path', 'body', 'fill', 'required'] : ['path', 'body', 'fill'], [], label);
+    const fill = stringMap(row.fill, `${label}.fill`, (item, at) => text(item, at));
+    const body = object(json(row.body, `${label}.body`), `${label}.body`);
+    const selected = required ? names(row.required, `${label}.required`) : undefined;
+    for (const key of selected ?? [])
+        if (!Object.hasOwn(fill, key) || !isScalarCredentialField(fill[key]))
+            throw new Error(`${label}.required ${key} has no direct scalar field`);
+    return { path: text(row.path, `${label}.path`), body, fill, ...(selected === undefined ? {} : { required: selected }) };
+}
+/** Strict whole metadata shape, preserving common fields. References are metadata, not authenticated files. */
+export function readManagedApiNeeds9(value) {
+    const row = shape(json(value, 'needs9'), ['kind', 'version', 'dockerfile', 'composeFile', 'application', 'needs', 'settings', 'unset', 'said', 'applicationApis'], ['target', 'bare', 'leftOut', 'notTold'], 'needs9');
+    if (row.kind !== 'browser-substrate.stack-needs' || row.version !== 9)
+        throw new Error('needs9 requires its explicit kind and version');
+    const notTold = Object.hasOwn(row, 'notTold') ? text(row.notTold, 'needs9.notTold', true) : undefined;
+    if (notTold)
+        throw new Error('needs9 cannot select an application whose service is not told');
+    const app = shape(row.application, ['service', 'told', 'notInTheImage', 'envFiles'], ['image', 'target'], 'needs9.application');
+    const statedReason = text(app.told, 'needs9.application.told');
+    const told = APPLICATION_REASONS.find(reason => reason === statedReason);
+    if (told === undefined)
+        throw new Error('needs9.application.told is unsupported');
+    const application = { service: service(app.service, 'needs9.application.service'), told,
+        notInTheImage: list(app.notInTheImage, 'needs9.application.notInTheImage', name), envFiles: strings(app.envFiles, 'needs9.application.envFiles'),
+        ...(Object.hasOwn(app, 'image') ? { image: text(app.image, 'needs9.application.image') } : {}),
+        ...(Object.hasOwn(app, 'target') ? { target: text(app.target, 'needs9.application.target') } : {}) };
+    const wired = new Set(), infrastructure = new Set();
+    const claim = (key) => { if (wired.has(key))
+        throw new Error(`needs9 infrastructure name ${key} has conflicting owners`); wired.add(key); };
+    const needs = list(row.needs, 'needs9.needs', (value, at) => {
+        const item = shape(value, ['service', 'supplier', 'names'], ['image', 'builds', 'family', 'originalInputs', 'nativeServerInputs', 'ports', 'portTargets', 'components'], at);
+        const id = service(item.service, `${at}.service`);
+        if (id === application.service || infrastructure.has(id))
+            throw new Error(`${at}.service is duplicate or the active application`);
+        infrastructure.add(id);
+        const supplier = item.supplier;
+        if (supplier !== 'a World' && supplier !== 'named by a catalog family' && supplier !== 'nobody' && supplier !== "the project's own build")
+            throw new Error(`${at}.supplier is unsupported`);
+        const bindings = list(item.names, `${at}.names`, (value, at) => {
+            const field = shape(value, ['name'], ['scheme', 'query', 'withPort', 'containerPort', 'dsnFormat', 'endpoint', 'dsnPrefix', 'dsnProtocol'], at);
+            const key = name(field.name, `${at}.name`);
+            claim(key);
+            if (Object.hasOwn(field, 'scheme') && !/^[a-z][a-z0-9+.-]*$/i.test(text(field.scheme, `${at}.scheme`)))
+                throw new Error(`${at}.scheme is unsupported`);
+            if (Object.hasOwn(field, 'withPort') && field.withPort !== true)
+                throw new Error(`${at}.withPort must be true when present`);
+            const typed = goMysqlBindingFields(field, key, 3306);
+            return { name: key, ...typed,
+                ...(Object.hasOwn(field, 'scheme') ? { scheme: text(field.scheme, `${at}.scheme`) } : {}),
+                ...(Object.hasOwn(field, 'query') ? { query: text(field.query, `${at}.query`, true) } : {}),
+                ...(Object.hasOwn(field, 'withPort') ? { withPort: true } : {}),
+                ...(Object.hasOwn(field, 'containerPort') ? { containerPort: port(field.containerPort, `${at}.containerPort`) } : {}) };
+        });
+        const ports = Object.hasOwn(item, 'ports') ? names(item.ports, `${at}.ports`) : undefined;
+        for (const key of ports ?? [])
+            claim(key);
+        const portTargets = Object.hasOwn(item, 'portTargets') ? Object.fromEntries(Object.entries(object(item.portTargets, `${at}.portTargets`)).map(([key, value]) => {
+            name(key, `${at}.portTargets`);
+            if (!ports?.includes(key))
+                throw new Error(`${at}.portTargets ${key} has no declared split port`);
+            return [key, port(value, `${at}.portTargets.${key}`)];
+        })) : undefined;
+        const components = Object.hasOwn(item, 'components') ? list(item.components, `${at}.components`, (value, at) => {
+            const part = shape(value, ['name', 'component'], [], at), key = name(part.name, `${at}.name`);
+            claim(key);
+            const component = part.component;
+            if (component !== 'database' && component !== 'user' && component !== 'password')
+                throw new Error(`${at}.component is unsupported`);
+            return { name: key, component };
+        }) : undefined;
+        return { service: id, supplier, names: bindings,
+            ...(Object.hasOwn(item, 'image') ? { image: text(item.image, `${at}.image`) } : {}),
+            ...(Object.hasOwn(item, 'builds') ? { builds: text(item.builds, `${at}.builds`) } : {}),
+            ...(Object.hasOwn(item, 'family') ? { family: text(item.family, `${at}.family`) } : {}),
+            ...(Object.hasOwn(item, 'originalInputs') ? { originalInputs: referenceOf(item.originalInputs) } : {}),
+            ...(Object.hasOwn(item, 'nativeServerInputs') ? { nativeServerInputs: nativeServerReference(item.nativeServerInputs) } : {}),
+            ...(ports === undefined ? {} : { ports }), ...(portTargets === undefined ? {} : { portTargets }), ...(components === undefined ? {} : { components }) };
+    });
+    const selectionKeys = new Set(), selectedNames = new Set();
+    const applicationApis = list(row.applicationApis, 'needs9.applicationApis', (value, at) => {
+        const item = shape(value, ['service', 'vendor', 'api', 'endpoints', 'credentials', 'cliRedirect', 'issues'], [], at);
+        if (item.service !== application.service || item.vendor !== 'aws' || item.api !== 's3')
+            throw new Error(`${at} must select this active application and the supported explicit vendor/API`);
+        const key = `${item.service}/aws/s3`;
+        if (selectionKeys.has(key))
+            throw new Error(`${at} duplicates an API selection`);
+        selectionKeys.add(key);
+        const endpoints = names(item.endpoints, `${at}.endpoints`), credentials = stringMap(item.credentials, `${at}.credentials`, name);
+        if (!endpoints.length && !Object.keys(credentials).length)
+            throw new Error(`${at} has no endpoint or credential consumer`);
+        for (const key of [...endpoints, ...Object.keys(credentials)]) {
+            if (selectedNames.has(key) || wired.has(key))
+                throw new Error(`${at} name ${key} has conflicting endpoint, credential or infrastructure ownership`);
+            selectedNames.add(key);
+        }
+        const redirect = stringMap(item.cliRedirect, `${at}.cliRedirect`);
+        if (Object.keys(redirect).length !== endpoints.length || Object.keys(redirect).some(key => !endpoints.includes(key) || redirect[key] !== '${url}'))
+            throw new Error(`${at}.cliRedirect must carry exactly the declared origin names`);
+        const issues = door(item.issues, `${at}.issues`, true);
+        const required = issues.required;
+        if (required.length !== Object.keys(credentials).length || required.some(key => !Object.hasOwn(credentials, key)))
+            throw new Error(`${at}.issues.required must retain every declared credential alias, including canonical names`);
+        return { service: application.service, vendor: 'aws', api: 's3', endpoints, credentials,
+            cliRedirect: Object.fromEntries(endpoints.map(key => [key, '${url}'])), issues: { ...issues, required } };
+    });
+    if (!applicationApis.length)
+        throw new Error('needs9 requires a consumed explicit API selection');
+    const leftOut = Object.hasOwn(row, 'leftOut') ? list(row.leftOut, 'needs9.leftOut', (value, at) => {
+        const item = shape(value, ['what', 'kind', 'why', 'wouldHaveBeen'], ['service', 'pointing'], at);
+        return { what: text(item.what, `${at}.what`), kind: text(item.kind, `${at}.kind`), why: text(item.why, `${at}.why`), wouldHaveBeen: text(item.wouldHaveBeen, `${at}.wouldHaveBeen`),
+            ...(Object.hasOwn(item, 'service') ? { service: service(item.service, `${at}.service`) } : {}),
+            ...(Object.hasOwn(item, 'pointing') ? { pointing: list(item.pointing, `${at}.pointing`, (value, at) => {
+                    const part = shape(value, ['service', 'variable'], [], at);
+                    return { service: service(part.service, `${at}.service`), variable: name(part.variable, `${at}.variable`) };
+                }) } : {}) };
+    }) : undefined;
+    const unset = Object.fromEntries(Object.entries(object(row.unset, 'needs9.unset')).map(([key, value]) => [name(key, 'needs9.unset'), list(value, `needs9.unset.${key}`, name)]));
+    return { kind: 'browser-substrate.stack-needs', version: 9, dockerfile: text(row.dockerfile, 'needs9.dockerfile', true), composeFile: text(row.composeFile, 'needs9.composeFile'), application, needs,
+        settings: stringMap(row.settings, 'needs9.settings'), unset, said: strings(row.said, 'needs9.said'), applicationApis,
+        ...(Object.hasOwn(row, 'target') ? { target: text(row.target, 'needs9.target') } : {}),
+        ...(Object.hasOwn(row, 'bare') ? { bare: list(row.bare, 'needs9.bare', name) } : {}), ...(notTold === undefined ? {} : { notTold }), ...(leftOut === undefined ? {} : { leftOut }) };
+}
+/** Data from a trusted caller's actual source reading; this validates shape, not custody. */
+export function readManagedApiApplication(value) {
+    const row = shape(json(value, 'needs9 source application'), ['service', 'environment', 'inheritedNames'], [], 'needs9 source application');
+    return { service: service(row.service, 'needs9 source application service'),
+        environment: stringMap(row.environment, 'needs9 source application environment'),
+        inheritedNames: names(row.inheritedNames, 'needs9 source inherited names') };
+}
+/** Caller prerequisites: authenticated immutable source/full correspondence, supplied package/current descriptor,
+ * and deliberate owner selection. This metadata composition neither proves those prerequisites nor writes a World. */
+export function composeManagedApiNeeds9(input) {
+    const needs = readManagedApiNeeds9(input.document);
+    const rawWorld = object(json(input.world, 'needs9 World'), 'needs9 World');
+    if (!Object.hasOwn(rawWorld, 'schemaVersion'))
+        throw new Error('needs9 composition requires an explicit format2 World');
+    const config = assertWorldConfig(rawWorld, 'needs9 World');
+    if (config.manifestVersion !== 2 || input.application.service !== needs.application.service)
+        throw new Error('needs9 composition requires this active application and format2 World');
+    const sourceEnvironment = stringMap(input.application.environment, 'needs9 source application environment');
+    const declared = new Set([...Object.keys(sourceEnvironment), ...names(input.application.inheritedNames, 'needs9 source inherited names')]);
+    const bindings = new Map();
+    for (const owner of list(input.owners, 'needs9 owners', (value, at) => shape(value, ['vendor', 'api', 'serviceId', 'currentDoor'], [], at))) {
+        if (owner.vendor !== 'aws' || owner.api !== 's3' || bindings.has('aws/s3'))
+            throw new Error('needs9 owner is unsupported or duplicate');
+        const id = service(owner.serviceId, 'needs9 selected twin owner'), actual = config.services.find(entry => entry.id === id);
+        if (!actual || actual.type !== 'twin')
+            throw new Error('needs9 actual selected owner is absent or not a twin');
+        bindings.set('aws/s3', { serviceId: id, current: door(owner.currentDoor, 'needs9 current supplied descriptor', false) });
+    }
+    const env = new Map(Object.entries(config.env ?? {})), changed = new Map(config.services.map(entry => [entry.id, entry]));
+    const consumed = new Set();
+    for (const row of needs.applicationApis) {
+        const key = `${row.vendor}/${row.api}`, binding = bindings.get(key);
+        if (!binding)
+            throw new Error(`needs9 selection ${key} has no deliberately selected actual owner`);
+        consumed.add(key);
+        const current = binding.current, actual = changed.get(binding.serviceId);
+        // Validate all saved canonical mappings and aliases before a current field can replace one.
+        const refreshed = composeCredentialDoor(actual.issues, current, actual.id);
+        if (row.issues.path !== current.path || !equalJson(json(row.issues.body, 'needs9 declared door body'), json(current.body, 'needs9 current door body')))
+            throw new Error('needs9 declared path/body differs from the current supplied descriptor');
+        const expected = new Map(Object.entries(current.fill));
+        for (const [alias, canonical] of Object.entries(row.credentials)) {
+            if (!declared.has(alias) || !Object.hasOwn(current.fill, canonical) || !isScalarCredentialField(current.fill[canonical]))
+                throw new Error(`needs9 alias ${alias} has no declared consumer or current canonical scalar field`);
+            const field = current.fill[canonical];
+            if (expected.has(alias) && expected.get(alias) !== field)
+                throw new Error(`needs9 alias ${alias} conflicts with a canonical binding`);
+            if (Object.hasOwn(actual.issues?.fill ?? {}, alias) && actual.issues?.fill[alias] !== field)
+                throw new Error(`needs9 alias ${alias} conflicts with its saved binding`);
+            expected.set(alias, field);
+            const request = `$issue:${actual.id}`, previous = env.get(alias);
+            if (previous !== undefined && previous !== request && previous !== '$mint')
+                throw new Error(`needs9 alias ${alias} conflicts with the global pending owner`);
+            env.set(alias, request);
+        }
+        if (!equalJson(json(row.issues.fill, 'needs9 declared fill'), json(Object.fromEntries(expected), 'needs9 expected fill')))
+            throw new Error('needs9 fill must carry exactly the canonical fields and declared aliases');
+        const redirects = new Map(Object.entries(actual.cliRedirect ?? {}));
+        for (const endpoint of row.endpoints) {
+            if (!declared.has(endpoint))
+                throw new Error(`needs9 endpoint ${endpoint} has no source-declared consumer`);
+            if (expected.has(endpoint))
+                throw new Error(`needs9 endpoint ${endpoint} conflicts with a current canonical credential binding`);
+            const value = Object.hasOwn(sourceEnvironment, endpoint) ? sourceEnvironment[endpoint] : undefined;
+            if (value !== undefined && value !== '') {
+                let origin;
+                try {
+                    origin = new URL(value);
+                }
+                catch {
+                    throw new Error(`needs9 endpoint ${endpoint} has no origin-only HTTP contract`);
+                }
+                if (!/^https?:\/\/[^/?#]+\/?$/i.test(value) || !['http:', 'https:'].includes(origin.protocol) || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash)
+                    throw new Error(`needs9 endpoint ${endpoint} has no origin-only HTTP contract`);
+            }
+            for (const other of changed.values()) {
+                if (Object.hasOwn(other.env ?? {}, endpoint) || Object.hasOwn(other.issues?.fill ?? {}, endpoint) || other.injectEnv === endpoint
+                    || Object.hasOwn(other.injectEnvTemplates ?? {}, endpoint) || other.external?.discover?.some(item => item.as === endpoint)
+                    || Object.hasOwn(other.cliRedirect ?? {}, endpoint) && (other.id !== actual.id || other.cliRedirect?.[endpoint] !== '${url}'))
+                    throw new Error(`needs9 endpoint ${endpoint} conflicts with service ${other.id}`);
+            }
+            redirects.set(endpoint, '${url}');
+        }
+        const saved = { path: current.path, body: current.body,
+            fill: Object.fromEntries([...Object.entries(refreshed.fill), ...expected]),
+            required: [...new Set([...(refreshed.required ?? []), ...row.issues.required])] };
+        const issues = composeCredentialDoor(saved, current, actual.id);
+        changed.set(actual.id, { ...actual, issues, ...(redirects.size ? { cliRedirect: Object.fromEntries(redirects) } : {}) });
+    }
+    if (consumed.size !== bindings.size)
+        throw new Error('needs9 has an unconsumed actual owner selection');
+    const proposed = { ...config, env: Object.fromEntries(env), services: config.services.map(entry => changed.get(entry.id)) };
+    const manifest = worldConfigDocument(proposed);
+    assertWorldConfig(manifest, 'needs9 proposed World');
+    return { needs, manifest };
+}

package/dist/src/managed-api-source.d.ts

@@ -0,0 +1,24 @@
+import { type ManagedApiApplication, type ManagedApiNeeds9 } from './managed-api-needs.js';
+/** Interface compatibility only. The caller separately authenticates the installed export/package closure. */
+export declare const MANAGED_API_SOURCE_READER_CONTRACT = "volter.managed-api-source-reader.v1";
+export type ManagedApiSourceReading = {
+    application: ManagedApiApplication;
+    identity: string;
+};
+/** Attached by reviewed host code, never from JSON. Each call must freshly authenticate the selected immutable
+ * application, full generated correspondence and supplied package facts against its retained setup identity.
+ * identity hashes that complete proof tuple for equality/cache binding only; it is not an authorization bit. */
+export type ManagedApiSourceReader = (input: {
+    repo: string;
+    needsFile: string;
+    document: ManagedApiNeeds9;
+}) => ManagedApiSourceReading;
+export type ManagedApiSourceSession = {
+    readonly document: ManagedApiNeeds9;
+    readonly application: ManagedApiApplication;
+    readonly identity: string;
+    /** Re-read actual needs bytes and invoke the same live source door before output. */
+    assertCurrent(): void;
+};
+/** No World output. A plain needs file lacks the trusted function and keeps its explicit refusal. */
+export declare function readManagedApiSourceSession(repo: string, needsFile: string, reader: ManagedApiSourceReader | undefined): ManagedApiSourceSession;

package/dist/src/managed-api-source.js

@@ -0,0 +1,59 @@
+/** Live host source-reader seam; metadata or an interface marker grants no source custody. */
+import { readFileSync } from 'node:fs';
+import { readManagedApiApplication, readManagedApiNeeds9 } from "./managed-api-needs.js";
+/** Interface compatibility only. The caller separately authenticates the installed export/package closure. */
+export const MANAGED_API_SOURCE_READER_CONTRACT = 'volter.managed-api-source-reader.v1';
+/** Only validated data copies enter here; no caller object is frozen. */
+function retainJson(value) {
+    const pending = [value];
+    while (pending.length) {
+        const item = pending.pop();
+        if (item === null || typeof item !== 'object' || Object.isFrozen(item))
+            continue;
+        pending.push(...Object.values(item));
+        Object.freeze(item);
+    }
+    return value;
+}
+function reading(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+        || Reflect.ownKeys(value).length !== 2)
+        throw new Error('needs9 source reader returned an invalid shape');
+    const data = (key) => {
+        const property = Object.getOwnPropertyDescriptor(value, key);
+        if (!property || !property.enumerable || !Object.hasOwn(property, 'value'))
+            throw new Error('needs9 source reader returned a missing or non-data field');
+        return property.value;
+    };
+    const identity = data('identity');
+    if (typeof identity !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(identity))
+        throw new Error('needs9 source reader requires its full proof comparison digest');
+    return { application: readManagedApiApplication(data('application')), identity };
+}
+/** No World output. A plain needs file lacks the trusted function and keeps its explicit refusal. */
+export function readManagedApiSourceSession(repo, needsFile, reader) {
+    if (typeof reader !== 'function')
+        throw new Error(`volter init: --needs ${needsFile} version9 requires its separately reviewed live source reader and writer; a needs file alone does not enable it`);
+    const bytes = readFileSync(needsFile), document = retainJson(readManagedApiNeeds9(JSON.parse(bytes.toString('utf8'))));
+    const read = () => {
+        const current = reading(reader({ repo, needsFile,
+            // The host reader receives its own data copy, so it cannot change this session's retained document.
+            document: readManagedApiNeeds9(JSON.parse(bytes.toString('utf8'))) }));
+        if (!readFileSync(needsFile).equals(bytes))
+            throw new Error('needs9 source input changed during its live reading');
+        return current;
+    };
+    const source = read();
+    if (source.application.service !== document.application.service)
+        throw new Error('needs9 source reader returned another active application');
+    const application = retainJson(source.application), identity = source.identity;
+    const applicationBytes = JSON.stringify(application);
+    return Object.freeze({ document, application, identity, assertCurrent() {
+            if (!readFileSync(needsFile).equals(bytes))
+                throw new Error('needs9 source input changed after planning');
+            const current = read();
+            if (current.identity !== identity || JSON.stringify(current.application) !== applicationBytes)
+                throw new Error('needs9 immutable application or complete correspondence changed after planning');
+        } });
+}

package/dist/src/mongodb-backing.js

@@ -1,8 +1,8 @@
 import { connect } from 'node:net';
+import { mongodbCommand } from "./mongodb-command.js";
 const PROTOCOL_QUESTION_MS = 1000;
-/** A refused connection cannot answer MongoDB. Ask that negative question before loading the driver,
- *  whose server selection retries an absent endpoint for the whole protocol question budget.
- *  A TCP acceptance is only permission to ask the original protocol question below. */
+/** A refused connection cannot answer MongoDB: that negative answer is TCP's, taken before a protocol question is
+ *  framed and sent. A TCP acceptance is only permission to ask the original protocol question below. */
 function portConnects(port) {
     return new Promise((resolve) => {
         const socket = connect({ host: '127.0.0.1', port, timeout: PROTOCOL_QUESTION_MS });
@@ -30,37 +30,25 @@ export function mongodbArgv(service, data) {
 export async function mongodbServes(service, pid) {
     if (!(await portConnects(service.hostPort)))
         return false;
-    const { MongoClient } = await import('mongodb');
-    const client = new MongoClient(`mongodb://127.0.0.1:${service.hostPort}`, { directConnection: true, timeoutMS: PROTOCOL_QUESTION_MS, serverSelectionTimeoutMS: PROTOCOL_QUESTION_MS });
     try {
-        await client.connect();
-        const status = await client.db('admin').command({ serverStatus: 1 });
+        const status = await mongodbCommand(service.hostPort, { serverStatus: 1 }, PROTOCOL_QUESTION_MS);
         return Number(status.pid) === pid;
     }
     catch {
         return false;
     }
-    finally {
-        await client.close().catch(() => undefined);
-    }
 }
 /** Whether anything speaking MongoDB's protocol answers on the port at all: a ping answered. */
 async function mongodbAnswers(port) {
     if (!(await portConnects(port)))
         return false;
-    const { MongoClient } = await import('mongodb');
-    const client = new MongoClient(`mongodb://127.0.0.1:${port}`, { directConnection: true, timeoutMS: PROTOCOL_QUESTION_MS, serverSelectionTimeoutMS: PROTOCOL_QUESTION_MS });
     try {
-        await client.connect();
-        await client.db('admin').command({ ping: 1 });
+        await mongodbCommand(port, { ping: 1 }, PROTOCOL_QUESTION_MS);
         return true;
     }
     catch {
         return false;
     }
-    finally {
-        await client.close().catch(() => undefined);
-    }
 }
 /** MongoDB's two questions for a twin that serves the kind (twin-backing.ts): the same ownership question the
  *  vendor's own server is asked above, so a pack that serves the kind answers serverStatus with its process's pid. */
@@ -73,11 +61,8 @@ export const MONGODB_PROTOCOL = {
             return true;
         // PID ownership alone cannot make a standalone listener ready for a replica-set URI. An older pack that
         // ignores the new CLI option must fail this protocol question before the application is given its address.
-        const { MongoClient } = await import('mongodb');
-        const client = new MongoClient(`mongodb://127.0.0.1:${port}`, { directConnection: true,
-            timeoutMS: PROTOCOL_QUESTION_MS, serverSelectionTimeoutMS: PROTOCOL_QUESTION_MS });
         try {
-            const hello = await client.db('admin').command({ hello: 1 });
+            const hello = await mongodbCommand(port, { hello: 1 }, PROTOCOL_QUESTION_MS);
             const self = `127.0.0.1:${port}`;
             return hello.setName === service.replicaSet && hello.isWritablePrimary === true && hello.primary === self
                 && Array.isArray(hello.hosts) && hello.hosts.length === 1 && hello.hosts[0] === self;
@@ -85,49 +70,39 @@ export const MONGODB_PROTOCOL = {
         catch {
             return false;
         }
-        finally {
-            await client.close().catch(() => undefined);
-        }
     },
 };
 /** Ping the server; initialize only an explicitly declared one-member set and await its primary. */
 export async function mongodbReady(service, launch, deadline, initialize = true) {
-    const { MongoClient } = await import('mongodb');
-    // Use the infrastructure lifecycle's remaining readiness budget rather than another fixed limit.
-    const remaining = deadline - Date.now();
-    if (remaining <= 0)
+    // Use the infrastructure lifecycle's remaining readiness budget rather than another fixed limit: each command
+    // has what is left of it when it is asked.
+    if (deadline - Date.now() <= 0)
         throw new Error('World-managed MongoDB readiness deadline elapsed');
-    const client = new MongoClient(`mongodb://127.0.0.1:${service.hostPort}`, {
-        directConnection: true, timeoutMS: remaining,
-    });
+    const admin = (command) => mongodbCommand(service.hostPort, command, deadline - Date.now(), launch.signal);
+    await admin({ ping: 1 });
+    if (!service.replicaSet)
+        return;
+    let config;
     try {
-        await client.connect();
-        const admin = client.db('admin');
-        await admin.command({ ping: 1 });
-        if (!service.replicaSet)
-            return;
-        let config;
-        try {
-            config = (await admin.command({ replSetGetConfig: 1 })).config;
-        }
-        catch (error) {
-            // MongoDB's NotYetInitialized; any other refusal remains its own error.
-            if (error.code !== 94 || !initialize)
-                throw error;
-            config = { _id: service.replicaSet, members: [{ _id: 0, host: `127.0.0.1:${service.hostPort}` }] };
-            await admin.command({ replSetInitiate: config });
-        }
-        if (config._id !== service.replicaSet || config.members?.length !== 1 || config.members[0].host !== `127.0.0.1:${service.hostPort}`) {
-            throw new Error('World-managed MongoDB replica-set name or member address differs from the declared service; refusing reconfiguration');
-        }
-        while (!(await admin.command({ hello: 1 })).isWritablePrimary) {
-            launch.signal?.throwIfAborted();
-            if (Date.now() >= deadline)
-                throw new Error('World-managed MongoDB did not elect its single-node primary before the readiness deadline');
-            await new Promise((resolve) => setTimeout(resolve, 200));
-        }
+        config = (await admin({ replSetGetConfig: 1 })).config;
+    }
+    catch (error) {
+        // MongoDB's NotYetInitialized; any other refusal remains its own error.
+        if (error.code !== 94 || !initialize)
+            throw error;
+        config = { _id: service.replicaSet, members: [{ _id: 0, host: `127.0.0.1:${service.hostPort}` }] };
+        await admin({ replSetInitiate: config });
+    }
+    if (config?._id !== service.replicaSet || config.members?.length !== 1 || config.members[0].host !== `127.0.0.1:${service.hostPort}`) {
+        throw new Error('World-managed MongoDB replica-set name or member address differs from the declared service; refusing reconfiguration');
     }
-    finally {
-        await client.close();
+    while (!(await admin({ hello: 1 })).isWritablePrimary) {
+        launch.signal?.throwIfAborted();
+        if (Date.now() >= deadline)
+            throw new Error('World-managed MongoDB did not elect its single-node primary before the readiness deadline');
+        await new Promise((resolve) => setTimeout(resolve, 200));
+        // A deadline that passed while it waited is the election's, not the next question's empty budget.
+        if (Date.now() >= deadline)
+            throw new Error('World-managed MongoDB did not elect its single-node primary before the readiness deadline');
     }
 }

package/dist/src/mongodb-command.d.ts

@@ -0,0 +1,21 @@
+import { type MongoDocument } from '@volter/world-core/mongodb';
+export type { MongoDocument };
+/** A command the server answered and refused (`ok` not 1), with its own code, as the driver's server error carries it. */
+export declare class MongoCommandError extends Error {
+    readonly code: number | undefined;
+    readonly codeName: string | undefined;
+    constructor(code: number | undefined, codeName: string | undefined, message: string);
+}
+/** A document as BSON: the values the runtime's own commands hold (numbers, bigints, strings, booleans, null,
+ *  documents and arrays). An undefined value is left out, as the driver leaves it; -0 is a double, as it is to BSON. */
+export declare function encodeBson(document: MongoDocument): Buffer;
+/** A BSON document read whole from `bytes` at `start`. Every BSON type is read, so an answer's fields the runtime does
+ *  not use are still walked; a length out of bounds, a boolean other than 0 or 1, text that is not UTF-8, or a document
+ *  that does not end where its length says is refused. An int64 is a number where it is a safe integer, as the driver
+ *  promotes it, and a bigint where it is not. */
+export declare function decodeBson(bytes: Buffer, start?: number, array?: boolean): MongoDocument | unknown[];
+/** One admin command on one loopback connection, answered through the kernel's client: refused where the server says
+ *  it is not ok, where its answer cannot be read (the client checks its request, opcode and length; a document
+ *  sequence in it is joined as the field it names, as the client joins one), where the connection ends or refuses
+ *  first, where `timeoutMs` passes, or where `signal` aborts. */
+export declare function mongodbCommand(port: number, command: MongoDocument, timeoutMs: number, signal?: AbortSignal): Promise<MongoDocument>;