@hypequery/cli 1.6.0 → 1.7.0

package/README.md

@@ -138,36 +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
 ```
 
-Named Serve handlers are bundled into a Node runtime artifact automatically.
-Dataset-only APIs do not produce a runtime artifact. Use `--runtime-artifact`
-to reference a separately built Node or Python artifact instead.
+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 a prebuilt runtime artifact
-- `--runtime-output <path>`: default beside the deployment JSON as `hypequery-runtime.mjs`
+- `--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;AAyJD,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,12 @@ 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>', '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)')
@@ -123,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);
 }));
@@ -157,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,10 @@
 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;AAW7B,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA0FrC;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,10 +1,13 @@
-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}$/;
+const DEFAULT_BUNDLE_OUTPUT = 'analytics/hypequery-deployment';
 function runtimeName(options) {
     const runtime = options.runtime ?? 'node';
     if (runtime !== 'node' && runtime !== 'python') {
@@ -46,6 +49,23 @@ export async function buildDeploymentCommand(apiPath, 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.');
     }
@@ -84,6 +104,30 @@ export async function buildDeploymentCommand(apiPath, options = {}) {
     const contract = api.deploymentContract(artifact ? { runtimeArtifact: artifact } : {});
     const prepared = prepareProtocolDeploymentContract(contract);
     const { canonical, contract: validated, identity: digest } = prepared;
+    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;
@@ -118,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/cli",
-  "version": "1.6.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.13.0"
+    "@hypequery/serve": "0.13.1"
   },
   "repository": {
     "type": "git",