@hypequery/deployment 0.2.0 → 0.4.0

package/dist/data-plane.js

@@ -0,0 +1,200 @@
+import { createProtocolSchemaValueParser, ProtocolSchemaValueError, validateProtocolDeploymentContract, } from '@hypequery/protocol';
+import { resolveDeploymentDataPlaneLimits, } from './data-plane-limits.js';
+export class DeploymentDataPlaneError extends Error {
+    code;
+    path;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentDataPlaneError';
+        this.code = code;
+        this.path = options.path;
+    }
+}
+function dataPlaneError(code, message, cause, path) {
+    return new DeploymentDataPlaneError(code, message, { cause, path });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw dataPlaneError('HQ_DATA_PLANE_ABORTED', 'The data-plane request was aborted.', signal.reason);
+    }
+}
+function frozenRecord(entries) {
+    return Object.freeze(Object.assign(Object.create(null), entries));
+}
+function valueAtPath(input, path) {
+    let value = input;
+    for (const segment of path.split('.')) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)
+            || !Object.hasOwn(value, segment))
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+function sqlParameters(query, input, tenant) {
+    if (query.implementation.kind !== 'compiled-sql')
+        return Object.freeze({});
+    const values = Object.create(null);
+    for (const parameter of query.implementation.parameters) {
+        const value = parameter.source.kind === 'tenant'
+            ? tenant
+            : valueAtPath(input, parameter.source.path);
+        if (value === undefined) {
+            throw dataPlaneError('HQ_DATA_PLANE_INPUT_INVALID', 'A required compiled SQL binding is missing.', undefined, parameter.source.kind === 'input' ? `$.${parameter.source.path}` : '$.tenant');
+        }
+        values[parameter.name] = value;
+    }
+    return frozenRecord(values);
+}
+function routeTable(deployment, limits) {
+    const routes = new Map();
+    for (const query of deployment.queries) {
+        routes.set(`${query.endpoint.method}\0${query.endpoint.path}`, Object.freeze({
+            query,
+            input: createProtocolSchemaValueParser(query.input, { limits }),
+            output: createProtocolSchemaValueParser(query.output, { limits }),
+        }));
+    }
+    return routes;
+}
+function missing(values, actual) {
+    const available = new Set(actual ?? []);
+    return values.filter(value => !available.has(value));
+}
+export function createDeploymentDataPlane(options) {
+    let deployment;
+    try {
+        deployment = validateProtocolDeploymentContract(options.deployment);
+    }
+    catch (error) {
+        throw dataPlaneError('HQ_DATA_PLANE_CONFIGURATION', 'The deployment data plane requires a valid deployment contract.', error);
+    }
+    const limits = resolveDeploymentDataPlaneLimits(options.limits);
+    const routes = routeTable(deployment, limits);
+    const paths = new Set(deployment.queries.map(query => query.endpoint.path));
+    return Object.freeze({
+        async execute(request) {
+            throwIfAborted(request.signal);
+            const route = routes.get(`${request.method}\0${request.path}`);
+            if (!route) {
+                if (paths.has(request.path)) {
+                    throw dataPlaneError('HQ_DATA_PLANE_METHOD_NOT_ALLOWED', 'The deployment route does not support this method.');
+                }
+                throw dataPlaneError('HQ_DATA_PLANE_ROUTE_NOT_FOUND', 'The deployment route was not found.');
+            }
+            const { query } = route;
+            let principal = null;
+            if (query.endpoint.access.kind === 'authenticated' && !options.authenticate) {
+                throw dataPlaneError('HQ_DATA_PLANE_CONFIGURATION', 'An authenticator is required for this deployment route.');
+            }
+            if (options.authenticate
+                && (query.endpoint.access.kind === 'authenticated' || request.credentials !== undefined)) {
+                try {
+                    principal = await options.authenticate({ credentials: request.credentials, request, query });
+                }
+                catch (error) {
+                    throw dataPlaneError('HQ_DATA_PLANE_UNAUTHENTICATED', 'Authentication failed.', error);
+                }
+            }
+            throwIfAborted(request.signal);
+            if (query.endpoint.access.kind === 'authenticated') {
+                if (!principal) {
+                    throw dataPlaneError('HQ_DATA_PLANE_UNAUTHENTICATED', 'Authentication is required.');
+                }
+                if (missing(query.endpoint.access.roles, principal.roles).length > 0
+                    || missing(query.endpoint.access.scopes, principal.scopes).length > 0) {
+                    throw dataPlaneError('HQ_DATA_PLANE_FORBIDDEN', 'The principal lacks required access.');
+                }
+            }
+            let tenant;
+            if (query.endpoint.tenant.kind !== 'not-required') {
+                if (!options.resolveTenant) {
+                    if (query.endpoint.tenant.kind === 'required') {
+                        throw dataPlaneError('HQ_DATA_PLANE_CONFIGURATION', 'A tenant resolver is required for this deployment route.');
+                    }
+                }
+                else {
+                    try {
+                        tenant = await options.resolveTenant({ principal, request, query });
+                    }
+                    catch (error) {
+                        throw dataPlaneError('HQ_DATA_PLANE_FORBIDDEN', 'Tenant resolution failed.', error);
+                    }
+                }
+                if (query.endpoint.tenant.kind === 'required' && (tenant === undefined || tenant === null)) {
+                    throw dataPlaneError('HQ_DATA_PLANE_TENANT_REQUIRED', 'Tenant context is required.');
+                }
+            }
+            throwIfAborted(request.signal);
+            let input;
+            try {
+                input = route.input.parse(request.input);
+            }
+            catch (error) {
+                if (error instanceof ProtocolSchemaValueError) {
+                    throw dataPlaneError('HQ_DATA_PLANE_INPUT_INVALID', 'The request input does not match the deployment schema.', error, error.path);
+                }
+                throw error;
+            }
+            const common = { query, input, principal, tenant, request, signal: request.signal };
+            let output;
+            try {
+                switch (query.implementation.kind) {
+                    case 'semantic-plan':
+                        if (!options.executeSemanticPlan)
+                            throw dataPlaneError('HQ_DATA_PLANE_EXECUTOR_UNAVAILABLE', 'No semantic-plan executor is configured.');
+                        output = await options.executeSemanticPlan({
+                            ...common,
+                            implementation: query.implementation,
+                            deployment,
+                        });
+                        break;
+                    case 'compiled-sql':
+                        if (!options.executeCompiledSql)
+                            throw dataPlaneError('HQ_DATA_PLANE_EXECUTOR_UNAVAILABLE', 'No compiled SQL executor is configured.');
+                        output = await options.executeCompiledSql({
+                            ...common,
+                            implementation: query.implementation,
+                            parameters: sqlParameters(query, input, tenant),
+                        });
+                        break;
+                    case 'runtime-reference':
+                        if (!options.executeRuntimeReference)
+                            throw dataPlaneError('HQ_DATA_PLANE_EXECUTOR_UNAVAILABLE', 'No runtime-reference executor is configured.');
+                        output = await options.executeRuntimeReference({
+                            ...common,
+                            implementation: query.implementation,
+                        });
+                        break;
+                }
+            }
+            catch (error) {
+                if (error instanceof DeploymentDataPlaneError)
+                    throw error;
+                if (request.signal?.aborted) {
+                    throw dataPlaneError('HQ_DATA_PLANE_ABORTED', 'The data-plane request was aborted.', error);
+                }
+                throw dataPlaneError('HQ_DATA_PLANE_EXECUTION_FAILED', 'Deployment query execution failed.', error);
+            }
+            try {
+                output = route.output.parse(output);
+            }
+            catch (error) {
+                if (error instanceof ProtocolSchemaValueError) {
+                    throw dataPlaneError('HQ_DATA_PLANE_OUTPUT_INVALID', 'The query output does not match the deployment schema.', error, error.path);
+                }
+                throw error;
+            }
+            const publicCacheTtlMs = query.endpoint.access.kind === 'public'
+                && query.endpoint.tenant.kind === 'not-required'
+                && principal === null
+                ? query.endpoint.cacheTtlMs
+                : undefined;
+            return Object.freeze({
+                query: query.name,
+                output,
+                ...(publicCacheTtlMs === undefined ? {} : { cacheTtlMs: publicCacheTtlMs }),
+            });
+        },
+    });
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, } from './activation.js';
-export type { DeploymentActivationErrorCode, DeploymentActivationRegistry, DeploymentActivationRelease, DeploymentActivationRecord, DeploymentActivationRequest, DeploymentActivationResult, DeploymentReleaseReader, FileSystemDeploymentActivationRegistryOptions, } from './activation.js';
+export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, validateDeploymentActivationRecord, } from './activation.js';
+export type { DeploymentActivationErrorCode, DeploymentActivationHistoryPage, DeploymentActivationHistoryQuery, DeploymentActivationRegistry, DeploymentActivationRelease, DeploymentActivationRecord, DeploymentActivationRequest, DeploymentActivationResult, DeploymentReleaseReader, FileSystemDeploymentActivationRegistryOptions, } from './activation.js';
 export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
 export type { VerifiedDeploymentBundle } from './bundle.js';
 export { DeploymentIntakeError, } from './errors.js';
