@hypequery/deployment 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @hypequery/deployment
 
-Provider-neutral verification and receiving-side intake for Hypequery deployment
-bundles.
+Provider-neutral verification, intake, activation, and HTTP control-plane
+building blocks for Hypequery deployment bundles.
 
 The package accepts the authenticated multipart transport emitted by
 `hypequery deploy`, reconstructs only manifest-declared files in temporary
@@ -152,4 +152,97 @@ append-only chain. It has no mutable pointer file or persistent lock to become
 stale after a crash. Activation does not load runtime code, route traffic,
 perform health checks, or authorize callers; those remain provider concerns.
 
+## HTTP control plane
+
+`createDeploymentControlPlane` combines intake and activation behind closed v1
+routes. Activation reads and writes use a separate target-scoped authorizer;
+write authorization completes before the small JSON request body is consumed.
+The Fetch and Node adapters preserve streaming multipart submission bodies.
+
+```ts
+import {
+  createDeploymentControlPlane,
+  createDeploymentControlPlaneNodeHandler,
+} from '@hypequery/deployment';
+
+const controlPlane = createDeploymentControlPlane({
+  intake,
+  activations,
+  authenticator,
+  authorizer: {
+    async authorize({ principal, action, target }) {
+      return canControlDeployment(principal, action, target);
+    },
+  },
+});
+
+const nodeHandler = createDeploymentControlPlaneNodeHandler(controlPlane);
+```
+
+The control plane exposes release submission, compare-and-swap activation,
+current state, and bounded cursor history. It returns stable, bounded JSON error
+codes and suppresses internal provider and filesystem details. The HTTP
+contract is specified in `specs/deployment/0003-control-plane-http.md`.
+
+## Runtime materialization
+
+`createDeploymentRuntimeMaterializer` converts the current target activation
+into a private runtime snapshot. It revalidates the accepted release and closed
+bundle, copies and hashes each runtime artifact without following symbolic
+links, and confirms the activation revision again before returning.
+
+```ts
+import { createDeploymentRuntimeMaterializer } from '@hypequery/deployment';
+
+const materializer = createDeploymentRuntimeMaterializer({
+  activations,
+  releases: store,
+});
+
+const snapshot = await materializer.current({
+  project: 'analytics',
+  environment: 'production',
+});
+```
+
+Artifact `read()` methods return fresh byte copies, so neither callers nor later
+changes to durable storage can alter a materialized snapshot. Runtime imports,
+process lifecycle, readiness, and traffic switching remain separate concerns.
+
+## Runtime supervision
+
+`createDeploymentRuntimeSupervisor` starts materialized snapshots through a
+runtime factory, checks candidate readiness, confirms activation again, and
+atomically changes the generation used for new named-query invocations. Failed
+or superseded candidates never displace a healthy generation.
+
+```ts
+import {
+  createDeploymentRuntimeSupervisor,
+  createNodeWorkerDeploymentRuntimeFactory,
+} from '@hypequery/deployment';
+
+const supervisor = createDeploymentRuntimeSupervisor({
+  materializer,
+  factory: createNodeWorkerDeploymentRuntimeFactory(),
+});
+
+await supervisor.reconcile({ project: 'analytics', environment: 'production' });
+const result = await supervisor.invoke({
+  target: { project: 'analytics', environment: 'production' },
+  query: 'orders',
+  argument: { input, ctx: { tenantId } },
+});
+```
+
+Calls already assigned to an old generation may finish after cutover. That
+generation receives no new calls and closes when its in-flight work reaches
+zero or the drain deadline expires. The reference Node factory loads exact
+materialized bytes in worker threads and removes their temporary files on
+shutdown. Provider factories can implement Python, process, container, or
+remote-sandbox isolation behind the same lifecycle interface.
+
+The reference worker is a lifecycle boundary, not a hostile-code security
+sandbox. Only trusted deployment code should use it directly.
+
 The package is ESM-only and requires Node.js 20 or newer.

package/dist/activation.d.ts

@@ -29,6 +29,14 @@ export type DeploymentActivationResult = {
     readonly status: 'conflict';
     readonly current: DeploymentActivationRecord | null;
 };
