@hypequery/cli 1.5.0 → 1.7.0

package/README.md

@@ -138,35 +138,48 @@ semantic keys such as `dataset:orders`.
 
 ### `hypequery deployment:build`
 
-Builds deployment metadata for an exported HypeQuery API and writes the
-artifact with its identity sidecar.
+Builds a closed deployment bundle for an exported HypeQuery API. The bundle
+contains canonical deployment metadata, every referenced runtime artifact, and
+a manifest that binds their exact bytes and identities.
 
 ```bash
-npx hypequery deployment:build analytics/api.ts \
-  --runtime-artifact 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+npx hypequery deployment:build analytics/api.ts
 ```
 
-The runtime artifact digest is required when named Serve handlers cannot be
-lowered to a portable implementation. Dataset-only APIs can omit it.
+The default output is `analytics/hypequery-deployment/`. Named Serve handlers
+are bundled into a Node runtime artifact automatically. Dataset-only APIs do
+not produce a runtime artifact. For a separately built Node or Python runtime,
+provide both its expected digest and file path:
+
+```bash
+npx hypequery deployment:build analytics/api.ts \
+  --runtime python \
+  --runtime-artifact <sha256> \
+  --runtime-file dist/runtime.pyz
+```
 
 Options:
 
-- `--output <path>`: default `analytics/hypequery-deployment.json`
+- `--bundle-output <directory>`: default `analytics/hypequery-deployment`
 - `--runtime <runtime>`: `node` (default) or `python`
-- `--runtime-artifact <sha256>`: lowercase SHA-256 of the built runtime artifact
+- `--runtime-artifact <sha256>`: lowercase SHA-256 of a prebuilt runtime artifact
+- `--runtime-file <path>`: bytes for the prebuilt runtime artifact
 - `--entrypoint-prefix <prefix>`: default `queries`
-- `--hash-output <path>`: default `<output>.sha256`
 
-The identity sidecar is not compatible with `sha256sum -c`. Use
-`deployment:validate` to validate the artifact and report its identity.
+The compatibility options `--output`, `--runtime-output`, and `--hash-output`
+still emit the earlier metadata files instead of a complete bundle. They cannot
+be combined with `--bundle-output`.
 
 ### `hypequery deployment:validate`
 
-Validates an existing deployment artifact and reports its datasets, queries,
-runtime artifacts, and identity.
+Verifies a complete deployment bundle before returning any contained metadata.
+Verification rejects missing or undeclared files, symbolic links, path
+traversal, byte-length or hash mismatches, deployment identity mismatches, and
+runtime files not referenced by the deployment. Legacy deployment JSON files
+are still accepted for metadata-only validation.
 
 ```bash
-npx hypequery deployment:validate analytics/hypequery-deployment.json
+npx hypequery deployment:validate analytics/hypequery-deployment
 ```
 
 ## Non-interactive Setup

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AAwJD,OAAO,EAAE,OAAO,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAa9B,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;EAKpE;AA2JD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/cli.js

@@ -111,10 +111,13 @@ program
 }));
 program
     .command('deployment:build <api>')
-    .description('Build a validated, canonical deployment contract and identity')
+    .description('Build a verified deployment bundle')
+    .option('--bundle-output <directory>', 'Bundle directory (default: analytics/hypequery-deployment)')
     .option('-o, --output <path>', 'Output JSON file (default: analytics/hypequery-deployment.json)')
     .option('--runtime <runtime>', 'Runtime for non-portable handlers: node or python (default: node)')
-    .option('--runtime-artifact <sha256>', 'SHA-256 identity of the built runtime artifact')
+    .option('--runtime-artifact <sha256>', 'Use a prebuilt runtime artifact with this SHA-256 identity')
+    .option('--runtime-file <path>', 'Include the bytes for a prebuilt runtime artifact')
+    .option('--runtime-output <path>', 'Bundled Node runtime path (default: beside deployment JSON)')
     .option('--entrypoint-prefix <prefix>', 'Runtime entrypoint prefix (default: queries)')
     .option('--hash-output <path>', 'Deployment identity sidecar path (default: <output>.sha256)')
     .action(runCommand(async (api, options) => {
@@ -122,7 +125,7 @@ program
 }));
 program
     .command('deployment:validate <artifact>')
-    .description('Validate a deployment contract and report its identity')
+    .description('Verify a deployment bundle or validate a legacy deployment JSON file')
     .action(runCommand(async (artifact) => {
     await validateDeploymentCommand(artifact);
 }));
@@ -156,8 +159,8 @@ program.on('--help', () => {
     console.log('  hypequery generate:types --output analytics/schema.ts');
     console.log('  hypequery generate:datasets');
     console.log('  hypequery generate:manifest analytics/api.ts --output analytics/hypequery-manifest.json');
-    console.log('  hypequery deployment:build analytics/api.ts --runtime-artifact <sha256>');
-    console.log('  hypequery deployment:validate analytics/hypequery-deployment.json');
+    console.log('  hypequery deployment:build analytics/api.ts');
+    console.log('  hypequery deployment:validate analytics/hypequery-deployment');
     console.log('');
     console.log('Docs: https://hypequery.com/docs');
 });