@@ -7,7 +7,25 @@ export type { DeploymentIntakeErrorCode } from './errors.js';
 export { createFileSystemDeploymentSubmissionStore, FileSystemDeploymentStoreError, } from './filesystem-store.js';
 export type { FileSystemDeploymentStoreErrorCode, FileSystemDeploymentSubmissionStore, FileSystemDeploymentSubmissionStoreOptions, StoredDeploymentSubmission, } from './filesystem-store.js';
 export { createDeploymentIntake, } from './intake.js';
+export { createDeploymentControlPlaneFetchHandler, createDeploymentControlPlaneNodeHandler, } from './control-plane-adapters.js';
+export type { DeploymentControlPlaneFetchHandler, DeploymentControlPlaneNodeHandler, } from './control-plane-adapters.js';
+export { createDeploymentControlPlane, } from './control-plane.js';
+export type { DeploymentControlPlane, DeploymentControlPlaneAction, DeploymentControlPlaneAuthorizationInput, DeploymentControlPlaneAuthorizer, DeploymentControlPlaneErrorCode, DeploymentControlPlaneOptions, DeploymentControlPlaneRequest, DeploymentControlPlaneResponse, } from './control-plane.js';
+export { DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS, resolveDeploymentControlPlaneLimits, } from './control-plane-limits.js';
+export type { DeploymentControlPlaneLimits } from './control-plane-limits.js';
 export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';
 export type { DeploymentIntakeLimits } from './limits.js';