+export interface DeploymentActivationHistoryQuery {
+    readonly limit: number;
+    readonly before?: string;
+}
+export interface DeploymentActivationHistoryPage {
+    readonly activations: readonly DeploymentActivationRecord[];
+    readonly nextBefore: string | null;
+}
 export interface DeploymentActivationRelease {
     readonly release: ProtocolDeploymentReleaseEnvelope;
     readonly releaseIdentity: string;
@@ -46,6 +54,9 @@ export interface DeploymentActivationRegistry {
     activate(request: DeploymentActivationRequest): Promise<DeploymentActivationResult>;
     current(target: ProtocolDeploymentReleaseTarget): Promise<DeploymentActivationRecord | undefined>;
     history(target: ProtocolDeploymentReleaseTarget): Promise<readonly DeploymentActivationRecord[]>;
+    historyPage(target: ProtocolDeploymentReleaseTarget, query: DeploymentActivationHistoryQuery): Promise<DeploymentActivationHistoryPage>;
 }
+/** Validate and recompute an immutable deployment activation record. */
+export declare function validateDeploymentActivationRecord(input: unknown): DeploymentActivationRecord;
 export declare function createFileSystemDeploymentActivationRegistry(options: FileSystemDeploymentActivationRegistryOptions): DeploymentActivationRegistry;
 //# sourceMappingURL=activation.d.ts.map

package/dist/activation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../src/activation.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,iCAAiC,EACtC,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAe7B,MAAM,MAAM,6BAA6B,GACrC,wCAAwC,GACxC,0CAA0C,GAC1C,4CAA4C,GAC5C,8CAA8C,GAC9C,0CAA0C,GAC1C,wCAAwC,GACxC,6BAA6B,CAAC;AAElC,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;gBAG3C,IAAI,EAAE,6BAA6B,EACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,MAAM,0BAA0B,GAClC;IACA,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;CACjD,GACC;IACA,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAAC;CACrD,CAAC;AAEJ,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACtC,6FAA6F;IAC7F,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,6CAA6C;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACpF,OAAO,CACL,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,0BAA0B,GAAG,SAAS,CAAC,CAAC;IACnD,OAAO,CACL,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,SAAS,0BAA0B,EAAE,CAAC,CAAC;CACnD;AAqdD,wBAAgB,4CAA4C,CAC1D,OAAO,EAAE,6CAA6C,GACrD,4BAA4B,CAqM9B"}
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../src/activation.ts"],"names":[],"mappings":"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"}

package/dist/activation.js

@@ -128,21 +128,16 @@ function requireRecord(input) {
     }
     return value;
 }