package/dist/commands/deployment.d.ts

@@ -1,8 +1,11 @@
 import { type ProtocolDeploymentContract } from '@hypequery/protocol';
 export interface BuildDeploymentOptions {
+    bundleOutput?: string;
     output?: string;
     runtime?: 'node' | 'python';
     runtimeArtifact?: string;
+    runtimeFile?: string;
+    runtimeOutput?: string;
     entrypointPrefix?: string;
     hashOutput?: string;
 }

package/dist/commands/deployment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA8BD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAuCrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAoCrC"}
+{"version":3,"file":"deployment.d.ts","sourceRoot":"","sources":["../../src/commands/deployment.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAiB7B,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAwIrC;AAED,wBAAsB,yBAAyB,CAC7C,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA2ErC"}

package/dist/commands/deployment.js

@@ -1,19 +1,26 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { writeDeploymentBundle, verifyDeploymentBundle, readDeploymentRuntimeFile, } from '../utils/deployment-bundle.js';
+import { buildNodeRuntimeArtifact, getDeploymentRuntimeEntrypoints, } from '../utils/deployment-runtime-artifact.js';
 import { loadApiModule } from '../utils/load-api.js';
 import { logger } from '../utils/logger.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
-function runtimeArtifact(options) {
+const DEFAULT_BUNDLE_OUTPUT = 'analytics/hypequery-deployment';
+function runtimeName(options) {
+    const runtime = options.runtime ?? 'node';
+    if (runtime !== 'node' && runtime !== 'python') {
+        throw new Error('--runtime must be either node or python.');
+    }
+    return runtime;
+}
+function configuredRuntimeArtifact(options, runtime) {
     if (options.runtimeArtifact === undefined)
         return undefined;
     if (!SHA256_PATTERN.test(options.runtimeArtifact)) {
         throw new Error('--runtime-artifact must be a lowercase 64-character SHA-256 digest.');
     }
-    const runtime = options.runtime ?? 'node';
-    if (runtime !== 'node' && runtime !== 'python') {
-        throw new Error('--runtime must be either node or python.');
-    }
     return {
         runtime,
         artifactSha256: options.runtimeArtifact,
@@ -22,23 +29,113 @@ function runtimeArtifact(options) {
             : {}),
     };
 }
+function assertDistinctOutputPaths(paths) {
+    const seen = new Map();
+    for (const [label, value] of Object.entries(paths)) {
+        if (value === undefined)
+            continue;
+        const resolved = path.resolve(value);
+        const existing = seen.get(resolved);
+        if (existing) {
+            throw new Error(`${label} must use a different path from ${existing}.`);
+        }
+        seen.set(resolved, label);
+    }
+}
 export async function buildDeploymentCommand(apiPath, options = {}) {
     if (!apiPath) {
         throw new Error('Missing API module path.\n\n'
             + 'Usage: hypequery deployment:build analytics/api.ts');
     }
-    const artifact = runtimeArtifact(options);
+    const runtime = runtimeName(options);
+    const configuredArtifact = configuredRuntimeArtifact(options, runtime);
+    const legacyOutputRequested = options.output !== undefined
+        || options.hashOutput !== undefined
+        || options.runtimeOutput !== undefined;
+    if (options.bundleOutput !== undefined && legacyOutputRequested) {
+        throw new Error('--bundle-output cannot be combined with --output, --hash-output, or --runtime-output.');
+    }
+    const bundleOutput = options.bundleOutput
+        ?? (legacyOutputRequested ? undefined : DEFAULT_BUNDLE_OUTPUT);
+    if (options.runtimeFile !== undefined && configuredArtifact === undefined) {
+        throw new Error('--runtime-file requires --runtime-artifact.');
+    }
+    if (options.runtimeFile !== undefined && bundleOutput === undefined) {
+        throw new Error('--runtime-file is only supported when building a deployment bundle.');
+    }
+    if (configuredArtifact && bundleOutput !== undefined && options.runtimeFile === undefined) {
+        throw new Error('A complete deployment bundle requires --runtime-file with a prebuilt --runtime-artifact.');
+    }
+    if (configuredArtifact && options.runtimeOutput !== undefined) {
+        throw new Error('--runtime-output cannot be used with a prebuilt --runtime-artifact.');
+    }
+    const outputPath = options.output ?? 'analytics/hypequery-deployment.json';
+    const hashOutputPath = options.hashOutput ?? `${outputPath}.sha256`;
+    if (options.runtimeOutput !== undefined) {
+        assertDistinctOutputPaths({
+            '--output': outputPath,
+            '--hash-output': hashOutputPath,
+            '--runtime-output': options.runtimeOutput,
+        });
+    }
     const api = await loadApiModule(apiPath);
     if (typeof api.deploymentContract !== 'function') {
         throw new Error(`Invalid API module: ${apiPath}\n\n`
             + 'The exported API must provide deploymentContract(). '
             + 'Upgrade @hypequery/serve and export the value returned by createAPI() or serve().');
     }
+    let builtArtifact;
+    let artifact = configuredArtifact;
+    if (!artifact) {
+        const runtimeEntrypoints = getDeploymentRuntimeEntrypoints(api);
+        if (runtimeEntrypoints.length > 0) {
+            if (runtime !== 'node') {
+                throw new Error('Automatic runtime artifact builds currently support Node only. '
+                    + 'Provide --runtime-artifact for Python deployments.');
+            }
+            builtArtifact = await buildNodeRuntimeArtifact(apiPath, runtimeEntrypoints, options.entrypointPrefix);
+            artifact = {
+                runtime: 'node',
+                artifactSha256: builtArtifact.artifactSha256,
+                entrypointPrefix: builtArtifact.entrypointPrefix,
+            };
+        }
+    }
     const contract = api.deploymentContract(artifact ? { runtimeArtifact: artifact } : {});
     const prepared = prepareProtocolDeploymentContract(contract);
     const { canonical, contract: validated, identity: digest } = prepared;
-    const outputPath = options.output ?? 'analytics/hypequery-deployment.json';
-    const hashOutputPath = options.hashOutput ?? `${outputPath}.sha256`;
+    if (bundleOutput !== undefined) {
+        const runtimeFiles = [];
+        if (builtArtifact) {
+            runtimeFiles.push({
+                runtime: 'node',
+                sha256: builtArtifact.artifactSha256,
+                bytes: builtArtifact.bytes,
+            });
+        }
+        else if (configuredArtifact && options.runtimeFile) {
+            const bytes = await readDeploymentRuntimeFile(options.runtimeFile);
+            const actualSha256 = createHash('sha256').update(bytes).digest('hex');
+            if (actualSha256 !== configuredArtifact.artifactSha256) {
+                throw new Error(`Prebuilt runtime artifact SHA-256 mismatch: ${options.runtimeFile}\n\n`
+                    + `Expected: ${configuredArtifact.artifactSha256}\nActual: ${actualSha256}`);
+            }
+            runtimeFiles.push({ runtime, sha256: actualSha256, bytes });
+        }
+        const bundle = await writeDeploymentBundle(bundleOutput, prepared, runtimeFiles);
+        logger.success(`Deployment bundle written to ${bundle.directory}`);
+        logger.info(`Bundle identity: ${bundle.identity}`);
+        logger.info(`Deployment identity: ${digest}`);
+        return validated;
+    }
+    const runtimeOutputPath = builtArtifact
+        ? options.runtimeOutput ?? path.join(path.dirname(outputPath), 'hypequery-runtime.mjs')
+        : undefined;
+    assertDistinctOutputPaths({
+        '--output': outputPath,
+        '--hash-output': hashOutputPath,
+        '--runtime-output': runtimeOutputPath,
+    });
     const identitySidecar = [
         '# Hypequery deployment identity v1; not a file checksum or sha256sum input.',
         '# SHA-256(UTF-8("hypequery:deployment:v1") || 0x00 || RFC 8785 canonical bytes); '
@@ -48,8 +145,16 @@ export async function buildDeploymentCommand(apiPath, options = {}) {
     ].join('\n');
     await mkdir(path.dirname(outputPath), { recursive: true });
     await mkdir(path.dirname(hashOutputPath), { recursive: true });
+    if (runtimeOutputPath && builtArtifact) {
+        await mkdir(path.dirname(runtimeOutputPath), { recursive: true });
+        await writeFile(runtimeOutputPath, builtArtifact.bytes);
+    }
     await writeFile(outputPath, `${canonical}\n`, 'utf8');
     await writeFile(hashOutputPath, identitySidecar, 'utf8');
+    if (runtimeOutputPath && builtArtifact) {
+        logger.success(`Runtime artifact written to ${runtimeOutputPath}`);
+        logger.info(`Runtime artifact SHA-256: ${builtArtifact.artifactSha256}`);
+    }
     logger.success(`Deployment contract written to ${outputPath}`);
     logger.info(`Identity: ${digest}`);
     return validated;
@@ -57,7 +162,37 @@ export async function buildDeploymentCommand(apiPath, options = {}) {
 export async function validateDeploymentCommand(artifactPath) {
     if (!artifactPath) {
         throw new Error('Missing deployment artifact path.\n\n'
-            + 'Usage: hypequery deployment:validate analytics/hypequery-deployment.json');
+            + 'Usage: hypequery deployment:validate analytics/hypequery-deployment');
+    }
+    let artifactStat;
+    try {
+        artifactStat = await stat(artifactPath);
+    }
+    catch (error) {
+        if (!(typeof error === 'object' && error !== null && 'code' in error
+            && error.code === 'ENOENT')) {
+            throw new Error(`Cannot inspect deployment input: ${artifactPath}\n\n`
+                + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    if (artifactStat?.isDirectory()) {
+        try {
+            const bundle = await verifyDeploymentBundle(artifactPath);
+            const contract = bundle.contract;
+            logger.success(`Valid deployment bundle: ${artifactPath}`);
+            logger.info(`${contract.datasets.length} datasets, ${contract.queries.length} queries, `
+                + `${contract.artifacts.length} runtime artifacts`);
+            logger.info(`Bundle identity: ${bundle.identity}`);
+            logger.info(`Deployment identity: ${bundle.manifest.deployment.identity}`);
+            return contract;
+        }
+        catch (error) {
+            throw new Error(`Invalid deployment bundle: ${artifactPath}\n\n`
+                + (error instanceof Error ? error.message : String(error)));
+        }
+    }
+    if (artifactStat && !artifactStat.isFile()) {
+        throw new Error(`Deployment input must be a regular JSON file or bundle directory: ${artifactPath}`);
     }
     let input;
     try {

package/dist/utils/deployment-bundle.d.ts

@@ -0,0 +1,19 @@
+import { type PreparedProtocolDeploymentContract, type ProtocolDeploymentBundleManifest, type ProtocolDeploymentContract } from '@hypequery/protocol';
+export declare const DEPLOYMENT_BUNDLE_MANIFEST = "bundle.json";
+export declare const DEPLOYMENT_BUNDLE_CONTRACT = "deployment.json";
+export interface DeploymentBundleRuntimeFile {
+    readonly runtime: 'node' | 'python';
+    readonly sha256: string;
+    readonly bytes: Uint8Array;
+}
+export interface WrittenDeploymentBundle {
+    readonly directory: string;
+    readonly manifest: ProtocolDeploymentBundleManifest;
+    readonly identity: string;
+    readonly contract: ProtocolDeploymentContract;
+}
+export type VerifiedDeploymentBundle = WrittenDeploymentBundle;
+export declare function writeDeploymentBundle(outputDirectory: string, prepared: PreparedProtocolDeploymentContract, runtimeFiles: readonly DeploymentBundleRuntimeFile[]): Promise<WrittenDeploymentBundle>;
+export declare function readDeploymentRuntimeFile(filePath: string): Promise<Uint8Array>;
+export declare function verifyDeploymentBundle(bundleDirectory: string): Promise<VerifiedDeploymentBundle>;
+//# sourceMappingURL=deployment-bundle.d.ts.map

package/dist/utils/deployment-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-bundle.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-bundle.ts"],"names":[],"mappings":"AAaA,OAAO,EAIL,KAAK,kCAAkC,EAEvC,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAG7B,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAED,MAAM,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AA+F/D,wBAAsB,qBAAqB,CACzC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,kCAAkC,EAC5C,YAAY,EAAE,SAAS,2BAA2B,EAAE,GACnD,OAAO,CAAC,uBAAuB,CAAC,CA6ElC;AAgDD,wBAAsB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAMrF;AA+FD,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,wBAAwB,CAAC,CA+DnC"}

package/dist/utils/deployment-bundle.js

@@ -0,0 +1,322 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, lstat, mkdir, mkdtemp, open, readdir, rename, rm, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+import { logger } from './logger.js';
+export const DEPLOYMENT_BUNDLE_MANIFEST = 'bundle.json';
+export const DEPLOYMENT_BUNDLE_CONTRACT = 'deployment.json';
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+const utf8Encoder = new TextEncoder();
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+function runtimeArtifactPath(runtime, digest) {
+    return `artifacts/${digest}.${runtime === 'node' ? 'mjs' : 'pyz'}`;
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+async function existingVerifiedBundle(outputDirectory) {
+    try {
+        await lstat(outputDirectory);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+    try {
+        await verifyDeploymentBundle(outputDirectory);
+    }
+    catch (error) {
+        throw new Error('Refusing to replace an existing path that is not a valid deployment bundle: '
+            + `${outputDirectory}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    return true;
+}
+function validateRuntimeFiles(prepared, files) {
+    requireClosedContractArtifactSet(prepared.contract);
+    const declared = new Map(prepared.contract.artifacts.map(artifact => [artifact.artifactSha256, artifact.runtime]));
+    const supplied = new Map();
+    for (const file of files) {
+        if (sha256(file.bytes) !== file.sha256) {
+            throw new Error(`Runtime artifact bytes do not match SHA-256 ${file.sha256}.`);
+        }
+        if (declared.get(file.sha256) !== file.runtime) {
+            throw new Error(`Runtime artifact ${file.sha256} is not declared by the deployment contract as ${file.runtime}.`);
+        }
+        if (supplied.has(file.sha256)) {
+            throw new Error(`Duplicate runtime artifact bytes supplied for ${file.sha256}.`);
+        }
+        if (file.bytes.byteLength < 1
+            || file.bytes.byteLength > DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes) {
+            throw new Error(`Runtime artifact ${file.sha256} exceeds the bundle byte limits.`);
+        }
+        supplied.set(file.sha256, file.runtime);
+    }
+    for (const [digest, runtime] of declared) {
+        if (supplied.get(digest) !== runtime) {
+            throw new Error(`Deployment bundle is missing ${runtime} runtime artifact ${digest}.`);
+        }
+    }
+    return Object.freeze([...files].sort((left, right) => {
+        const leftPath = runtimeArtifactPath(left.runtime, left.sha256);
+        const rightPath = runtimeArtifactPath(right.runtime, right.sha256);
+        return leftPath < rightPath ? -1 : leftPath > rightPath ? 1 : 0;
+    }));
+}
+function requireClosedContractArtifactSet(contract) {
+    const referenced = new Map();
+    for (const query of contract.queries) {
+        if (query.implementation.kind === 'runtime-reference') {
+            referenced.set(query.implementation.artifactSha256, query.implementation.runtime);
+        }
+    }
+    if (referenced.size !== contract.artifacts.length) {
+        throw new Error('Deployment contract contains missing or unreferenced runtime artifacts.');
+    }
+    for (const artifact of contract.artifacts) {
+        if (referenced.get(artifact.artifactSha256) !== artifact.runtime) {
+            throw new Error(`Deployment runtime artifact ${artifact.artifactSha256} is not referenced by a named query.`);
+        }
+    }
+}
+export async function writeDeploymentBundle(outputDirectory, prepared, runtimeFiles) {
+    const destination = path.resolve(outputDirectory);
+    if (destination === path.parse(destination).root) {
+        throw new Error('The deployment bundle output cannot be a filesystem root.');
+    }
+    const files = validateRuntimeFiles(prepared, runtimeFiles);
+    const deploymentBytes = utf8Encoder.encode(`${prepared.canonical}\n`);
+    const manifestInput = {
+        kind: 'hypequery-deployment-bundle',
+        version: 1,
+        deployment: {
+            path: DEPLOYMENT_BUNDLE_CONTRACT,
+            identity: prepared.identity,
+            sha256: sha256(deploymentBytes),
+            byteLength: deploymentBytes.byteLength,
+        },
+        artifacts: files.map(file => ({
+            runtime: file.runtime,
+            path: runtimeArtifactPath(file.runtime, file.sha256),
+            sha256: file.sha256,
+            byteLength: file.bytes.byteLength,
+        })),
+    };
+    const preparedManifest = prepareProtocolDeploymentBundleManifest(manifestInput);
+    const replaceExisting = await existingVerifiedBundle(destination);
+    const parent = path.dirname(destination);
+    await mkdir(parent, { recursive: true });
+    const staging = await mkdtemp(path.join(parent, `.${path.basename(destination)}.tmp-`));
+    try {
+        if (files.length > 0)
+            await mkdir(path.join(staging, 'artifacts'));
+        await writeFile(path.join(staging, DEPLOYMENT_BUNDLE_CONTRACT), deploymentBytes, { flag: 'wx' });
+        for (const file of files) {
+            await writeFile(path.join(staging, runtimeArtifactPath(file.runtime, file.sha256)), file.bytes, { flag: 'wx' });
+        }
+        await writeFile(path.join(staging, DEPLOYMENT_BUNDLE_MANIFEST), `${preparedManifest.canonical}\n`, { encoding: 'utf8', flag: 'wx' });
+        if (!replaceExisting) {
+            await rename(staging, destination);
+        }
+        else {
+            const backup = path.join(parent, `.${path.basename(destination)}.previous-${randomUUID()}`);
+            await rename(destination, backup);
+            try {
+                await rename(staging, destination);
+            }
+            catch (error) {
+                await rename(backup, destination);
+                throw error;
+            }
+            try {
+                await rm(backup, { recursive: true });
+            }
+            catch (error) {
+                logger.warn(`Deployment bundle was replaced, but its previous backup could not be removed: ${backup}`
+                    + ` (${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+    }
+    catch (error) {
+        await rm(staging, { force: true, recursive: true });
+        throw error;
+    }
+    return Object.freeze({
+        directory: destination,
+        manifest: preparedManifest.manifest,
+        identity: preparedManifest.identity,
+        contract: prepared.contract,
+    });
+}
+async function readBoundedAbsoluteRegularFile(absolutePath, displayPath, maximum) {
+    let handle;
+    try {
+        const initialStat = await lstat(absolutePath);
+        if (initialStat.isSymbolicLink()) {
+            throw new Error(`Bundle entry must not be a symbolic link: ${displayPath}`);
+        }
+        if (!initialStat.isFile()) {
+            throw new Error(`Bundle entry is not a regular file: ${displayPath}`);
+        }
+        if (initialStat.size < 1 || initialStat.size > maximum) {
+            throw new Error(`Bundle entry exceeds its byte limit: ${displayPath}`);
+        }
+        handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`Bundle entry is not a regular file: ${displayPath}`);
+        if (stat.size < 1 || stat.size > maximum) {
+            throw new Error(`Bundle entry exceeds its byte limit: ${displayPath}`);
+        }
+        return await handle.readFile();
+    }
+    catch (error) {
+        if (errorCode(error) === 'ELOOP') {
+            throw new Error(`Bundle entry must not be a symbolic link: ${displayPath}`);
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function readBoundedRegularFile(root, relativePath, maximum) {
+    return readBoundedAbsoluteRegularFile(path.join(root, ...relativePath.split('/')), relativePath, maximum);
+}
+export async function readDeploymentRuntimeFile(filePath) {
+    return readBoundedAbsoluteRegularFile(path.resolve(filePath), filePath, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
+}
+function expectedDirectories(files) {
+    const result = new Set();
+    for (const file of files) {
+        const segments = file.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            result.add(segments.slice(0, index).join('/'));
+        }
+    }
+    return result;
+}
+async function verifyExactEntries(root, manifest) {
+    const expectedFiles = new Set([
+        DEPLOYMENT_BUNDLE_MANIFEST,
+        manifest.deployment.path,
+        ...manifest.artifacts.map(artifact => artifact.path),
+    ]);
+    const expectedDirectoryPaths = expectedDirectories([...expectedFiles]);
+    const seenFiles = new Set();
+    const seenDirectories = new Set();
+    async function visit(relativeDirectory) {
+        const absoluteDirectory = relativeDirectory
+            ? path.join(root, ...relativeDirectory.split('/'))
+            : root;
+        const names = await readdir(absoluteDirectory);
+        names.sort();
+        for (const name of names) {
+            const relativePath = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+            const stat = await lstat(path.join(absoluteDirectory, name));
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Bundle entries must not be symbolic links: ${relativePath}`);
+            }
+            if (stat.isDirectory()) {
+                if (!expectedDirectoryPaths.has(relativePath)) {
+                    throw new Error(`Deployment bundle contains an undeclared directory: ${relativePath}`);
+                }
+                seenDirectories.add(relativePath);
+                await visit(relativePath);
+            }
+            else if (stat.isFile()) {
+                if (!expectedFiles.has(relativePath)) {
+                    throw new Error(`Deployment bundle contains an undeclared file: ${relativePath}`);
+                }
+                seenFiles.add(relativePath);
+            }
+            else {
+                throw new Error(`Bundle entry is not a regular file or directory: ${relativePath}`);
+            }
+        }
+    }
+    await visit('');
+    const missingFiles = [...expectedFiles].filter(file => !seenFiles.has(file)).sort();
+    if (missingFiles.length > 0) {
+        throw new Error(`Deployment bundle is missing files: ${missingFiles.join(', ')}`);
+    }
+    const missingDirectories = [...expectedDirectoryPaths]
+        .filter(directory => !seenDirectories.has(directory))
+        .sort();
+    if (missingDirectories.length > 0) {
+        throw new Error(`Deployment bundle is missing directories: ${missingDirectories.join(', ')}`);
+    }
+}
+function verifyFile(bytes, file) {
+    if (bytes.byteLength !== file.byteLength) {
+        throw new Error(`Bundle entry byte length does not match the manifest: ${file.path}`);
+    }
+    if (sha256(bytes) !== file.sha256) {
+        throw new Error(`Bundle entry SHA-256 does not match the manifest: ${file.path}`);
+    }
+}
+function verifyRuntimeReferences(contract, artifacts) {
+    requireClosedContractArtifactSet(contract);
+    const declared = new Map(contract.artifacts.map(artifact => [artifact.artifactSha256, artifact.runtime]));
+    if (declared.size !== artifacts.length) {
+        throw new Error('Bundle runtime artifacts do not match the deployment contract.');
+    }
+    for (const artifact of artifacts) {
+        if (declared.get(artifact.sha256) !== artifact.runtime) {
+            throw new Error(`Bundle artifact ${artifact.sha256} does not match a deployment runtime reference.`);
+        }
+    }
+}
+export async function verifyDeploymentBundle(bundleDirectory) {
+    const root = path.resolve(bundleDirectory);
+    const rootStat = await lstat(root);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new Error(`Deployment bundle path must be a regular directory: ${bundleDirectory}`);
+    }
+    const manifestBytes = await readBoundedRegularFile(root, DEPLOYMENT_BUNDLE_MANIFEST, 1024 * 1024);
+    let input;
+    try {
+        input = JSON.parse(utf8Decoder.decode(manifestBytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment bundle manifest: ${path.join(root, DEPLOYMENT_BUNDLE_MANIFEST)}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const preparedManifest = prepareProtocolDeploymentBundleManifest(input);
+    const expectedManifestBytes = utf8Encoder.encode(`${preparedManifest.canonical}\n`);
+    if (!Buffer.from(manifestBytes).equals(Buffer.from(expectedManifestBytes))) {
+        throw new Error('Deployment bundle manifest must contain canonical JSON followed by one newline.');
+    }
+    await verifyExactEntries(root, preparedManifest.manifest);
+    const deployment = preparedManifest.manifest.deployment;
+    const deploymentBytes = await readBoundedRegularFile(root, deployment.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxDeploymentBytes);
+    verifyFile(deploymentBytes, deployment);
+    let contractInput;
+    try {
+        contractInput = JSON.parse(utf8Decoder.decode(deploymentBytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment JSON in bundle: ${deployment.path}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const preparedContract = prepareProtocolDeploymentContract(contractInput);
+    if (preparedContract.identity !== deployment.identity) {
+        throw new Error('Deployment identity does not match the bundle manifest.');
+    }
+    for (const artifact of preparedManifest.manifest.artifacts) {
+        const bytes = await readBoundedRegularFile(root, artifact.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
+        verifyFile(bytes, artifact);
+    }
+    verifyRuntimeReferences(preparedContract.contract, preparedManifest.manifest.artifacts);
+    return Object.freeze({
+        directory: root,
+        manifest: preparedManifest.manifest,
+        identity: preparedManifest.identity,
+        contract: preparedContract.contract,
+    });
+}

package/dist/utils/deployment-runtime-artifact.d.ts

@@ -0,0 +1,9 @@
+export interface NodeRuntimeArtifact {
+    readonly bytes: Uint8Array;
+    readonly artifactSha256: string;
+    readonly entrypointPrefix: string;
+    readonly runtimeEntrypoints: readonly string[];
+}
+export declare function getDeploymentRuntimeEntrypoints(input: unknown): readonly string[];
+export declare function buildNodeRuntimeArtifact(apiPath: string, runtimeEntrypoints: readonly string[], entrypointPrefix?: string): Promise<NodeRuntimeArtifact>;
+//# sourceMappingURL=deployment-runtime-artifact.d.ts.map

package/dist/utils/deployment-runtime-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-runtime-artifact.d.ts","sourceRoot":"","sources":["../../src/utils/deployment-runtime-artifact.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AASD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CA6BjF;AA6CD,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,gBAAgB,SAAY,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAmD9B"}

package/dist/utils/deployment-runtime-artifact.js

@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { parseProtocolIdentifier, parseProtocolQualifiedIdentifier, } from '@hypequery/protocol';
+import { build } from 'esbuild';
+import { findNearestTsconfig } from './load-api.js';
+const deploymentBuildSourceSymbol = Symbol.for('hypequery.deployment-build-source.v1');
+function executableQuery(query) {
+    return typeof query === 'function'
+        || (typeof query === 'object'
+            && query !== null
+            && typeof query.run === 'function');
+}
+export function getDeploymentRuntimeEntrypoints(input) {
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('Invalid API module: deployment build metadata is unavailable.');
+    }
+    const api = input;
+    const source = api[deploymentBuildSourceSymbol];
+    if (source?.version !== 1 || !Array.isArray(source.runtimeEntrypoints)) {
+        throw new Error('The exported API does not expose deployment build metadata. '
+            + 'Upgrade @hypequery/serve before building runtime artifacts.');
+    }
+    const names = source.runtimeEntrypoints.map((name) => {
+        try {
+            return parseProtocolIdentifier(name);
+        }
+        catch {
+            throw new Error(`Invalid runtime entrypoint name: ${String(name)}`);
+        }
+    });
+    if (new Set(names).size !== names.length) {
+        throw new Error('Deployment build metadata contains duplicate runtime entrypoints.');
+    }
+    for (const name of names) {
+        if (!executableQuery(api.queries?.[name]?.query)) {
+            throw new Error(`Serve query "${name}" does not expose an executable runtime handler.`);
+        }
+    }
+    return Object.freeze([...names].sort());
+}
+function projectRelativeImport(apiPath) {
+    const resolved = path.resolve(process.cwd(), apiPath);
+    const relative = path.relative(process.cwd(), resolved);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error('The API module must be inside the current project for deterministic bundling.');
+    }
+    const portable = relative.split(path.sep).join('/');
+    return {
+        resolved,
+        specifier: portable.startsWith('.') ? portable : `./${portable}`,
+    };
+}
+function runtimeEntrySource(apiSpecifier, runtimeEntrypoints, entrypointPrefix) {
+    const prefix = parseProtocolQualifiedIdentifier(entrypointPrefix).split('.');
+    const names = JSON.stringify(runtimeEntrypoints);
+    let registryExpression = 'runtimeEntries';
+    for (let index = prefix.length - 1; index >= 1; index -= 1) {
+        registryExpression = `Object.freeze({ ${prefix[index]}: ${registryExpression} })`;
+    }
+    return [
+        `import * as apiModule from ${JSON.stringify(apiSpecifier)};`,
+        'const api = apiModule.api ?? Reflect.get(apiModule, "default");',
+        'if (!api || typeof api !== "object") throw new Error("Runtime API export is unavailable.");',
+        'const resolveQuery = (name) => {',
+        '  const query = api.queries?.[name]?.query;',
+        '  if (typeof query === "function") return query;',
+        '  if (query && typeof query === "object" && typeof query.run === "function") {',
+        '    return query.run.bind(query);',
+        '  }',
+        '  throw new Error(`Runtime entrypoint ${name} is unavailable.`);',
+        '};',
+        `const runtimeEntries = Object.freeze(Object.fromEntries(${names}.map(name => [name, resolveQuery(name)])));`,
+        `export const ${prefix[0]} = ${registryExpression};`,
+        '',
+    ].join('\n');
+}
+export async function buildNodeRuntimeArtifact(apiPath, runtimeEntrypoints, entrypointPrefix = 'queries') {
+    if (runtimeEntrypoints.length === 0) {
+        throw new Error('Cannot build a runtime artifact without Serve query entrypoints.');
+    }
+    const names = getValidatedEntrypointNames(runtimeEntrypoints);
+    const { resolved, specifier } = projectRelativeImport(apiPath);
+    let source;
+    try {
+        source = runtimeEntrySource(specifier, names, entrypointPrefix);
+    }
+    catch {
+        throw new Error(`Invalid runtime entrypoint prefix: ${entrypointPrefix}`);
+    }
+    try {
+        const result = await build({
+            stdin: {
+                contents: source,
+                loader: 'ts',
+                resolveDir: process.cwd(),
+                sourcefile: 'hypequery-runtime-entry.ts',
+            },
+            absWorkingDir: process.cwd(),
+            bundle: true,
+            charset: 'utf8',
+            format: 'esm',
+            legalComments: 'none',
+            logLevel: 'warning',
+            minify: true,
+            platform: 'node',
+            sourcemap: false,
+            target: ['node18'],
+            treeShaking: true,
+            tsconfig: await findNearestTsconfig(resolved) ?? undefined,
+            write: false,
+        });
+        const output = result.outputFiles?.find(file => file.path.endsWith('.js'))
+            ?? result.outputFiles?.[0];
+        if (!output)
+            throw new Error('esbuild produced no output');
+        const bytes = output.contents;
+        return Object.freeze({
+            bytes,
+            artifactSha256: createHash('sha256').update(bytes).digest('hex'),
+            entrypointPrefix,
+            runtimeEntrypoints: names,
+        });
+    }
+    catch (error) {
+        throw new Error(`Failed to build the Node runtime artifact from ${apiPath}.\n`
+            + `Original error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function getValidatedEntrypointNames(input) {
+    const names = input.map((name) => {
+        try {
+            return parseProtocolIdentifier(name);
+        }
+        catch {
+            throw new Error(`Invalid runtime entrypoint name: ${name}`);
+        }
+    });
+    if (new Set(names).size !== names.length) {
+        throw new Error('Runtime entrypoint names must be unique.');
+    }
+    return Object.freeze([...names].sort());
+}

package/dist/utils/load-api.d.ts

@@ -1,3 +1,4 @@
 export declare function loadApiModule(modulePath: string): Promise<any>;
 export declare function loadModule(modulePath: string): Promise<any>;
+export declare function findNearestTsconfig(filePath: string): Promise<string | null>;
 //# sourceMappingURL=load-api.d.ts.map

package/dist/utils/load-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAaA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAkClD"}
+{"version":3,"file":"load-api.d.ts","sourceRoot":"","sources":["../../src/utils/load-api.ts"],"names":[],"mappings":"AAaA,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,gBA2DrD;AAED,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,gBAkClD;AA0JD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,0BA8BzD"}

package/dist/utils/load-api.js

@@ -217,7 +217,7 @@ async function bundleTypeScriptModule(entryPath) {
             `Original error: ${error?.message ?? error}`);
     }
 }
-async function findNearestTsconfig(filePath) {
+export async function findNearestTsconfig(filePath) {
     let dir = path.dirname(filePath);
     const visited = [];
     while (dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Command-line interface for hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,7 +19,7 @@
     "open": "^10.0.0",
     "ora": "^8.0.1",
     "prompts": "^2.4.2",
-    "@hypequery/protocol": "0.3.0"
+    "@hypequery/protocol": "0.4.0"
   },
   "peerDependencies": {
     "@hypequery/clickhouse": "*",
@@ -37,7 +37,7 @@
     "typescript": "^5.7.3",
     "vitest": "^3.2.6",
     "@hypequery/clickhouse": "2.4.0",
-    "@hypequery/serve": "0.12.0"
+    "@hypequery/serve": "0.13.1"
   },
   "repository": {
     "type": "git",