+export { createNodeWorkerDeploymentRuntimeFactory, NodeDeploymentRuntimeError, } from './node-runtime-factory.js';
+export type { NodeDeploymentRuntimeErrorCode, NodeDeploymentRuntimeFactoryOptions, } from './node-runtime-factory.js';
+export { createDeploymentRuntimeMaterializer, DeploymentRuntimeMaterializationError, } from './runtime-materialization.js';
+export type { DeploymentRuntimeArtifactSnapshot, DeploymentRuntimeMaterializationErrorCode, DeploymentRuntimeMaterializer, DeploymentRuntimeMaterializerOptions, DeploymentRuntimeQueryBinding, DeploymentRuntimeRelease, DeploymentRuntimeReleaseReader, DeploymentRuntimeSnapshot, } from './runtime-materialization.js';
+export { createDeploymentRuntimeSupervisor, DeploymentRuntimeSupervisorError, } from './runtime-supervisor.js';
+export type { DeploymentRuntimeFactory, DeploymentRuntimeInstance, DeploymentRuntimeInstanceInvocation, DeploymentRuntimeInvocation, DeploymentRuntimeReconcileResult, DeploymentRuntimeStatus, DeploymentRuntimeSupervisor, DeploymentRuntimeSupervisorErrorCode, DeploymentRuntimeSupervisorOptions, } from './runtime-supervisor.js';
 export type { DeploymentAuthenticationInput, DeploymentAuthenticator, DeploymentAuthorizationInput, DeploymentAuthorizer, DeploymentIntake, DeploymentIntakeOptions, DeploymentIntakeRequest, DeploymentIntakeResponse, DeploymentSubmissionResponse, DeploymentSubmissionStore, VerifiedDeploymentSubmission, } from './types.js';
