@hypequery/deployment 0.1.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
@@ -65,4 +65,184 @@ filesystem. It rejects symbolic links and undeclared entries, enforces byte
 limits, recomputes every hash and identity, and returns an immutable verified
 snapshot.
 
+## Filesystem store
+
+`createFileSystemDeploymentSubmissionStore` is the reference durable store for
+a single host. It copies verified bundle bytes out of temporary intake storage,
+revalidates the copy, and atomically publishes the release only after its bundle
+is durable. Replaying the same release returns `already-exists` after the stored
+state has been fully revalidated.
+
+```ts
+import {
+  createDeploymentIntake,
+  createFileSystemDeploymentSubmissionStore,
+} from '@hypequery/deployment';
+
+const store = createFileSystemDeploymentSubmissionStore({
+  directory: '/var/lib/hypequery/deployments',
+});
+
+const intake = createDeploymentIntake({
+  authenticator,
+  authorizer,
+  store,
+});
+```
+
+The closed layout is content-addressed:
+
+```text
+<directory>/
+  bundles/<bundle identity>/...
+  releases/<release identity>/release.json
+```
+
+Bundle directories are published before release directories. A crash can leave
+an unreferenced bundle that a later submission safely reuses, but cannot expose
+a release whose bundle is incomplete. Files and directories are opened without
+following symbolic links where Node exposes that facility, file contents and
+directory entries are revalidated on reads and replays, and temporary staging
+directories are removed after success or failure.
+
+The configured directory is an operator-controlled local trust boundary. This
+store does not provide remote replication, activation, lifecycle state, or
+protection from an administrator modifying its files. `read(releaseIdentity)`
+returns only a completely revalidated stored submission.
+
+## Activation registry
+
+`createFileSystemDeploymentActivationRegistry` adds explicit target activation
+without changing accepted release or bundle bytes. The registry requires a
+release reader that completely revalidates an accepted release and its closed
+bundle before returning it; the filesystem submission store satisfies that
+contract directly.
+
+```ts
+import {
+  createFileSystemDeploymentActivationRegistry,
+  createFileSystemDeploymentSubmissionStore,
+} from '@hypequery/deployment';
+
+const directory = '/var/lib/hypequery/deployments';
+const releases = createFileSystemDeploymentSubmissionStore({ directory });
+const activations = createFileSystemDeploymentActivationRegistry({
+  directory,
+  releases,
+});
+
+const target = { project: 'analytics', environment: 'production' };
+const current = await activations.current(target);
+const result = await activations.activate({
+  target,
+  releaseIdentity,
+  expectedRevision: current?.revision ?? null,
+});
+```
+
+`expectedRevision` is a compare-and-swap precondition. A different active
+revision returns `conflict`; requesting the release that is already active
+returns `already-active`. Activating an older accepted release performs a
+rollback through the same operation and produces a new revision, so stale
+pre-rollback callers cannot pass the comparison after an ABA sequence.
+
+The filesystem implementation stores an immutable, domain-separated activation
+record for every transition and derives the current release by verifying the
+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

@@ -0,0 +1,62 @@
+import { type ProtocolDeploymentReleaseEnvelope, type ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+export type DeploymentActivationErrorCode = 'HQ_DEPLOYMENT_ACTIVATION_CONFIGURATION' | 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST' | 'HQ_DEPLOYMENT_ACTIVATION_RELEASE_NOT_FOUND' | 'HQ_DEPLOYMENT_ACTIVATION_RELEASE_UNAVAILABLE' | 'HQ_DEPLOYMENT_ACTIVATION_TARGET_MISMATCH' | 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE' | 'HQ_DEPLOYMENT_ACTIVATION_IO';
+export declare class DeploymentActivationError extends Error {
+    readonly code: DeploymentActivationErrorCode;
+    constructor(code: DeploymentActivationErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface DeploymentActivationRecord {
+    readonly kind: 'hypequery-deployment-activation';
+    readonly version: 1;
+    readonly revision: string;
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly releaseIdentity: string;
+    readonly previousRevision: string | null;
+    readonly previousReleaseIdentity: string | null;
+    readonly activatedAt: string;
+}
+export interface DeploymentActivationRequest {
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly releaseIdentity: string;
+    /** `null` means the caller expects this target to have no active release. */
+    readonly expectedRevision: string | null;
+}
+export type DeploymentActivationResult = {
+    readonly status: 'activated' | 'already-active';
+    readonly activation: DeploymentActivationRecord;
+} | {
+    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;
+}
+export interface DeploymentReleaseReader {
+    /** Return only accepted releases whose release and closed bundle remain completely valid. */
+    read(releaseIdentity: string): Promise<DeploymentActivationRelease | undefined>;
+}
+export interface FileSystemDeploymentActivationRegistryOptions {
+    readonly directory: string;
+    readonly releases: DeploymentReleaseReader;
+    readonly clock?: () => Date;
+}
+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

@@ -0,0 +1 @@
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../src/activation.ts"],"names":[],"mappings":"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"}