@hypequery/deployment 0.1.0 → 0.2.0

package/README.md

@@ -65,4 +65,91 @@ 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.
+
 The package is ESM-only and requires Node.js 20 or newer.

package/dist/activation.d.ts

@@ -0,0 +1,51 @@
+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 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[]>;
+}
+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":"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"}

package/dist/activation.js

@@ -0,0 +1,530 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readdir, rename, rm, } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentReleaseEnvelope, validateProtocolDeploymentReleaseTarget, } from '@hypequery/protocol';
+const ACTIVATION_FILE = 'activation.json';
+const CLAIMS_DIRECTORY = 'claims';
+// Each predecessor has one filesystem slot for its successor. Renaming a
+// complete record into that slot is the cross-process compare-and-swap.
+const INITIAL_CLAIM = 'initial';
+const TARGET_FILE = 'target.json';
+const MAX_ACTIVATION_BYTES = 4096;
+const MAX_TARGET_BYTES = 1024;
+const IDENTITY_PATTERN = /^[0-9a-f]{64}$/;
+const ACTIVATION_IDENTITY_DOMAIN = 'hypequery:deployment-activation:v1\0';
+const TARGET_IDENTITY_DOMAIN = 'hypequery:deployment-target:v1\0';
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+export class DeploymentActivationError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentActivationError';
+        this.code = code;
+    }
+}
+function activationError(code, message, cause) {
+    return new DeploymentActivationError(code, message, { cause });
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function isOperationalFileSystemError(error) {
+    const code = errorCode(error);
+    return code !== undefined && !['EISDIR', 'ELOOP', 'ENOENT', 'ENOTDIR'].includes(code);
+}
+function sha256(domain, value) {
+    return createHash('sha256').update(domain).update(value).digest('hex');
+}
+function targetCanonical(target) {
+    return JSON.stringify({ project: target.project, environment: target.environment });
+}
+function targetsEqual(left, right) {
+    return left.project === right.project && left.environment === right.environment;
+}
+function validateTarget(input, code) {
+    try {
+        return validateProtocolDeploymentReleaseTarget(input);
+    }
+    catch (error) {
+        throw activationError(code, 'Deployment activation target is invalid.', error);
+    }
+}
+function requireIdentity(input, description, code) {
+    if (typeof input !== 'string' || !IDENTITY_PATTERN.test(input)) {
+        throw activationError(code, `${description} must be 64 lowercase hexadecimal characters.`);
+    }
+    return input;
+}
+function requireNullableIdentity(input, description, code) {
+    return input === null ? null : requireIdentity(input, description, code);
+}
+function activationPayloadCanonical(input) {
+    // Every value has already been reduced to a closed primitive shape, so this
+    // fixed construction order is also the canonical byte order persisted below.
+    return JSON.stringify({
+        kind: 'hypequery-deployment-activation',
+        version: 1,
+        target: {
+            project: input.target.project,
+            environment: input.target.environment,
+        },
+        releaseIdentity: input.releaseIdentity,
+        previousRevision: input.previousRevision,
+        previousReleaseIdentity: input.previousReleaseIdentity,
+        activatedAt: input.activatedAt,
+    });
+}
+function activationCanonical(record) {
+    return JSON.stringify({
+        kind: record.kind,
+        version: record.version,
+        revision: record.revision,
+        target: {
+            project: record.target.project,
+            environment: record.target.environment,
+        },
+        releaseIdentity: record.releaseIdentity,
+        previousRevision: record.previousRevision,
+        previousReleaseIdentity: record.previousReleaseIdentity,
+        activatedAt: record.activatedAt,
+    });
+}
+function prepareActivation(input) {
+    const payload = activationPayloadCanonical(input);
+    const revision = sha256(ACTIVATION_IDENTITY_DOMAIN, payload);
+    const record = Object.freeze({
+        kind: 'hypequery-deployment-activation',
+        version: 1,
+        revision,
+        target: input.target,
+        releaseIdentity: input.releaseIdentity,
+        previousRevision: input.previousRevision,
+        previousReleaseIdentity: input.previousReleaseIdentity,
+        activatedAt: input.activatedAt,
+    });
+    const canonical = activationCanonical(record);
+    return Object.freeze({ record, canonical, bytes: Buffer.from(canonical) });
+}
+function requireRecord(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Activation record must be an object.');
+    }
+    const value = input;
+    const expected = [
+        'activatedAt',
+        'kind',
+        'previousReleaseIdentity',
+        'previousRevision',
+        'releaseIdentity',
+        'revision',
+        'target',
+        'version',
+    ];
+    if (Object.keys(value).sort().join('\0') !== expected.join('\0')) {
+        throw new Error('Activation record fields are inconsistent.');
+    }
+    return value;
+}
+function validateStoredActivation(input, expectedTarget, expectedPreviousRevision, expectedPreviousReleaseIdentity) {
+    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)) {
+        throw new Error('Activation record predecessor is inconsistent.');
+    }
+    if (typeof value.activatedAt !== 'string') {
+        throw new Error('Activation timestamp is invalid.');
+    }
+    const timestamp = new Date(value.activatedAt);
+    if (!Number.isFinite(timestamp.valueOf()) || timestamp.toISOString() !== value.activatedAt) {
+        throw new Error('Activation timestamp is not a canonical ISO timestamp.');
+    }
+    const prepared = prepareActivation({
+        target,
+        releaseIdentity,
+        previousRevision,
+        previousReleaseIdentity,
+        activatedAt: value.activatedAt,
+    });
+    if (value.revision !== prepared.record.revision) {
+        throw new Error('Activation revision does not match its contents.');
+    }
+    return prepared;
+}
+async function pathExists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function requireRegularDirectory(directory, description) {
+    const stat = await lstat(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE', `${description} must be a regular directory: ${directory}`);
+    }
+}
+async function ensureRegularDirectory(directory, description) {
+    let created = false;
+    try {
+        created = await mkdir(directory, { recursive: true, mode: 0o700 }) !== undefined;
+    }
+    catch (error) {
+        if (errorCode(error) !== 'EEXIST')
+            throw error;
+    }
+    await requireRegularDirectory(directory, description);
+    return created;
+}
+async function syncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeExclusiveFile(filePath, bytes) {
+    const handle = await open(filePath, 'wx', 0o600);
+    try {
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const result = await handle.write(bytes, offset, bytes.byteLength - offset);
+            if (result.bytesWritten < 1)
+                throw new Error('Filesystem write made no progress.');
+            offset += result.bytesWritten;
+        }
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readRegularFile(filePath, maximumBytes) {
+    const initial = await lstat(filePath);
+    if (initial.isSymbolicLink() || !initial.isFile()
+        || initial.size < 1 || initial.size > maximumBytes) {
+        throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+    }
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes) {
+            throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+        }
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function withStagingDirectory(root, prefix, action) {
+    const staging = await mkdtemp(path.join(root, prefix));
+    let result;
+    let failure;
+    try {
+        result = await action(staging);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await rm(staging, { force: true, recursive: true });
+    }
+    catch (error) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', `Could not clean deployment activation staging directory: ${staging}`, failure ? new AggregateError([failure.error, error]) : error);
+    }
+    if (failure)
+        throw failure.error;
+    return result;
+}
+async function readCanonicalTarget(targetDirectory, expectedTarget) {
+    try {
+        await requireRegularDirectory(targetDirectory, 'Deployment activation target');
+        const entries = (await readdir(targetDirectory)).sort();
+        if (entries.join('\0') !== `${CLAIMS_DIRECTORY}\0${TARGET_FILE}`) {
+            throw new Error('Deployment activation target contains undeclared or missing entries.');
+        }
+        await requireRegularDirectory(path.join(targetDirectory, CLAIMS_DIRECTORY), 'Deployment activation claims');
+        const bytes = await readRegularFile(path.join(targetDirectory, TARGET_FILE), MAX_TARGET_BYTES);
+        let input;
+        try {
+            input = JSON.parse(textDecoder.decode(bytes));
+        }
+        catch (error) {
+            throw new Error('Stored deployment activation target is invalid JSON.', { cause: error });
+        }
+        const target = validateTarget(input, 'HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE');
+        if (!targetsEqual(target, expectedTarget)
+            || !Buffer.from(bytes).equals(Buffer.from(targetCanonical(target)))) {
+            throw new Error('Stored deployment activation target is inconsistent.');
+        }
+    }
+    catch (error) {
+        if (error instanceof DeploymentActivationError)
+            throw error;
+        if (isOperationalFileSystemError(error))
+            throw error;
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE', 'Stored deployment activation target is invalid.', error);
+    }
+}
+async function ensureTargetDirectory(activationsRoot, target) {
+    const canonical = targetCanonical(target);
+    const targetKey = sha256(TARGET_IDENTITY_DOMAIN, canonical);
+    const destination = path.join(activationsRoot, targetKey);
+    if (await pathExists(destination)) {
+        await readCanonicalTarget(destination, target);
+        return destination;
+    }
+    await withStagingDirectory(activationsRoot, '.target-staging-', async (staging) => {
+        await mkdir(path.join(staging, CLAIMS_DIRECTORY), { mode: 0o700 });
+        await writeExclusiveFile(path.join(staging, TARGET_FILE), Buffer.from(canonical));
+        await syncDirectory(path.join(staging, CLAIMS_DIRECTORY));
+        await syncDirectory(staging);
+        try {
+            await rename(staging, destination);
+        }
+        catch (error) {
+            if (!await pathExists(destination))
+                throw error;
+            await readCanonicalTarget(destination, target);
+            return;
+        }
+        await syncDirectory(activationsRoot);
+    });
+    await readCanonicalTarget(destination, target);
+    return destination;
+}
+async function readStoredActivation(claimDirectory, target, previousRevision, previousReleaseIdentity) {
+    await requireRegularDirectory(claimDirectory, 'Deployment activation claim');
+    const entries = await readdir(claimDirectory);
+    if (entries.length !== 1 || entries[0] !== ACTIVATION_FILE) {
+        throw new Error('Deployment activation claim contains undeclared or missing entries.');
+    }
+    const bytes = await readRegularFile(path.join(claimDirectory, ACTIVATION_FILE), MAX_ACTIVATION_BYTES);
+    let input;
+    try {
+        input = JSON.parse(textDecoder.decode(bytes));
+    }
+    catch (error) {
+        throw new Error('Stored deployment activation is invalid JSON.', { cause: error });
+    }
+    const prepared = validateStoredActivation(input, target, previousRevision, previousReleaseIdentity);
+    if (!Buffer.from(bytes).equals(Buffer.from(prepared.bytes))) {
+        throw new Error('Stored deployment activation is not canonical JSON.');
+    }
+    return prepared;
+}
+async function resolveHistory(targetDirectory, target) {
+    try {
+        await readCanonicalTarget(targetDirectory, target);
+        const claimsDirectory = path.join(targetDirectory, CLAIMS_DIRECTORY);
+        const claimNames = (await readdir(claimsDirectory)).sort();
+        for (const name of claimNames) {
+            if (name !== INITIAL_CLAIM && !IDENTITY_PATTERN.test(name)) {
+                throw new Error(`Deployment activation claim name is invalid: ${name}`);
+            }
+        }
+        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
+        // mutable pointer. The remaining-set check rejects orphaned branches.
+        for (;;) {
+            const claimName = previousRevision ?? INITIAL_CLAIM;
+            if (!remaining.delete(claimName))
+                break;
+            const prepared = await readStoredActivation(path.join(claimsDirectory, claimName), target, previousRevision, previousReleaseIdentity);
+            if (revisions.has(prepared.record.revision)) {
+                throw new Error('Deployment activation history contains a cycle.');
+            }
+            revisions.add(prepared.record.revision);
+            history.push(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)
+            throw error;
+        if (isOperationalFileSystemError(error))
+            throw error;
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CORRUPT_STATE', 'Stored deployment activation history is invalid.', error);
+    }
+}
+function currentActivation(history) {
+    return history[history.length - 1];
+}
+export function createFileSystemDeploymentActivationRegistry(options) {
+    if (typeof options.directory !== 'string' || options.directory.length < 1) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CONFIGURATION', 'Deployment activation directory is required.');
+    }
+    if (typeof options.releases?.read !== 'function') {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CONFIGURATION', 'A deployment release reader is required.');
+    }
+    const root = path.resolve(options.directory);
+    if (root === path.parse(root).root) {
+        throw activationError('HQ_DEPLOYMENT_ACTIVATION_CONFIGURATION', 'Deployment activation directory cannot be a filesystem root.');
+    }
+    const clock = options.clock ?? (() => new Date());
+    const activations = path.join(root, 'activations');
+    let initializationPromise;
+    async function initializeActivationRoot() {
+        const rootCreated = await ensureRegularDirectory(root, 'Deployment store root');
+        const activationsCreated = await ensureRegularDirectory(activations, 'Deployment activation store');
+        if (activationsCreated)
+            await syncDirectory(root);
+        if (rootCreated)
+            await syncDirectory(path.dirname(root));
+    }
+    async function activationRoot() {
+        const pending = initializationPromise ??= initializeActivationRoot();
+        try {
+            await pending;
+        }
+        catch (error) {
+            if (initializationPromise === pending)
+                initializationPromise = undefined;
+            throw error;
+        }
+        await requireRegularDirectory(root, 'Deployment store root');
+        await requireRegularDirectory(activations, 'Deployment activation store');
+        return activations;
+    }
+    async function history(targetInput) {
+        const target = validateTarget(targetInput, 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        try {
+            const activations = await activationRoot();
+            const key = sha256(TARGET_IDENTITY_DOMAIN, targetCanonical(target));
+            const targetDirectory = path.join(activations, key);
+            if (!await pathExists(targetDirectory))
+                return Object.freeze([]);
+            return await resolveHistory(targetDirectory, target);
+        }
+        catch (error) {
+            if (error instanceof DeploymentActivationError)
+                throw error;
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not read deployment activation history.', error);
+        }
+    }
+    async function current(target) {
+        return currentActivation(await history(target));
+    }
+    async function activate(request) {
+        const target = validateTarget(request.target, 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        const releaseIdentity = requireIdentity(request.releaseIdentity, 'Deployment release identity', 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        const expectedRevision = requireNullableIdentity(request.expectedRevision, 'Expected deployment activation revision', 'HQ_DEPLOYMENT_ACTIVATION_INVALID_REQUEST');
+        let storedRelease;
+        try {
+            storedRelease = await options.releases.read(releaseIdentity);
+        }
+        catch (error) {
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_RELEASE_UNAVAILABLE', `Could not verify deployment release before activation: ${releaseIdentity}`, error);
+        }
+        if (!storedRelease) {
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_RELEASE_NOT_FOUND', `Deployment release is not stored: ${releaseIdentity}`);
+        }
+        let verifiedRelease;
+        try {
+            verifiedRelease = prepareProtocolDeploymentReleaseEnvelope(storedRelease.release);
+        }
+        catch (error) {
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_RELEASE_UNAVAILABLE', `Stored deployment release is invalid: ${releaseIdentity}`, error);
+        }
+        if (storedRelease.releaseIdentity !== releaseIdentity
+            || verifiedRelease.identity !== releaseIdentity) {
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_RELEASE_UNAVAILABLE', `Stored deployment release identity is inconsistent: ${releaseIdentity}`);
+        }
+        if (!targetsEqual(verifiedRelease.release.target, target)) {
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_TARGET_MISMATCH', 'Deployment release target does not match the activation target.');
+        }
+        try {
+            const activations = await activationRoot();
+            const targetDirectory = await ensureTargetDirectory(activations, target);
+            const existingHistory = await resolveHistory(targetDirectory, target);
+            const existing = currentActivation(existingHistory);
+            if (existing?.releaseIdentity === releaseIdentity) {
+                return Object.freeze({ status: 'already-active', activation: existing });
+            }
+            if ((existing?.revision ?? null) !== expectedRevision) {
+                return Object.freeze({ status: 'conflict', current: existing ?? null });
+            }
+            let now;
+            try {
+                now = clock();
+                if (!(now instanceof Date) || !Number.isFinite(now.valueOf()))
+                    throw new Error('Invalid date.');
+            }
+            catch (error) {
+                throw activationError('HQ_DEPLOYMENT_ACTIVATION_CONFIGURATION', 'Deployment activation clock returned an invalid value.', error);
+            }
+            const prepared = prepareActivation({
+                target,
+                releaseIdentity,
+                previousRevision: existing?.revision ?? null,
+                previousReleaseIdentity: existing?.releaseIdentity ?? null,
+                activatedAt: now.toISOString(),
+            });
+            const claimsDirectory = path.join(targetDirectory, CLAIMS_DIRECTORY);
+            const claimName = existing?.revision ?? INITIAL_CLAIM;
+            const destination = path.join(claimsDirectory, claimName);
+            const published = await withStagingDirectory(
+            // Staging lives outside the exact target directory, so interrupted
+            // writers are invisible to history readers until the atomic rename.
+            activations, '.activation-staging-', async (staging) => {
+                await writeExclusiveFile(path.join(staging, ACTIVATION_FILE), prepared.bytes);
+                await syncDirectory(staging);
+                try {
+                    await rename(staging, destination);
+                }
+                catch (error) {
+                    if (!await pathExists(destination))
+                        throw error;
+                    return false;
+                }
+                await syncDirectory(claimsDirectory);
+                return true;
+            });
+            if (published) {
+                return Object.freeze({ status: 'activated', activation: prepared.record });
+            }
+            const resolved = currentActivation(await resolveHistory(targetDirectory, target));
+            if (resolved?.releaseIdentity === releaseIdentity) {
+                return Object.freeze({ status: 'already-active', activation: resolved });
+            }
+            return Object.freeze({ status: 'conflict', current: resolved ?? null });
+        }
+        catch (error) {
+            if (error instanceof DeploymentActivationError)
+                throw error;
+            throw activationError('HQ_DEPLOYMENT_ACTIVATION_IO', 'Could not update deployment activation state.', error);
+        }
+    }
+    return Object.freeze({ activate, current, history });
+}

package/dist/filesystem-store.d.ts

@@ -0,0 +1,25 @@
+import { type ProtocolDeploymentReleaseEnvelope } from '@hypequery/protocol';
+import { type VerifiedDeploymentBundle } from './bundle.js';
+import type { DeploymentSubmissionStore } from './types.js';
+export type FileSystemDeploymentStoreErrorCode = 'HQ_DEPLOYMENT_STORE_CONFIGURATION' | 'HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION' | 'HQ_DEPLOYMENT_STORE_CORRUPT_STATE' | 'HQ_DEPLOYMENT_STORE_IO';
+export declare class FileSystemDeploymentStoreError extends Error {
+    readonly code: FileSystemDeploymentStoreErrorCode;
+    constructor(code: FileSystemDeploymentStoreErrorCode, message: string, options?: {
+        readonly cause?: unknown;
+    });
+}
+export interface FileSystemDeploymentSubmissionStoreOptions {
+    readonly directory: string;
+}
+export interface StoredDeploymentSubmission {
+    readonly releaseDirectory: string;
+    readonly release: ProtocolDeploymentReleaseEnvelope;
+    readonly releaseCanonical: string;
+    readonly releaseIdentity: string;
+    readonly bundle: VerifiedDeploymentBundle;
+}
+export interface FileSystemDeploymentSubmissionStore<Principal> extends DeploymentSubmissionStore<Principal> {
+    read(releaseIdentity: string): Promise<StoredDeploymentSubmission | undefined>;
+}
+export declare function createFileSystemDeploymentSubmissionStore<Principal = unknown>(options: FileSystemDeploymentSubmissionStoreOptions): FileSystemDeploymentSubmissionStore<Principal>;
+//# sourceMappingURL=filesystem-store.d.ts.map

package/dist/filesystem-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-store.d.ts","sourceRoot":"","sources":["../src/filesystem-store.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,iCAAiC,EACvC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,yBAAyB,EAE1B,MAAM,YAAY,CAAC;AASpB,MAAM,MAAM,kCAAkC,GAC1C,mCAAmC,GACnC,wCAAwC,GACxC,mCAAmC,GACnC,wBAAwB,CAAC;AAE7B,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,IAAI,EAAE,kCAAkC,CAAC;gBAGhD,IAAI,EAAE,kCAAkC,EACxC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAM7C;AAED,MAAM,WAAW,0CAA0C;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED,MAAM,WAAW,mCAAmC,CAAC,SAAS,CAC5D,SAAQ,yBAAyB,CAAC,SAAS,CAAC;IAC5C,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,GAAG,SAAS,CAAC,CAAC;CAChF;AAobD,wBAAgB,yCAAyC,CAAC,SAAS,GAAG,OAAO,EAC3E,OAAO,EAAE,0CAA0C,GAClD,mCAAmC,CAAC,SAAS,CAAC,CAkHhD"}

package/dist/filesystem-store.js

@@ -0,0 +1,418 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, mkdtemp, open, readdir, rename, rm, } from 'node:fs/promises';
+import path from 'node:path';
+import { prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
+import { DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
+const RELEASE_FILE = 'release.json';
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_RELEASE_BYTES = 16 * 1024;
+const COPY_BUFFER_BYTES = 64 * 1024;
+const IDENTITY_PATTERN = /^[0-9a-f]{64}$/;
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+export class FileSystemDeploymentStoreError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'FileSystemDeploymentStoreError';
+        this.code = code;
+    }
+}
+function storeError(code, message, cause) {
+    return new FileSystemDeploymentStoreError(code, message, { cause });
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+async function pathExists(filePath) {
+    try {
+        await lstat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function requireRegularDirectory(directory, description, code = 'HQ_DEPLOYMENT_STORE_CORRUPT_STATE') {
+    const stat = await lstat(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw storeError(code, `${description} must be a regular directory: ${directory}`);
+    }
+}
+async function ensureRegularStoreDirectory(directory, description) {
+    let created = false;
+    try {
+        created = await mkdir(directory, { recursive: true, mode: 0o700 }) !== undefined;
+    }
+    catch (error) {
+        if (errorCode(error) !== 'EEXIST')
+            throw error;
+    }
+    await requireRegularDirectory(directory, description);
+    return created;
+}
+async function ensureStoreDirectories(root) {
+    const rootCreated = await ensureRegularStoreDirectory(root, 'Deployment store root');
+    const bundles = path.join(root, 'bundles');
+    const releases = path.join(root, 'releases');
+    const bundlesCreated = await ensureRegularStoreDirectory(bundles, 'Deployment bundle store');
+    const releasesCreated = await ensureRegularStoreDirectory(releases, 'Deployment release store');
+    if (bundlesCreated || releasesCreated)
+        await syncDirectory(root);
+    if (rootCreated)
+        await syncDirectory(path.dirname(root));
+    return Object.freeze({ bundles, releases });
+}
+async function syncDirectory(directory) {
+    if (process.platform === 'win32')
+        return;
+    const handle = await open(directory, constants.O_RDONLY);
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writeAll(handle, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        const result = await handle.write(bytes, offset, bytes.byteLength - offset);
+        if (result.bytesWritten < 1)
+            throw new Error('Filesystem write made no progress.');
+        offset += result.bytesWritten;
+    }
+}
+async function writeExclusiveFile(filePath, bytes) {
+    const handle = await open(filePath, 'wx', 0o600);
+    try {
+        await writeAll(handle, bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function copyRegularFile(sourcePath, destinationPath, maximumBytes, expectedBytes) {
+    const initial = await lstat(sourcePath);
+    if (initial.isSymbolicLink() || !initial.isFile()) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry is no longer a regular file: ${sourcePath}`);
+    }
+    if (initial.size < 1 || initial.size > maximumBytes
+        || (expectedBytes !== undefined && initial.size !== expectedBytes)) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry changed before persistence: ${sourcePath}`);
+    }
+    let source;
+    let destination;
+    try {
+        source = await open(sourcePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await source.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes
+            || (expectedBytes !== undefined && stat.size !== expectedBytes)) {
+            throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry changed before persistence: ${sourcePath}`);
+        }
+        destination = await open(destinationPath, 'wx', 0o600);
+        const buffer = Buffer.allocUnsafe(COPY_BUFFER_BYTES);
+        let total = 0;
+        for (;;) {
+            const { bytesRead } = await source.read(buffer, 0, buffer.byteLength, null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maximumBytes || (expectedBytes !== undefined && total > expectedBytes)) {
+                throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry changed before persistence: ${sourcePath}`);
+            }
+            await writeAll(destination, buffer.subarray(0, bytesRead));
+        }
+        if (expectedBytes !== undefined && total !== expectedBytes) {
+            throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry changed before persistence: ${sourcePath}`);
+        }
+        await destination.sync();
+    }
+    catch (error) {
+        if (errorCode(error) === 'ELOOP') {
+            throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', `Verified bundle entry became a symbolic link: ${sourcePath}`, error);
+        }
+        throw error;
+    }
+    finally {
+        try {
+            await destination?.close();
+        }
+        finally {
+            await source?.close();
+        }
+    }
+}
+function bundleFilePaths(bundle) {
+    return Object.freeze([
+        { path: DEPLOYMENT_BUNDLE_MANIFEST },
+        {
+            path: bundle.manifest.deployment.path,
+            byteLength: bundle.manifest.deployment.byteLength,
+        },
+        ...bundle.manifest.artifacts.map(artifact => ({
+            path: artifact.path,
+            byteLength: artifact.byteLength,
+        })),
+    ]);
+}
+async function syncBundleDirectories(bundleRoot, files) {
+    const directories = new Set([bundleRoot]);
+    for (const file of files) {
+        const segments = file.path.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            directories.add(path.join(bundleRoot, ...segments.slice(0, index)));
+        }
+    }
+    const ordered = [...directories].sort((left, right) => (right.split(path.sep).length - left.split(path.sep).length));
+    for (const directory of ordered)
+        await syncDirectory(directory);
+}
+async function copyBundleToStaging(bundle, staging) {
+    await requireRegularDirectory(bundle.directory, 'Verified deployment bundle', 'HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION');
+    const files = bundleFilePaths(bundle);
+    for (const file of files) {
+        const destination = path.join(staging, ...file.path.split('/'));
+        await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+        await copyRegularFile(path.join(bundle.directory, ...file.path.split('/')), destination, file.byteLength ?? MAX_MANIFEST_BYTES, file.byteLength);
+    }
+    await syncBundleDirectories(staging, files);
+    let verified;
+    try {
+        verified = await verifyDeploymentBundle(staging);
+    }
+    catch (error) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', 'Deployment bundle changed before it could be persisted.', error);
+    }
+    if (verified.identity !== bundle.identity) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', 'Persisted bundle identity does not match the verified submission.');
+    }
+    return verified;
+}
+async function readRegularFile(filePath, maximumBytes) {
+    const initial = await lstat(filePath);
+    if (initial.isSymbolicLink() || !initial.isFile()
+        || initial.size < 1 || initial.size > maximumBytes) {
+        throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+    }
+    const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size < 1 || stat.size > maximumBytes) {
+            throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+        }
+        const buffer = Buffer.allocUnsafe(Math.min(COPY_BUFFER_BYTES, maximumBytes + 1));
+        const chunks = [];
+        let total = 0;
+        while (total <= maximumBytes) {
+            const remaining = maximumBytes + 1 - total;
+            const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.byteLength, remaining), null);
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maximumBytes) {
+                throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+            }
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+        if (total < 1) {
+            throw new Error(`Stored entry is not a bounded regular file: ${filePath}`);
+        }
+        return Buffer.concat(chunks, total);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readStoredRelease(releaseDirectory, expectedIdentity) {
+    await requireRegularDirectory(releaseDirectory, 'Stored deployment release');
+    const entries = (await readdir(releaseDirectory)).sort();
+    if (entries.length !== 1 || entries[0] !== RELEASE_FILE) {
+        throw new Error('Stored deployment release contains undeclared or missing entries.');
+    }
+    const bytes = await readRegularFile(path.join(releaseDirectory, RELEASE_FILE), MAX_RELEASE_BYTES);
+    let input;
+    try {
+        input = JSON.parse(textDecoder.decode(bytes));
+    }
+    catch (error) {
+        throw new Error('Stored deployment release is not valid UTF-8 JSON.', { cause: error });
+    }
+    const prepared = prepareProtocolDeploymentReleaseEnvelope(input);
+    if (prepared.identity !== expectedIdentity
+        || !Buffer.from(bytes).equals(Buffer.from(prepared.bytes))) {
+        throw new Error('Stored deployment release identity or canonical bytes do not match.');
+    }
+    return Object.freeze({ release: prepared.release, canonical: prepared.canonical });
+}
+async function verifyStoredBundle(bundleDirectory, expectedIdentity) {
+    let bundle;
+    try {
+        bundle = await verifyDeploymentBundle(bundleDirectory);
+    }
+    catch (error) {
+        throw storeError('HQ_DEPLOYMENT_STORE_CORRUPT_STATE', `Stored deployment bundle is invalid: ${expectedIdentity}`, error);
+    }
+    if (bundle.identity !== expectedIdentity) {
+        throw storeError('HQ_DEPLOYMENT_STORE_CORRUPT_STATE', `Stored deployment bundle identity is inconsistent: ${expectedIdentity}`);
+    }
+    return bundle;
+}
+async function ensureStoredBundle(root, bundlesDirectory, bundle) {
+    const destination = path.join(bundlesDirectory, bundle.identity);
+    if (await pathExists(destination)) {
+        await verifyStoredBundle(destination, bundle.identity);
+        return;
+    }
+    await withStagingDirectory(root, '.bundle-staging-', async (staging) => {
+        await copyBundleToStaging(bundle, staging);
+        await publishDirectory(staging, destination, bundlesDirectory, async () => { await verifyStoredBundle(destination, bundle.identity); });
+    });
+}
+async function publishDirectory(staging, destination, parent, verifyExisting) {
+    if (await pathExists(destination)) {
+        await verifyExisting();
+        return false;
+    }
+    try {
+        await rename(staging, destination);
+    }
+    catch (error) {
+        if (!await pathExists(destination))
+            throw error;
+        await verifyExisting();
+        return false;
+    }
+    await syncDirectory(parent);
+    return true;
+}
+async function withStagingDirectory(root, prefix, action) {
+    const staging = await mkdtemp(path.join(root, prefix));
+    let result;
+    let failure;
+    try {
+        result = await action(staging);
+    }
+    catch (error) {
+        failure = { error };
+    }
+    try {
+        await rm(staging, { force: true, recursive: true });
+    }
+    catch (error) {
+        throw storeError('HQ_DEPLOYMENT_STORE_IO', `Could not clean deployment store staging directory: ${staging}`, failure ? new AggregateError([failure.error, error]) : error);
+    }
+    if (failure)
+        throw failure.error;
+    return result;
+}
+function prepareSubmission(submission) {
+    let prepared;
+    try {
+        prepared = prepareProtocolDeploymentReleaseEnvelope(submission.release);
+    }
+    catch (error) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', 'Deployment release is invalid.', error);
+    }
+    if (prepared.identity !== submission.releaseIdentity
+        || prepared.canonical !== submission.releaseCanonical
+        || prepared.release.bundleIdentity !== submission.bundle.identity) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', 'Deployment submission identities or canonical release bytes are inconsistent.');
+    }
+    return prepared;
+}
+function requireIdentity(input) {
+    if (!IDENTITY_PATTERN.test(input)) {
+        throw storeError('HQ_DEPLOYMENT_STORE_INVALID_SUBMISSION', 'Deployment release identity must be 64 lowercase hexadecimal characters.');
+    }
+    return input;
+}
+export function createFileSystemDeploymentSubmissionStore(options) {
+    if (typeof options.directory !== 'string' || options.directory.length < 1) {
+        throw storeError('HQ_DEPLOYMENT_STORE_CONFIGURATION', 'Deployment store directory is required.');
+    }
+    const root = path.resolve(options.directory);
+    if (root === path.parse(root).root) {
+        throw storeError('HQ_DEPLOYMENT_STORE_CONFIGURATION', 'Deployment store directory cannot be a filesystem root.');
+    }
+    let directoriesPromise;
+    async function storeDirectories() {
+        const pending = directoriesPromise ??= ensureStoreDirectories(root);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            if (directoriesPromise === pending)
+                directoriesPromise = undefined;
+            throw error;
+        }
+    }
+    async function read(releaseIdentity) {
+        const identity = requireIdentity(releaseIdentity);
+        let directories;
+        try {
+            directories = await storeDirectories();
+            const releaseDirectory = path.join(directories.releases, identity);
+            if (!await pathExists(releaseDirectory))
+                return undefined;
+            let storedRelease;
+            try {
+                storedRelease = await readStoredRelease(releaseDirectory, identity);
+            }
+            catch (error) {
+                if (error instanceof FileSystemDeploymentStoreError)
+                    throw error;
+                throw storeError('HQ_DEPLOYMENT_STORE_CORRUPT_STATE', `Stored deployment release is invalid: ${identity}`, error);
+            }
+            const bundle = await verifyStoredBundle(path.join(directories.bundles, storedRelease.release.bundleIdentity), storedRelease.release.bundleIdentity);
+            return Object.freeze({
+                releaseDirectory,
+                release: storedRelease.release,
+                releaseCanonical: storedRelease.canonical,
+                releaseIdentity: identity,
+                bundle,
+            });
+        }
+        catch (error) {
+            if (error instanceof FileSystemDeploymentStoreError)
+                throw error;
+            throw storeError('HQ_DEPLOYMENT_STORE_IO', `Could not read deployment release from ${root}.`, error);
+        }
+    }
+    async function accept(submission) {
+        const prepared = prepareSubmission(submission);
+        try {
+            const directories = await storeDirectories();
+            await ensureStoredBundle(root, directories.bundles, submission.bundle);
+            const releaseDestination = path.join(directories.releases, submission.releaseIdentity);
+            const published = await withStagingDirectory(root, '.release-staging-', async (staging) => {
+                await writeExclusiveFile(path.join(staging, RELEASE_FILE), prepared.bytes);
+                await syncDirectory(staging);
+                return publishDirectory(staging, releaseDestination, directories.releases, async () => {
+                    let existing;
+                    try {
+                        existing = await readStoredRelease(releaseDestination, submission.releaseIdentity);
+                    }
+                    catch (error) {
+                        throw storeError('HQ_DEPLOYMENT_STORE_CORRUPT_STATE', `Stored deployment release is invalid: ${submission.releaseIdentity}`, error);
+                    }
+                    if (existing.canonical !== prepared.canonical
+                        || existing.release.bundleIdentity !== submission.bundle.identity) {
+                        throw storeError('HQ_DEPLOYMENT_STORE_CORRUPT_STATE', `Stored deployment release conflicts with its identity: ${submission.releaseIdentity}`);
+                    }
+                });
+            });
+            return published ? 'accepted' : 'already-exists';
+        }
+        catch (error) {
+            if (error instanceof FileSystemDeploymentStoreError)
+                throw error;
+            throw storeError('HQ_DEPLOYMENT_STORE_IO', `Could not persist deployment submission in ${root}.`, error);
+        }
+    }
+    return Object.freeze({ accept, read });
+}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
+export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, } from './activation.js';
+export type { DeploymentActivationErrorCode, DeploymentActivationRegistry, DeploymentActivationRelease, DeploymentActivationRecord, DeploymentActivationRequest, DeploymentActivationResult, DeploymentReleaseReader, FileSystemDeploymentActivationRegistryOptions, } from './activation.js';
 export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
 export type { VerifiedDeploymentBundle } from './bundle.js';
 export { DeploymentIntakeError, } from './errors.js';
 export type { DeploymentIntakeErrorCode } from './errors.js';
+export { createFileSystemDeploymentSubmissionStore, FileSystemDeploymentStoreError, } from './filesystem-store.js';
+export type { FileSystemDeploymentStoreErrorCode, FileSystemDeploymentSubmissionStore, FileSystemDeploymentSubmissionStoreOptions, StoredDeploymentSubmission, } from './filesystem-store.js';
 export { createDeploymentIntake, } from './intake.js';
 export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';
 export type { DeploymentIntakeLimits } from './limits.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,4 +1,6 @@
+export { createFileSystemDeploymentActivationRegistry, DeploymentActivationError, } from './activation.js';
 export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
 export { DeploymentIntakeError, } from './errors.js';
+export { createFileSystemDeploymentSubmissionStore, FileSystemDeploymentStoreError, } from './filesystem-store.js';
 export { createDeploymentIntake, } from './intake.js';
 export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/deployment",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Provider-neutral deployment verification and intake for Hypequery",
   "license": "Apache-2.0",
   "type": "module",
@@ -18,7 +18,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@hypequery/protocol": "0.5.0"
+    "@hypequery/protocol": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.5.0",