+export { createDeploymentDataPlane, DeploymentDataPlaneError, } from './data-plane.js';
+export type { DeploymentCompiledSqlExecutionInput, DeploymentDataPlane, DeploymentDataPlaneAuthenticationInput, DeploymentDataPlaneErrorCode, DeploymentDataPlaneExecutionInput, DeploymentDataPlaneOptions, DeploymentDataPlanePrincipal, DeploymentDataPlaneRequest, DeploymentDataPlaneResult, DeploymentDataPlaneTenantInput, DeploymentRuntimeReferenceExecutionInput, DeploymentSemanticPlanExecutionInput, } from './data-plane.js';
+export { DEFAULT_DEPLOYMENT_DATA_PLANE_LIMITS, resolveDeploymentDataPlaneLimits, } from './data-plane-limits.js';
+export type { DeploymentDataPlaneLimits } from './data-plane-limits.js';
+export { createDeploymentRuntimeSupervisorExecutor } from './data-plane-runtime.js';
+export type { DeploymentRuntimeSupervisorExecutorOptions } from './data-plane-runtime.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4CAA4C,EAC5C,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,6BAA6B,EAC7B,4BAA4B,EAC5B,2BAA2B,EAC3B,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,EAC1B,uBAAuB,EACvB,6CAA6C,GAC9C,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,yCAAyC,EACzC,8BAA8B,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,kCAAkC,EAClC,mCAAmC,EACnC,0CAA0C,EAC1C,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,15 @@
-export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, } from './activation.js';
+export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, validateDeploymentActivationRecord, } from './activation.js';
 export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
 export { DeploymentIntakeError, } from './errors.js';
 export { createFileSystemDeploymentSubmissionStore, FileSystemDeploymentStoreError, } from './filesystem-store.js';
 export { createDeploymentIntake, } from './intake.js';
+export { createDeploymentControlPlaneFetchHandler, createDeploymentControlPlaneNodeHandler, } from './control-plane-adapters.js';
+export { createDeploymentControlPlane, } from './control-plane.js';
+export { DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS, resolveDeploymentControlPlaneLimits, } from './control-plane-limits.js';
 export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';
+export { createNodeWorkerDeploymentRuntimeFactory, NodeDeploymentRuntimeError, } from './node-runtime-factory.js';
+export { createDeploymentRuntimeMaterializer, DeploymentRuntimeMaterializationError, } from './runtime-materialization.js';
+export { createDeploymentRuntimeSupervisor, DeploymentRuntimeSupervisorError, } from './runtime-supervisor.js';
+export { createDeploymentDataPlane, DeploymentDataPlaneError, } from './data-plane.js';
+export { DEFAULT_DEPLOYMENT_DATA_PLANE_LIMITS, resolveDeploymentDataPlaneLimits, } from './data-plane-limits.js';
+export { createDeploymentRuntimeSupervisorExecutor } from './data-plane-runtime.js';

package/dist/node-runtime-factory.d.ts