-function validateStoredActivation(input, expectedTarget, expectedPreviousRevision, expectedPreviousReleaseIdentity) {
+function prepareValidatedActivation(input) {
     const value = requireRecord(input);
     if (value.kind !== 'hypequery-deployment-activation' || value.version !== 1) {
         throw new Error('Activation record kind or version is invalid.');
     }
     const target = validateTarget(value.target, 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE');
-    if (!targetsEqual(target, expectedTarget)) {
-        throw new Error('Activation record target is inconsistent.');
-    }
     const releaseIdentity = requireIdentity(value.releaseIdentity, 'Stored release identity', 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE');
     const previousRevision = requireNullableIdentity(value.previousRevision, 'Stored previous revision', 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE');
     const previousReleaseIdentity = requireNullableIdentity(value.previousReleaseIdentity, 'Stored previous release identity', 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE');
-    if (previousRevision !== expectedPreviousRevision
-        || previousReleaseIdentity !== expectedPreviousReleaseIdentity
-        || (previousRevision === null) !== (previousReleaseIdentity === null)) {
+    if ((previousRevision === null) !== (previousReleaseIdentity === null)) {
         throw new Error('Activation record predecessor is inconsistent.');
     }
     if (typeof value.activatedAt !== 'string') {
@@ -164,6 +159,21 @@ function validateStoredActivation(input, expectedTarget, expectedPreviousRevisio
     }
     return prepared;
 }
+/** Validate and recompute an immutable deployment activation record. */
+export function validateDeploymentActivationRecord(input) {
+    return prepareValidatedActivation(input).record;
+}
+function validateStoredActivation(input, expectedTarget, expectedPreviousRevision, expectedPreviousReleaseIdentity) {
+    const prepared = prepareValidatedActivation(input);
+    if (!targetsEqual(prepared.record.target, expectedTarget)) {
+        throw new Error('Activation record target is inconsistent.');
+    }
+    if (prepared.record.previousRevision !== expectedPreviousRevision
+        || prepared.record.previousReleaseIdentity !== expectedPreviousReleaseIdentity) {
+        throw new Error('Activation record predecessor is inconsistent.');
+    }
+    return prepared;
+}
 async function pathExists(filePath) {
     try {
         await lstat(filePath);
@@ -335,7 +345,7 @@ async function readStoredActivation(claimDirectory, target, previousRevision, pr
     }
     return prepared;
 }
-async function resolveHistory(targetDirectory, target) {
+async function visitHistory(targetDirectory, target, visitor) {
     try {
         await readCanonicalTarget(targetDirectory, target);
         const claimsDirectory = path.join(targetDirectory, CLAIMS_DIRECTORY);
@@ -347,7 +357,6 @@ async function resolveHistory(targetDirectory, target) {
         }
         const remaining = new Set(claimNames);
         const revisions = new Set();
-        const history = [];
         let previousRevision = null;
         let previousReleaseIdentity = null;
         // Following predecessor-named claims derives the head without trusting a
@@ -361,14 +370,13 @@ async function resolveHistory(targetDirectory, target) {
                 throw new Error('Deployment activation history contains a cycle.');
             }
             revisions.add(prepared.record.revision);
-            history.push(prepared.record);
+            visitor(prepared.record);
             previousRevision = prepared.record.revision;
             previousReleaseIdentity = prepared.record.releaseIdentity;
         }
         if (remaining.size > 0) {
             throw new Error('Deployment activation history contains unreachable claims.');
         }
-        return Object.freeze(history);
     }
     catch (error) {
         if (error instanceof DeploymentActivationError)
@@ -378,8 +386,53 @@ async function resolveHistory(targetDirectory, target) {
         throw activationError('HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE', 'Stored deployment activation history is invalid.', error);
     }
 }
-function currentActivation(history) {
-    return history[history.length - 1];
+async function resolveHistory(targetDirectory, target) {
+    const history = [];
+    await visitHistory(targetDirectory, target, record => { history.push(record); });
+    return Object.freeze(history);
+}
+async function resolveCurrent(targetDirectory, target) {
+    let current;
+    await visitHistory(targetDirectory, target, record => { current = record; });
+    return current;
+}
+function validateHistoryQuery(input) {
+    if (!Number.isSafeInteger(input?.limit) || input.limit < 1
+        || (input.before !== undefined && !IDENTITY_PATTERN.test(input.before))) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST', 'Deployment activation history query is invalid.');
+    }
+    return Object.freeze({
+        limit: input.limit,
+        ...(input.before === undefined ? {} : { before: input.before }),
+    });
+}
+async function resolveHistoryPage(targetDirectory, target, query) {
+    const retained = [];
+    let beforeFound = query.before === undefined;
+    let beforeReached = false;
+    await visitHistory(targetDirectory, target, record => {
+        if (record.revision === query.before) {
+            beforeFound = true;
+            beforeReached = true;
+            return;
+        }
+        if (beforeReached)
+            return;
+        retained.push(record);
+        if (retained.length > query.limit + 1)
+            retained.shift();
+    });
+    if (!beforeFound) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST', 'Deployment activation history cursor was not found.');
+    }
+    const hasOlder = retained.length > query.limit;
+    if (hasOlder)
+        retained.shift();
+    const activations = Object.freeze(retained);
+    return Object.freeze({
+        activations,
+        nextBefore: hasOlder ? activations[0].revision : null,
+    });
 }
 export function createFileSystemDeploymentActivationRegistry(options) {
     if (typeof options.directory !== 'string' || options.directory.length < 1) {
@@ -433,8 +486,37 @@ export function createFileSystemDeploymentActivationRegistry(options) {
             throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not read deployment activation history.', error);
         }
     }
-    async function current(target) {
-        return currentActivation(await history(target));
+    async function current(targetInput) {
+        const target = validateTarget(targetInput, 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        try {
+            const key = sha256(TARGET_IDENTITY_DOMAIN, targetCanonical(target));
+            const targetDirectory = path.join(await activationRoot(), key);
+            if (!await pathExists(targetDirectory))
+                return undefined;
+            return await resolveCurrent(targetDirectory, target);
+        }
+        catch (error) {
+            if (error instanceof DeploymentActivationError)
+                throw error;
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not read the current deployment activation.', error);
+        }
+    }
+    async function historyPage(targetInput, queryInput) {
+        const target = validateTarget(targetInput, 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        const query = validateHistoryQuery(queryInput);
+        try {
+            const key = sha256(TARGET_IDENTITY_DOMAIN, targetCanonical(target));
+            const targetDirectory = path.join(await activationRoot(), key);
+            if (!await pathExists(targetDirectory)) {
+                return Object.freeze({ activations: Object.freeze([]), nextBefore: null });
+            }
+            return await resolveHistoryPage(targetDirectory, target, query);
+        }
+        catch (error) {
+            if (error instanceof DeploymentActivationError)
+                throw error;
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not read deployment activation history.', error);
+        }
     }
     async function activate(request) {
         const target = validateTarget(request.target, 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
@@ -467,8 +549,7 @@ export function createFileSystemDeploymentActivationRegistry(options) {
         try {
             const activations = await activationRoot();
             const targetDirectory = await ensureTargetDirectory(activations, target);
-            const existingHistory = await resolveHistory(targetDirectory, target);
-            const existing = currentActivation(existingHistory);
+            const existing = await resolveCurrent(targetDirectory, target);
             if (existing?.releaseIdentity === releaseIdentity) {
                 return Object.freeze({ status: 'already-active', activation: existing });
             }
@@ -514,7 +595,7 @@ export function createFileSystemDeploymentActivationRegistry(options) {
             if (published) {
                 return Object.freeze({ status: 'activated', activation: prepared.record });
             }
-            const resolved = currentActivation(await resolveHistory(targetDirectory, target));
+            const resolved = await resolveCurrent(targetDirectory, target);
             if (resolved?.releaseIdentity === releaseIdentity) {
                 return Object.freeze({ status: 'already-active', activation: resolved });
             }
@@ -526,5 +607,5 @@ export function createFileSystemDeploymentActivationRegistry(options) {
             throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not update deployment activation state.', error);
         }
     }
-    return Object.freeze({ activate, current, history });
+    return Object.freeze({ activate, current, history, historyPage });
 }

package/dist/control-plane-adapters.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { DeploymentControlPlane } from './control-plane.js';
+export type DeploymentControlPlaneFetchHandler = (request: Request) => Promise<Response>;
+export type DeploymentControlPlaneNodeHandler = (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export declare function createDeploymentControlPlaneFetchHandler(controlPlane: DeploymentControlPlane): DeploymentControlPlaneFetchHandler;
+export declare function createDeploymentControlPlaneNodeHandler(controlPlane: DeploymentControlPlane): DeploymentControlPlaneNodeHandler;
+//# sourceMappingURL=control-plane-adapters.d.ts.map

package/dist/control-plane-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane-adapters.d.ts","sourceRoot":"","sources":["../src/control-plane-adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EACV,sBAAsB,EAGvB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,kCAAkC,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AACzF,MAAM,MAAM,iCAAiC,GAAG,CAC9C,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;AAkHnB,wBAAgB,wCAAwC,CACtD,YAAY,EAAE,sBAAsB,GACnC,kCAAkC,CAkBpC;AAED,wBAAgB,uCAAuC,CACrD,YAAY,EAAE,sBAAsB,GACnC,iCAAiC,CAgCnC"}

package/dist/control-plane-adapters.js

@@ -0,0 +1,163 @@
+const INTERNAL_BODY = '{"error":{"code":"HQ_CONTROL_INTERNAL","message":"The deployment control-plane request could not be processed."}}\n';
+const INTERNAL_RESPONSE = Object.freeze({
+    status: 500,
+    headers: Object.freeze({
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': String(Buffer.byteLength(INTERNAL_BODY)),
+        'cache-control': 'no-store',
+    }),
+    body: INTERNAL_BODY,
+});
+const FETCH_SINGLETON_HEADERS = new Set([
+    'authorization',
+    'content-length',
+    'content-type',
+    'idempotency-key',
+    'x-hypequery-bundle-identity',
+    'x-hypequery-release-identity',
+]);
+function queryParameters(search) {
+    const query = Object.create(null);
+    for (const [name, value] of search) {
+        const current = query[name];
+        if (current === undefined) {
+            query[name] = value;
+        }
+        else if (typeof current === 'string') {
+            query[name] = Object.freeze([current, value]);
+        }
+        else {
+            query[name] = Object.freeze([...current, value]);
+        }
+    }
+    return Object.freeze(query);
+}
+function fetchHeaders(input) {
+    const headers = Object.create(null);
+    for (const [name, value] of input.entries()) {
+        headers[name] = value;
+        if (FETCH_SINGLETON_HEADERS.has(name) && value.includes(',')) {
+            // Fetch combines duplicate header lines before exposing Headers. Reify a
+            // second case-insensitive entry so the core singleton guard rejects it.
+            headers[name.toUpperCase()] = value;
+        }
+    }
+    return Object.freeze(headers);
+}
+async function* fetchBody(input) {
+    if (input === null)
+        return;
+    const reader = input.getReader();
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function nodeHeaders(request) {
+    const headers = Object.create(null);
+    for (let index = 0; index < request.rawHeaders.length; index += 2) {
+        const name = request.rawHeaders[index].toLowerCase();
+        const value = request.rawHeaders[index + 1];
+        if (headers[name] === undefined) {
+            headers[name] = value;
+        }
+        else {
+            // Keep a second case-insensitive entry so the core duplicate-header guard
+            // observes duplicates instead of accepting Node's comma-joined value.
+            headers[name.toUpperCase()] = value;
+        }
+    }
+    return Object.freeze(headers);
+}
+async function* nodeBody(request) {
+    for await (const chunk of request) {
+        yield chunk instanceof Uint8Array ? chunk : Buffer.from(chunk);
+    }
+}
+function nodeHasBody(headers) {
+    return Object.entries(headers).some(([name, value]) => {
+        const normalized = name.toLowerCase();
+        return normalized === 'transfer-encoding'
+            || (normalized === 'content-length' && value !== '0');
+    });
+}
+function internalFetchResponse() {
+    return new Response(INTERNAL_RESPONSE.body, {
+        status: INTERNAL_RESPONSE.status,
+        headers: INTERNAL_RESPONSE.headers,
+    });
+}
+function sendNodeResponse(response, controlResponse) {
+    if (response.writableEnded || response.headersSent)
+        return;
+    response.statusCode = controlResponse.status;
+    for (const [name, value] of Object.entries(controlResponse.headers)) {
+        response.setHeader(name, value);
+    }
+    response.end(controlResponse.body);
+}
+export function createDeploymentControlPlaneFetchHandler(controlPlane) {
+    return async (request) => {
+        try {
+            const url = new URL(request.url);
+            const response = await controlPlane.handle({
+                method: request.method,
+                path: url.pathname,
+                query: queryParameters(url.searchParams),
+                headers: fetchHeaders(request.headers),
+                body: fetchBody(request.body),
+                hasBody: request.body !== null,
+                signal: request.signal,
+            });
+            return new Response(response.body, { status: response.status, headers: response.headers });
+        }
+        catch {
+            return internalFetchResponse();
+        }
+    };
+}
+export function createDeploymentControlPlaneNodeHandler(controlPlane) {
+    return async (request, response) => {
+        const abort = new AbortController();
+        const abortRequest = () => {
+            if (!request.complete)
+                abort.abort(new Error('The request connection was closed.'));
+        };
+        const abortResponse = () => {
+            if (!response.writableEnded)
+                abort.abort(new Error('The response connection was closed.'));
+        };
+        request.socket.once('close', abortRequest);
+        response.once('close', abortResponse);
+        if (request.destroyed && !request.complete)
+            abortRequest();
+        try {
+            const url = new URL(request.url ?? '/', 'http://deployment-control-plane.invalid');
+            const headers = nodeHeaders(request);
+            const controlResponse = await controlPlane.handle({
+                method: request.method ?? 'GET',
+                path: url.pathname,
+                query: queryParameters(url.searchParams),
+                headers,
+                body: nodeBody(request),
+                hasBody: nodeHasBody(headers),
+                signal: abort.signal,
+            });
+            sendNodeResponse(response, controlResponse);
+        }
+        catch {
+            sendNodeResponse(response, INTERNAL_RESPONSE);
+        }
+        finally {
+            request.socket.off('close', abortRequest);
+            response.off('close', abortResponse);
+        }
+    };
+}

package/dist/control-plane-limits.d.ts

@@ -0,0 +1,7 @@
+export interface DeploymentControlPlaneLimits {
+    readonly maxActivationRequestBytes: number;
+    readonly maxHistoryPageSize: number;
+}
+export declare const DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS: Readonly<DeploymentControlPlaneLimits>;
+export declare function resolveDeploymentControlPlaneLimits(input?: Partial<DeploymentControlPlaneLimits>): Readonly<DeploymentControlPlaneLimits>;
+//# sourceMappingURL=control-plane-limits.d.ts.map

package/dist/control-plane-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane-limits.d.ts","sourceRoot":"","sources":["../src/control-plane-limits.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,eAAO,MAAM,uCAAuC,EACpD,QAAQ,CAAC,4BAA4B,CAGnC,CAAC;AAEH,wBAAgB,mCAAmC,CACjD,KAAK,GAAE,OAAO,CAAC,4BAA4B,CAAM,GAChD,QAAQ,CAAC,4BAA4B,CAAC,CAcxC"}

package/dist/control-plane-limits.js

@@ -0,0 +1,18 @@
+export const DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS = Object.freeze({
+    maxActivationRequestBytes: 16 * 1024,
+    maxHistoryPageSize: 100,
+});
+export function resolveDeploymentControlPlaneLimits(input = {}) {
+    const limits = { ...DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS };
+    for (const key of Object.keys(limits)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1
+            || value > DEFAULT_DEPLOYMENT_CONTROL_PLANE_LIMITS[key]) {
+            throw new RangeError(`${key} must be a positive safe integer no greater than the control-plane v1 maximum`);
+        }
+        limits[key] = value;
+    }
+    return Object.freeze(limits);
+}

package/dist/control-plane.d.ts

@@ -0,0 +1,35 @@
+import { type ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+import { type DeploymentActivationRegistry } from './activation.js';
+import { type DeploymentControlPlaneLimits } from './control-plane-limits.js';
+import type { DeploymentAuthenticator, DeploymentIntake, DeploymentIntakeRequest, DeploymentIntakeResponse } from './types.js';
+export type DeploymentControlPlaneAction = 'activate' | 'read-current-activation' | 'read-activation-history';
+export interface DeploymentControlPlaneAuthorizationInput<Principal> {
+    readonly principal: Principal;
+    readonly action: DeploymentControlPlaneAction;
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentControlPlaneAuthorizer<Principal> {
+    authorize(input: DeploymentControlPlaneAuthorizationInput<Principal>): Promise<boolean>;
+}
+export interface DeploymentControlPlaneRequest extends DeploymentIntakeRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly query?: Readonly<Record<string, string | readonly string[] | undefined>>;
+    /** Set by transport adapters without consuming the request stream. */
+    readonly hasBody?: boolean;
+}
+export type DeploymentControlPlaneResponse = DeploymentIntakeResponse;
+export interface DeploymentControlPlane {
+    handle(request: DeploymentControlPlaneRequest): Promise<DeploymentControlPlaneResponse>;
+}
+export interface DeploymentControlPlaneOptions<Principal> {
+    readonly intake: DeploymentIntake;
+    readonly activations: DeploymentActivationRegistry;
+    readonly authenticator: DeploymentAuthenticator<Principal>;
+    readonly authorizer: DeploymentControlPlaneAuthorizer<Principal>;
+    readonly limits?: Partial<DeploymentControlPlaneLimits>;
+}
+export type DeploymentControlPlaneErrorCode = 'HQ_CONTROL_BAD_REQUEST' | 'HQ_CONTROL_UNAUTHENTICATED' | 'HQ_CONTROL_FORBIDDEN' | 'HQ_CONTROL_NOT_FOUND' | 'HQ_CONTROL_METHOD_NOT_ALLOWED' | 'HQ_CONTROL_TOO_LARGE' | 'HQ_CONTROL_RELEASE_NOT_FOUND' | 'HQ_CONTROL_RELEASE_UNAVAILABLE' | 'HQ_CONTROL_INTERNAL';
+export declare function createDeploymentControlPlane<Principal>(options: DeploymentControlPlaneOptions<Principal>): DeploymentControlPlane;
+//# sourceMappingURL=control-plane.d.ts.map

package/dist/control-plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-plane.d.ts","sourceRoot":"","sources":["../src/control-plane.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EACV,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAMpB,MAAM,MAAM,4BAA4B,GACpC,UAAU,GACV,yBAAyB,GACzB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,wCAAwC,CAAC,SAAS;IACjE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,4BAA4B,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,gCAAgC,CAAC,SAAS;IACzD,SAAS,CAAC,KAAK,EAAE,wCAAwC,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;IAClF,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,8BAA8B,GAAG,wBAAwB,CAAC;AAEtE,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,6BAA6B,CAAC,SAAS;IACtD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,4BAA4B,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,gCAAgC,CAAC,SAAS,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,4BAA4B,CAAC,CAAC;CACzD;AAED,MAAM,MAAM,+BAA+B,GACvC,wBAAwB,GACxB,4BAA4B,GAC5B,sBAAsB,GACtB,sBAAsB,GACtB,+BAA+B,GAC/B,sBAAsB,GACtB,8BAA8B,GAC9B,gCAAgC,GAChC,qBAAqB,CAAC;AA+X1B,wBAAgB,4BAA4B,CAAC,SAAS,EACpD,OAAO,EAAE,6BAA6B,CAAC,SAAS,CAAC,GAChD,sBAAsB,CAkHxB"}