@@ -0,0 +1,16 @@
+import type { DeploymentRuntimeFactory } from './runtime-supervisor.js';
+export type NodeDeploymentRuntimeErrorCode = 'HQ_NODE_RUNTIME_CONFIGURATION' | 'HQ_NODE_RUNTIME_UNSUPPORTED_ARTIFACT' | 'HQ_NODE_RUNTIME_INVALID_ARTIFACT' | 'HQ_NODE_RUNTIME_START_FAILED' | 'HQ_NODE_RUNTIME_WORKER_EXITED' | 'HQ_NODE_RUNTIME_INVOCATION_FAILED' | 'HQ_NODE_RUNTIME_ABORTED' | 'HQ_NODE_RUNTIME_CLOSED';
+export declare class NodeDeploymentRuntimeError extends Error {
+    readonly code: NodeDeploymentRuntimeErrorCode;
+    constructor(code: NodeDeploymentRuntimeErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface NodeDeploymentRuntimeFactoryOptions {
+    readonly temporaryDirectory?: string;
+    /** Worker import deadline from 1 through 300,000 milliseconds. */
+    readonly startupTimeoutMs?: number;
+    readonly onCleanupError?: (error: unknown, directory: string) => void;
+}
+export declare function createNodeWorkerDeploymentRuntimeFactory(options?: NodeDeploymentRuntimeFactoryOptions): DeploymentRuntimeFactory;
+//# sourceMappingURL=node-runtime-factory.d.ts.map

package/dist/node-runtime-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-runtime-factory.d.ts","sourceRoot":"","sources":["../src/node-runtime-factory.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,wBAAwB,EAGzB,MAAM,yBAAyB,CAAC;AA+CjC,MAAM,MAAM,8BAA8B,GACtC,+BAA+B,GAC/B,sCAAsC,GACtC,kCAAkC,GAClC,8BAA8B,GAC9B,+BAA+B,GAC/B,mCAAmC,GACnC,yBAAyB,GACzB,wBAAwB,CAAC;AAE7B,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,8BAA8B,CAAC;gBAG5C,IAAI,EAAE,8BAA8B,EACpC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACvE;AAoSD,wBAAgB,wCAAwC,CACtD,OAAO,GAAE,mCAAwC,GAChD,wBAAwB,CAuB1B"}

package/dist/node-runtime-factory.js

@@ -0,0 +1,274 @@
+import { createHash } from 'node:crypto';
+import { chmod, lstat, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { Worker } from 'node:worker_threads';
+const DEFAULT_STARTUP_TIMEOUT_MS = 30_000;
+const MAX_STARTUP_TIMEOUT_MS = 5 * 60_000;
+const WORKER_SOURCE = [
+    "const { parentPort, workerData } = require('node:worker_threads');",
+    "const { pathToFileURL } = require('node:url');",
+    'const handlers = new Map();',
+    'function errorValue(error) {',
+    "  return { name: error instanceof Error ? error.name : 'Error',",
+    "    message: error instanceof Error ? error.message : String(error) };",
+    '}',
+    'function resolveEntrypoint(module, entrypoint) {',
+    '  let value = module;',
+    "  for (const segment of entrypoint.split('.')) value = value?.[segment];",
+    "  if (typeof value !== 'function') throw new Error(`Runtime entrypoint is unavailable: ${entrypoint}`);",
+    '  return value;',
+    '}',
+    '(async () => {',
+    '  for (const artifact of workerData.artifacts) {',
+    '    const module = await import(pathToFileURL(artifact.path).href);',
+    '    for (const entrypoint of artifact.entrypoints) {',
+    '      handlers.set(entrypoint, resolveEntrypoint(module, entrypoint));',
+    '    }',
+    '  }',
+    "  parentPort.postMessage({ kind: 'ready' });",
+    "  parentPort.on('message', async message => {",
+    "    if (message.kind === 'health') {",
+    "      parentPort.postMessage({ kind: 'result', id: message.id, value: null });",
+    '      return;',
+    '    }',
+    "    if (message.kind !== 'invoke') return;",
+    '    try {',
+    '      const handler = handlers.get(message.entrypoint);',
+    "      if (!handler) throw new Error(`Runtime entrypoint is unavailable: ${message.entrypoint}`);",
+    '      const value = await handler(message.argument);',
+    "      parentPort.postMessage({ kind: 'result', id: message.id, value });",
+    '    } catch (error) {',
+    "      parentPort.postMessage({ kind: 'failure', id: message.id, error: errorValue(error) });",
+    '    }',
+    '  });',
+    '})().catch(error => {',
+    "  parentPort.postMessage({ kind: 'fatal', error: errorValue(error) });",
+    '});',
+].join('\n');
+export class NodeDeploymentRuntimeError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'NodeDeploymentRuntimeError';
+        this.code = code;
+    }
+}
+function nodeRuntimeError(code, message, cause) {
+    return new NodeDeploymentRuntimeError(code, message, { cause });
+}
+function startupTimeout(input) {
+    const value = input ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_STARTUP_TIMEOUT_MS) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_CONFIGURATION', `startupTimeoutMs must be between 1 and ${MAX_STARTUP_TIMEOUT_MS}.`);
+    }
+    return value;
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+async function ensureTemporaryDirectory(input) {
+    const directory = path.resolve(input ?? tmpdir());
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_CONFIGURATION', 'The Node runtime temporary directory must be a regular directory.');
+    }
+    return directory;
+}
+function remoteError(input) {
+    const message = typeof input?.message === 'string'
+        ? input.message.slice(0, 4096)
+        : 'The runtime worker failed without an error message.';
+    const error = new Error(message);
+    if (typeof input?.name === 'string')
+        error.name = input.name.slice(0, 128);
+    return error;
+}
+function workerInstance(worker, directory, ready) {
+    const pending = new Map();
+    let sequence = 0;
+    let closed = false;
+    let closePromise;
+    let terminalError;
+    function failPending(error) {
+        for (const call of pending.values()) {
+            call.cleanup();
+            call.reject(error);
+        }
+        pending.clear();
+    }
+    worker.on('message', (message) => {
+        if ((message.kind !== 'result' && message.kind !== 'failure')
+            || !Number.isSafeInteger(message.id))
+            return;
+        const call = pending.get(message.id);
+        if (!call)
+            return;
+        pending.delete(message.id);
+        call.cleanup();
+        if (message.kind === 'result')
+            call.resolve(message.value);
+        else
+            call.reject(nodeRuntimeError('HQ_NODE_RUNTIME_INVOCATION_FAILED', 'The Node deployment runtime invocation failed.', remoteError(message.error)));
+    });
+    worker.on('error', error => {
+        terminalError = nodeRuntimeError('HQ_NODE_RUNTIME_WORKER_EXITED', 'The Node deployment runtime worker failed.', error);
+        failPending(terminalError);
+    });
+    worker.on('exit', code => {
+        if (!closed) {
+            terminalError = nodeRuntimeError('HQ_NODE_RUNTIME_WORKER_EXITED', `The Node deployment runtime worker exited unexpectedly with code ${code}.`);
+            failPending(terminalError);
+        }
+    });
+    function call(kind, payload, signal) {
+        if (closed || terminalError) {
+            return Promise.reject(terminalError ?? nodeRuntimeError('HQ_NODE_RUNTIME_CLOSED', 'The Node deployment runtime worker is closed.'));
+        }
+        if (signal?.aborted) {
+            return Promise.reject(nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'The Node deployment runtime invocation was aborted.', signal.reason));
+        }
+        const id = sequence;
+        sequence += 1;
+        return new Promise((resolve, reject) => {
+            const observeAbort = kind === 'health';
+            const abort = () => {
+                pending.delete(id);
+                reject(nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'The Node deployment runtime health check was aborted.', signal?.reason));
+            };
+            const cleanup = () => signal?.removeEventListener('abort', abort);
+            pending.set(id, { resolve, reject, cleanup });
+            if (observeAbort)
+                signal?.addEventListener('abort', abort, { once: true });
+            try {
+                worker.postMessage({ kind, id, ...payload });
+            }
+            catch (error) {
+                pending.delete(id);
+                cleanup();
+                reject(nodeRuntimeError('HQ_NODE_RUNTIME_INVOCATION_FAILED', 'The Node deployment runtime invocation could not be sent.', error));
+            }
+        });
+    }
+    return {
+        ready,
+        async healthCheck({ signal }) {
+            await call('health', {}, signal);
+        },
+        invoke(input) {
+            return call('invoke', {
+                entrypoint: input.binding.entrypoint,
+                argument: input.argument,
+            }, input.signal);
+        },
+        async close() {
+            if (closePromise)
+                return closePromise;
+            closed = true;
+            const error = nodeRuntimeError('HQ_NODE_RUNTIME_CLOSED', 'The Node deployment runtime worker was closed.');
+            failPending(error);
+            closePromise = (async () => {
+                try {
+                    await worker.terminate();
+                }
+                finally {
+                    await rm(directory, { force: true, recursive: true });
+                }
+            })();
+            return closePromise;
+        },
+    };
+}
+async function startWorker(snapshot, directory, timeoutMs, signal) {
+    if (signal?.aborted) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal.reason);
+    }
+    const artifacts = [];
+    for (const artifact of snapshot.artifacts) {
+        if (artifact.runtime !== 'node') {
+            throw nodeRuntimeError('HQ_NODE_RUNTIME_UNSUPPORTED_ARTIFACT', `The Node runtime factory cannot load a ${artifact.runtime} artifact.`);
+        }
+        const bytes = artifact.read();
+        if (bytes.byteLength !== artifact.byteLength || sha256(bytes) !== artifact.artifactSha256) {
+            throw nodeRuntimeError('HQ_NODE_RUNTIME_INVALID_ARTIFACT', 'Materialized Node runtime bytes do not match their identity.');
+        }
+        const artifactPath = path.join(directory, `${artifact.artifactSha256}.mjs`);
+        await writeFile(artifactPath, bytes, { flag: 'wx', mode: 0o600 });
+        artifacts.push(Object.freeze({ path: artifactPath, entrypoints: artifact.entrypoints }));
+    }
+    if (artifacts.length === 0) {
+        throw nodeRuntimeError('HQ_NODE_RUNTIME_UNSUPPORTED_ARTIFACT', 'The deployment snapshot contains no Node runtime artifacts.');
+    }
+    const worker = new Worker(WORKER_SOURCE, {
+        eval: true,
+        workerData: { artifacts },
+    });
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    const timer = setTimeout(() => {
+        rejectReady(nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', 'The Node deployment runtime did not start before its deadline.'));
+    }, timeoutMs);
+    timer.unref();
+    const abort = () => rejectReady(nodeRuntimeError('HQ_NODE_RUNTIME_ABORTED', 'Node runtime startup was aborted.', signal?.reason));
+    signal?.addEventListener('abort', abort, { once: true });
+    const startupMessage = (message) => {
+        if (message.kind === 'ready')
+            resolveReady();
+        if (message.kind === 'fatal')
+            rejectReady(nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', 'The Node deployment runtime could not import its artifacts.', remoteError(message.error)));
+    };
+    const startupError = (error) => rejectReady(nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', 'The Node deployment runtime worker failed during startup.', error));
+    const startupExit = (code) => rejectReady(nodeRuntimeError('HQ_NODE_RUNTIME_START_FAILED', `The Node deployment runtime worker exited during startup with code ${code}.`));
+    worker.on('message', startupMessage);
+    worker.once('error', startupError);
+    worker.once('exit', startupExit);
+    const instance = workerInstance(worker, directory, ready);
+    try {
+        await ready;
+        return instance;
+    }
+    catch (error) {
+        try {
+            await instance.close();
+        }
+        catch {
+            // Preserve the startup failure; cleanup can be retried by the factory.
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        worker.off('message', startupMessage);
+        worker.off('error', startupError);
+        worker.off('exit', startupExit);
+    }
+}
+export function createNodeWorkerDeploymentRuntimeFactory(options = {}) {
+    const timeoutMs = startupTimeout(options.startupTimeoutMs);
+    return Object.freeze({
+        async start(snapshot, input) {
+            const root = await ensureTemporaryDirectory(options.temporaryDirectory);
+            const directory = await mkdtemp(path.join(root, 'hypequery-node-runtime-'));
+            try {
+                await chmod(directory, 0o700);
+                return await startWorker(snapshot, directory, timeoutMs, input.signal);
+            }
+            catch (error) {
+                try {
+                    await rm(directory, { force: true, recursive: true });
+                }
+                catch (cleanupError) {
+                    options.onCleanupError?.(cleanupError, directory);
+                    // Preserve the error that prevented a runtime from starting.
+                }
+                throw error;
+            }
+        },
+    });
+}

package/dist/runtime-materialization.d.ts

@@ -0,0 +1,58 @@
+import type { ProtocolDeploymentContract, ProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+import type { DeploymentActivationRecord, DeploymentActivationRegistry } from './activation.js';
+import { type VerifiedDeploymentBundle } from './bundle.js';
+export type DeploymentRuntimeMaterializationErrorCode = 'HQ_RUNTIME_MATERIALIZATION_CONFIGURATION' | 'HQ_RUNTIME_MATERIALIZATION_ACTIVATION_UNAVAILABLE' | 'HQ_RUNTIME_MATERIALIZATION_RELEASE_NOT_FOUND' | 'HQ_RUNTIME_MATERIALIZATION_RELEASE_INVALID' | 'HQ_RUNTIME_MATERIALIZATION_ARTIFACT_INVALID' | 'HQ_RUNTIME_MATERIALIZATION_UNSTABLE_ACTIVATION';
+export declare class DeploymentRuntimeMaterializationError extends Error {
+    readonly code: DeploymentRuntimeMaterializationErrorCode;
+    constructor(code: DeploymentRuntimeMaterializationErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface DeploymentRuntimeRelease {
+    readonly release: ProtocolDeploymentReleaseEnvelope;
+    readonly releaseIdentity: string;
+    readonly bundle: VerifiedDeploymentBundle;
+}
+export interface DeploymentRuntimeReleaseReader {
+    /** Return only a fully revalidated accepted release and its closed bundle. */
+    read(releaseIdentity: string): Promise<DeploymentRuntimeRelease | undefined>;
+}
+export interface DeploymentRuntimeArtifactSnapshot {
+    readonly runtime: 'node' | 'python';
+    readonly artifactSha256: string;
+    readonly byteLength: number;
+    readonly entrypoints: readonly string[];
+    /** Returns a fresh copy so callers cannot mutate the materialized bytes. */
+    read(): Uint8Array;
+}
+export interface DeploymentRuntimeQueryBinding {
+    readonly query: string;
+    readonly runtime: 'node' | 'python';
+    readonly artifactSha256: string;
+    readonly entrypoint: string;
+}
+export interface DeploymentRuntimeSnapshot {
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly activation: DeploymentActivationRecord;
+    readonly release: ProtocolDeploymentReleaseEnvelope;
+    readonly releaseIdentity: string;
+    readonly bundleIdentity: string;
+    readonly deployment: ProtocolDeploymentContract;
+    readonly artifacts: readonly DeploymentRuntimeArtifactSnapshot[];
+    readonly queries: readonly DeploymentRuntimeQueryBinding[];
+}
+export interface DeploymentRuntimeMaterializer {
+    /**
+     * Materialize the current activation and confirm it remained current while
+     * its bytes were copied. Returns undefined when the target has no activation.
+     */
+    current(target: ProtocolDeploymentReleaseTarget): Promise<DeploymentRuntimeSnapshot | undefined>;
+}
+export interface DeploymentRuntimeMaterializerOptions {
+    readonly activations: DeploymentActivationRegistry;
+    readonly releases: DeploymentRuntimeReleaseReader;
+    /** Activation-stability attempts from 1 through 16. */
+    readonly maxStabilityAttempts?: number;
+}
+export declare function createDeploymentRuntimeMaterializer(options: DeploymentRuntimeMaterializerOptions): DeploymentRuntimeMaterializer;
+//# sourceMappingURL=runtime-materialization.d.ts.map

package/dist/runtime-materialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-materialization.d.ts","sourceRoot":"","sources":["../src/runtime-materialization.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,0BAA0B,EAC1B,iCAAiC,EACjC,+BAA+B,EAChC,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EACV,0BAA0B,EAC1B,4BAA4B,EAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,aAAa,CAAC;AAKrB,MAAM,MAAM,yCAAyC,GACjD,0CAA0C,GAC1C,mDAAmD,GACnD,8CAA8C,GAC9C,4CAA4C,GAC5C,6CAA6C,GAC7C,gDAAgD,CAAC;AAErD,qBAAa,qCAAsC,SAAQ,KAAK;IAC9D,QAAQ,CAAC,IAAI,EAAE,yCAAyC,CAAC;gBAGvD,IAAI,EAAE,yCAAyC,EAC/C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED,MAAM,WAAW,8BAA8B;IAC7C,8EAA8E;IAC9E,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAC;CAC9E;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,4EAA4E;IAC5E,IAAI,IAAI,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,SAAS,EAAE,SAAS,iCAAiC,EAAE,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC5D;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,+BAA+B,GAAG,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CAAC;CAClG;AAED,MAAM,WAAW,oCAAoC;IACnD,QAAQ,CAAC,WAAW,EAAE,4BAA4B,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;IAClD,uDAAuD;IACvD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AA4LD,wBAAgB,mCAAmC,CACjD,OAAO,EAAE,oCAAoC,GAC5C,6BAA6B,CA+C/B"}