@deksden-com/dd-flow-cli 0.9.0-beta.135 → 0.9.0-beta.136

package/dist/services/release-cache.js

@@ -0,0 +1,142 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+import { verifyReleaseArchive } from "./release-manifest.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("cache_integrity", "Release cache cannot be published", 1, { reason, phase: "cache_publication", effect: "no_effect", help: "setup" });
+}
+function directory(target) {
+    if (fs.existsSync(target)) {
+        if (!fs.lstatSync(target).isDirectory())
+            refuse("unsafe_cache_directory");
+        return;
+    }
+    const parent = path.dirname(target);
+    if (parent !== target)
+        directory(parent);
+    fs.mkdirSync(target, { mode: 0o700 });
+}
+function write(target, bytes, mode) {
+    const fd = fs.openSync(target, "wx", mode);
+    try {
+        fs.writeFileSync(fd, bytes);
+        fs.fchmodSync(fd, mode);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function retained(target, archive, entries) {
+    if (!fs.lstatSync(target).isDirectory())
+        refuse("unsafe_retained_cache");
+    const archiveFile = path.join(target, "archive.tgz");
+    if (!fs.lstatSync(archiveFile).isFile())
+        refuse("unsafe_retained_cache");
+    if (fs.readdirSync(target).sort().join("/") !== "archive.tgz/payload/receipt.json")
+        refuse("retained_cache_changed");
+    const marker = path.join(target, "receipt.json"), payload = path.join(target, "payload");
+    if (!fs.lstatSync(marker).isFile() || fs.readFileSync(marker, "utf8") !== JSON.stringify({ sha256: archive.sha256, bytes: archive.bytes }))
+        refuse("same_version_different_bytes");
+    verifyReleaseArchive(archive, fs.readFileSync(archiveFile));
+    const expected = new Map();
+    const directories = new Set();
+    for (const entry of entries) {
+        expected.set(entry.path, entry);
+        const parts = entry.path.split("/");
+        for (let index = 1; index < parts.length; index++)
+            directories.add(parts.slice(0, index).join("/"));
+    }
+    const seen = new Set();
+    const visit = (root, relative) => {
+        if (!fs.lstatSync(root).isDirectory())
+            refuse("unsafe_retained_cache");
+        for (const name of fs.readdirSync(root)) {
+            const logical = relative ? `${relative}/${name}` : name, full = path.join(root, name), stat = fs.lstatSync(full);
+            const entry = expected.get(logical);
+            if (stat.isDirectory()) {
+                if (entry?.kind === "file" || (!entry && !directories.has(logical)))
+                    refuse("retained_cache_changed");
+                if (entry)
+                    seen.add(logical);
+                visit(full, logical);
+            }
+            else {
+                if (!stat.isFile() || entry?.kind !== "file" || stat.size !== entry.bytes.length || digest(fs.readFileSync(full)) !== digest(entry.bytes) || (stat.mode & 0o111) !== (entry.mode & 0o111))
+                    refuse("retained_cache_changed");
+                seen.add(logical);
+            }
+        }
+    };
+    visit(payload, "");
+    if (seen.size !== entries.length)
+        refuse("retained_cache_changed");
+}
+/** Verify retained compressed and expanded bytes without executing or activating them. */
+export function verifyPublishedReleaseCache(target, archive) {
+    if (!fs.lstatSync(target).isDirectory())
+        refuse("unsafe_retained_cache");
+    const archiveFile = path.join(target, "archive.tgz");
+    if (!fs.lstatSync(archiveFile).isFile())
+        refuse("unsafe_retained_cache");
+    retained(target, archive, inspectReleaseArchive(archive, fs.readFileSync(archiveFile)));
+}
+/** Home-only immutable publication. It never activates a version or changes RUN bindings. */
+export function publishReleaseCache(home, kind, version, archive, compressed) {
+    if (kind !== "canon" && kind !== "engine")
+        refuse("invalid_artifact_kind");
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/.test(version))
+        refuse("invalid_version");
+    const entries = inspectReleaseArchive(archive, compressed);
+    const parent = path.join(path.resolve(home), "release-cache", kind), target = path.join(parent, version);
+    for (const candidate of [path.resolve(home), path.join(path.resolve(home), "release-cache"), parent]) {
+        if (fs.existsSync(candidate) && !fs.lstatSync(candidate).isDirectory())
+            refuse("unsafe_cache_directory");
+    }
+    // Validate before creating even the home, including on replay.
+    if (fs.existsSync(target)) {
+        directory(parent);
+        retained(target, archive, entries);
+        return { root: target, replayed: true };
+    }
+    directory(parent);
+    const lock = `${target}.lock`;
+    const lease = acquireInstallationLock(lock, hybridDigest({ kind, version, archive }));
+    let staging = null;
+    try {
+        if (fs.existsSync(target)) {
+            retained(target, archive, entries);
+            return { root: target, replayed: true };
+        }
+        staging = path.join(parent, `.staging-${lease.token}`);
+        fs.mkdirSync(staging, { mode: 0o700 });
+        const payload = path.join(staging, "payload");
+        fs.mkdirSync(payload, { mode: 0o700 });
+        for (const entry of entries) {
+            const destination = path.join(payload, entry.path);
+            if (entry.kind === "directory")
+                directory(destination);
+            else {
+                directory(path.dirname(destination));
+                write(destination, entry.bytes, entry.mode);
+            }
+        }
+        write(path.join(staging, "receipt.json"), Buffer.from(JSON.stringify({ sha256: archive.sha256, bytes: archive.bytes })), 0o600);
+        write(path.join(staging, "archive.tgz"), compressed, 0o600);
+        retained(staging, archive, entries);
+        fs.renameSync(staging, target);
+        staging = null;
+        return { root: target, replayed: false };
+    }
+    finally {
+        // Only the unique staging directory and lock acquired by this call are owned here.
+        if (staging)
+            fs.rmSync(staging, { recursive: true, force: true });
+        lease.release();
+    }
+}

package/dist/services/release-compatibility.js

@@ -0,0 +1,18 @@
+import semver from "semver";
+import { AppError } from "../shared/errors.js";
+/** Registered catalog format revisions; these do not establish harness/model availability. */
+export const installedCatalogVersions = Object.freeze({ harness: "1.0.0", model: "1.0.0", flow: "1.0.0" });
+/** Compatibility comes from the installed consumer/catalog policy, never from release claims. */
+export function createReleaseCompatibility(policy) {
+    if (!["stable", "preview", "development"].includes(policy.channel) || !semver.valid(policy.routerVersion) ||
+        ["harness", "model", "flow"].some(family => !semver.valid(policy.catalogVersions[family]))) {
+        throw new AppError("release_compatibility", "Installed release compatibility policy is invalid", 1, { phase: "release_admission", effect: "no_effect", help: "setup" });
+    }
+    const routerVersion = policy.routerVersion;
+    return {
+        channel: policy.channel,
+        catalogVersions: { ...policy.catalogVersions },
+        routerCompatible: minimum => Boolean(semver.valid(minimum)) && semver.gte(routerVersion, minimum),
+        engineCompatible: (version, range) => Boolean(semver.valid(version) && semver.validRange(range)) && semver.satisfies(version, range)
+    };
+}

package/dist/services/release-download.js

@@ -0,0 +1,67 @@
+import { AppError } from "../shared/errors.js";
+import { verifyReleaseArchive } from "./release-manifest.js";
+function refuse(reason) {
+    throw new AppError("release_download", "Release artifact download failed", 1, { reason, phase: "artifact_download", effect: "no_effect", help: "setup" });
+}
+/** No provider login, credentials or redirect forwarding. Activation is a separate operation. */
+export async function downloadReleaseArchive(identity, options) {
+    const maxBytes = options.maxBytes ?? 256 * 1024 * 1024;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 ||
+        !Number.isSafeInteger(identity.bytes) || identity.bytes < 1 || identity.bytes > maxBytes || !/^[a-f0-9]{64}$/.test(identity.sha256))
+        refuse("invalid_download_limits_or_identity");
+    let url;
+    try {
+        url = new URL(identity.url);
+    }
+    catch {
+        return refuse("invalid_artifact_url");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || (url.port && url.port !== "443") || !options.allowedHosts.has(url.hostname))
+        refuse("unapproved_artifact_origin");
+    const fetcher = options.fetch ?? globalThis.fetch;
+    let response;
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        response = await fetcher(url, { redirect: "error", signal, credentials: "omit" });
+    }
+    catch {
+        return refuse("network_unavailable_or_redirect");
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        return refuse("artifact_http_failure");
+    }
+    const length = response.headers.get("content-length");
+    if (length !== null && (!/^[0-9]+$/.test(length) || Number(length) !== identity.bytes)) {
+        await response.body.cancel();
+        return refuse("content_length_mismatch");
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let received = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            received += value.byteLength;
+            if (received > identity.bytes || received > maxBytes) {
+                await reader.cancel();
+                return refuse("artifact_exceeds_declared_size");
+            }
+            chunks.push(Buffer.from(value));
+            options.onProgress?.({ received_bytes: received, expected_bytes: identity.bytes });
+        }
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("artifact_stream_interrupted");
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = Buffer.concat(chunks, received);
+    verifyReleaseArchive(identity, bytes);
+    return bytes;
+}

package/dist/services/release-envelope.js

@@ -0,0 +1,104 @@
+import { createHash, createPublicKey, sign, verify } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { admitReleaseManifest } from "./release-manifest.js";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("release_authentication", "Release producer cannot be authenticated", 1, { reason, effect: "no_effect", phase: "release_authentication", help: "setup" });
+}
+function object(value, keys) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).length !== keys.length ||
+        Object.keys(value).some(key => !keys.includes(key)))
+        refuse("invalid_envelope_shape");
+    return value;
+}
+function decoded(value, max = 16 * 1024 * 1024) {
+    if (typeof value !== "string" || value.length > Math.ceil(max / 3) * 4 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
+        refuse("invalid_encoded_bytes");
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.length > max || bytes.toString("base64") !== value)
+        refuse("invalid_encoded_bytes");
+    return bytes;
+}
+function json(bytes) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return refuse("invalid_signed_json");
+    }
+}
+export function releaseProducerKeyId(publicKey) {
+    if (publicKey.type !== "public" || publicKey.asymmetricKeyType !== "ed25519")
+        refuse("unsupported_signing_key");
+    return digest(publicKey.export({ type: "spki", format: "der" }));
+}
+function admission(payload, compatibility, producer) {
+    const data = object(payload, ["schema_id", "manifest_base64", "source", "qualifications", "evidence"]);
+    if (data.schema_id !== "dd-flow/release-payload@1" || !Array.isArray(data.qualifications) || !Array.isArray(data.evidence) || data.qualifications.length > 10_000 || data.evidence.length > 10_000)
+        refuse("invalid_payload_shape");
+    const source = object(data.source, ["kind", "repository", "commit", "tag"]);
+    if (source.repository !== producer.repository || typeof source.commit !== "string" || !/^[a-f0-9]{40}$/.test(source.commit) ||
+        !["published_release", "source_checkout"].includes(String(source.kind)))
+        refuse("source_outside_producer_scope");
+    if (!producer.channels.has(compatibility.channel))
+        refuse("channel_outside_producer_scope");
+    const receipts = new Map();
+    const qualifiedRoutes = new Map(), evidence = new Map();
+    for (const input of data.qualifications) {
+        const fact = object(input, ["route", "sha256", "request_id", "project_root", "workspace", "canon_sha256", "engine_sha256"]);
+        if (typeof fact.route !== "string" || !/^(darwin-arm64|darwin-x64|linux-arm64|linux-x64|win32-x64)\/(codex|zcode|agy|opencode|grok|droid)\/[a-z][a-z0-9-]{0,47}\/(external|native)$/.test(fact.route) ||
+            [fact.sha256, fact.canon_sha256, fact.engine_sha256].some(value => typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) ||
+            [fact.request_id, fact.project_root, fact.workspace].some(value => typeof value !== "string" || !value.trim()))
+            refuse("invalid_qualification_fact");
+        if (qualifiedRoutes.has(fact.route))
+            refuse("duplicate_qualification_fact");
+        qualifiedRoutes.set(fact.route, fact.sha256);
+        receipts.set(fact.sha256, { kind: "route-qualification", requestId: fact.request_id, projectRoot: fact.project_root, workspace: fact.workspace });
+    }
+    for (const input of data.evidence) {
+        const item = object(input, ["path", "bytes_base64"]);
+        if (typeof item.path !== "string" || !/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*(\/[a-zA-Z0-9_-][a-zA-Z0-9_.-]*)*$/.test(item.path) || evidence.has(item.path))
+            refuse("invalid_evidence_path");
+        evidence.set(item.path, decoded(item.bytes_base64));
+    }
+    const manifestBytes = decoded(data.manifest_base64, 1024 * 1024);
+    const authority = { ...compatibility, receipts, qualifiedRoutes, evidence };
+    const manifest = admitReleaseManifest(json(manifestBytes), authority);
+    for (const input of data.qualifications) {
+        if (input.canon_sha256 !== manifest.canon.archive.sha256 || input.engine_sha256 !== manifest.engine.archive.sha256)
+            refuse("qualification_artifact_mismatch");
+    }
+    if (source.commit !== manifest.canon.commit)
+        refuse("source_commit_mismatch");
+    if (source.kind === "source_checkout") {
+        if (manifest.channel !== "development" || source.tag !== null)
+            refuse("source_cannot_claim_published_release");
+    }
+    else if (source.tag !== `v${manifest.version}` || manifest.channel === "development")
+        refuse("published_release_identity_mismatch");
+    return { manifest, manifestBytes, authority, source: source };
+}
+/** Producer receives qualification facts from its owner ledger, never manufactures them from manifest references. */
+export function produceReleaseEnvelope(payload, privateKey, compatibility) {
+    if (privateKey.type !== "private" || privateKey.asymmetricKeyType !== "ed25519")
+        refuse("unsupported_signing_key");
+    admission(payload, compatibility, { repository: payload.source.repository, channels: new Set([compatibility.channel]) });
+    const bytes = Buffer.from(JSON.stringify(payload));
+    if (bytes.length > 16 * 1024 * 1024)
+        refuse("oversized_payload");
+    return { schema_id: "dd-flow/release-envelope@1", producer_key_id: releaseProducerKeyId(createPublicKey(privateKey)),
+        payload_base64: bytes.toString("base64"), signature_base64: sign(null, bytes, privateKey).toString("base64") };
+}
+/** Trust keys and scope are selected independently; an envelope cannot nominate its own authority. */
+export function authenticateReleaseEnvelope(input, trusted, compatibility) {
+    const envelope = object(input, ["schema_id", "producer_key_id", "payload_base64", "signature_base64"]);
+    if (envelope.schema_id !== "dd-flow/release-envelope@1" || typeof envelope.producer_key_id !== "string")
+        refuse("invalid_envelope_identity");
+    const producer = trusted.get(envelope.producer_key_id);
+    if (!producer || releaseProducerKeyId(producer.publicKey) !== envelope.producer_key_id)
+        refuse("unknown_producer");
+    const bytes = decoded(envelope.payload_base64), signature = decoded(envelope.signature_base64, 64);
+    if (signature.length !== 64 || !verify(null, bytes, producer.publicKey, signature))
+        refuse("signature_mismatch");
+    return admission(json(bytes), compatibility, producer);
+}

package/dist/services/release-manifest.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { validateHybridContract } from "./hybrid-contracts.js";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("release_integrity", "Release manifest cannot be admitted", 1, { reason, phase: "release_admission", effect: "no_effect", help: "setup" });
+}
+/** Pure admission: no download, activation, filesystem writes or qualification probes. */
+export function admitReleaseManifest(input, authority) {
+    const issues = validateHybridContract("release-manifest", input, { receipts: authority.receipts });
+    if (issues.length)
+        refuse(issues[0].code);
+    const manifest = input;
+    if (manifest.channel !== authority.channel)
+        refuse("channel_mismatch");
+    if (!authority.routerCompatible(manifest.min_router_version))
+        refuse("router_incompatible");
+    if (!authority.engineCompatible(manifest.engine.version, manifest.engine.compatible_range))
+        refuse("engine_incompatible");
+    for (const family of ["harness", "model", "flow"]) {
+        if (manifest.catalog_versions[family] !== authority.catalogVersions[family])
+            refuse("catalog_incompatible");
+    }
+    for (const route of manifest.qualified_routes) {
+        const key = [route.platform, route.harness, route.flow, route.delegation].join("/");
+        if (authority.qualifiedRoutes.get(key) !== route.evidence.sha256)
+            refuse("route_qualification_mismatch");
+    }
+    for (const reference of [manifest.impact, ...manifest.qualified_routes.map(route => route.evidence)]) {
+        const bytes = authority.evidence.get(reference.path);
+        if (!bytes || sha256(bytes) !== reference.sha256)
+            refuse("evidence_bytes_mismatch");
+    }
+    // Return a detached tuple: callers cannot mutate the submitted object after admission.
+    return structuredClone(manifest);
+}
+/** Verify the actual transferred bytes before any archive parser or cache publication. */
+export function verifyReleaseArchive(archive, bytes) {
+    if (!Number.isSafeInteger(archive.bytes) || archive.bytes < 1 || !/^[a-f0-9]{64}$/.test(archive.sha256))
+        refuse("invalid_archive_identity");
+    if (bytes.byteLength !== archive.bytes)
+        refuse("archive_size_mismatch");
+    if (sha256(bytes) !== archive.sha256)
+        refuse("archive_digest_mismatch");
+}

package/dist/services/release-payload.js

@@ -0,0 +1,114 @@
+import { TextDecoder } from "node:util";
+import { valid } from "semver";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { inspectReleaseArchive } from "./release-archive.js";
+const decoder = new TextDecoder("utf-8", { fatal: true });
+function refuse(reason) {
+    throw new AppError("release_integrity", "Release payload cannot be admitted", 1, { reason, phase: "payload_validation", effect: "no_effect", help: "setup" });
+}
+function root(entries, kind) {
+    const roots = new Set(entries.map(entry => entry.path.split("/")[0]));
+    if (roots.size !== 1)
+        refuse(`${kind}_payload_root_ambiguous`);
+    const selected = [...roots][0];
+    if (kind === "engine" && selected !== "package")
+        refuse("engine_payload_root_invalid");
+    if (entries.some(entry => entry.kind === "file" && entry.path === selected))
+        refuse(`${kind}_payload_root_invalid`);
+    return selected;
+}
+function text(entries, file) {
+    const entry = entries.find(candidate => candidate.path === file);
+    if (!entry || entry.kind !== "file")
+        refuse("payload_metadata_missing");
+    // Metadata is bounded separately from the expanded archive and never executed.
+    if (entry.bytes.length > 1024 * 1024)
+        refuse("payload_metadata_oversized");
+    try {
+        return decoder.decode(entry.bytes);
+    }
+    catch {
+        return refuse("payload_metadata_invalid_utf8");
+    }
+}
+function json(entries, file) {
+    let value;
+    try {
+        value = JSON.parse(text(entries, file));
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("engine_payload_package_invalid");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        refuse("engine_payload_package_invalid");
+    return value;
+}
+function validateCanonLayout(entries, archiveRoot) {
+    const markers = ["dd-flow/README.md", "mbb/index.md", "protocol/index.md"];
+    const candidates = [archiveRoot, `${archiveRoot}/.memory-bank`];
+    const present = (file) => entries.some(entry => entry.path === file && entry.kind === "file" && entry.bytes.length > 0);
+    const layouts = candidates.filter(candidate => markers.every(marker => present(`${candidate}/${marker}`)));
+    if (layouts.length !== 1)
+        refuse(layouts.length ? "canon_payload_layout_ambiguous" : "canon_payload_layout_incomplete");
+    const selected = layouts[0];
+    // Even an incomplete second layout can shadow files during later resolution.
+    if (candidates.some(candidate => candidate !== selected && markers.some(marker => present(`${candidate}/${marker}`))))
+        refuse("canon_payload_layout_ambiguous");
+}
+/** Check package identity from transferred bytes before creating the installation home.
+ * This is not catalog/schema or runtime qualification; those require their own evidence.
+ */
+export function validateReleasePayloadIdentity(manifest, canon, engine) {
+    const canonEntries = inspectReleaseArchive(manifest.canon.archive, canon);
+    const engineEntries = inspectReleaseArchive(manifest.engine.archive, engine);
+    const canonRoot = root(canonEntries, "canon"), engineRoot = root(engineEntries, "engine");
+    if (text(canonEntries, `${canonRoot}/VERSION`).trim() !== manifest.canon.version)
+        refuse("canon_payload_version_mismatch");
+    validateCanonLayout(canonEntries, canonRoot);
+    const metadata = json(engineEntries, `${engineRoot}/package.json`);
+    if (metadata.name !== manifest.engine.package)
+        refuse("engine_payload_package_mismatch");
+    if (metadata.version !== manifest.engine.version)
+        refuse("engine_payload_version_mismatch");
+    if (metadata.type !== "module")
+        refuse("engine_payload_module_type_invalid");
+    const bins = metadata.bin;
+    if (!bins || typeof bins !== "object" || Array.isArray(bins)
+        || bins["dd-flow"] !== "dist/cli.js")
+        refuse("engine_payload_bin_invalid");
+    for (const target of Object.values(bins)) {
+        if (typeof target !== "string" || !/^dist\/[A-Za-z0-9_./-]+$/.test(target)
+            || target.split("/").some(part => !part || part === "." || part === ".."))
+            refuse("engine_payload_bin_invalid");
+        const executable = engineEntries.find(entry => entry.path === `${engineRoot}/${target}`);
+        if (!executable || executable.kind !== "file" || executable.bytes.length === 0 || !(executable.mode & 0o111))
+            refuse("engine_payload_bin_missing");
+    }
+    const build = json(engineEntries, `${engineRoot}/dist/build-info.json`);
+    if (build.cli_package !== manifest.engine.package || build.cli_version !== manifest.engine.version
+        || typeof build.cli_commit !== "string" || !/^[a-f0-9]{40}$/.test(build.cli_commit))
+        refuse("engine_payload_build_identity_mismatch");
+    const canonBuild = build.built_with_canon;
+    // Build provenance is not the installed canon selection. One immutable engine
+    // can serve multiple independently qualified canon tuples without being rebuilt.
+    if (!canonBuild || typeof canonBuild !== "object" || Array.isArray(canonBuild)
+        || typeof canonBuild.version !== "string" || !valid(canonBuild.version)
+        || typeof canonBuild.commit !== "string" || !/^[a-f0-9]{40}$/.test(canonBuild.commit))
+        refuse("engine_payload_canon_provenance_invalid");
+    const schemaFiles = { descriptor: "flow-descriptor", execution: "execution-settings", bundle: "execution-bundle" };
+    for (const family of ["descriptor", "execution", "bundle"]) {
+        const schema = json(engineEntries, `${engineRoot}/dist/schemas/${schemaFiles[family]}.schema.json`);
+        if (schema.$id !== manifest.schema_versions[family]
+            || schema.$schema !== "https://json-schema.org/draft/2020-12/schema")
+            refuse("engine_payload_schema_identity_mismatch");
+        try {
+            new Ajv2020({ strict: true, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("engine_payload_schema_invalid");
+        }
+    }
+}

package/dist/services/release-producer.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createPublicKey, randomUUID } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { authenticateReleaseEnvelope, produceReleaseEnvelope, releaseProducerKeyId } from "./release-envelope.js";
+import { readLocalReleaseBundle } from "./release-source.js";
+import { validateReleasePayloadIdentity } from "./release-payload.js";
+function refuse(reason) {
+    throw new AppError("release_producer", "Release bundle cannot be published", 1, { reason, phase: "release_production", effect: "no_effect" });
+}
+/** Local immutable delivery only. Qualification facts must already come from their
+ * owner ledger; this producer never performs, synthesizes or upgrades qualification.
+ */
+export function publishReleaseBundle(destination, input) {
+    if (!input.payload || typeof input.payload !== "object" || !input.payload.source
+        || typeof input.payload.source.repository !== "string")
+        refuse("invalid_producer_payload");
+    const envelope = produceReleaseEnvelope(input.payload, input.privateKey, input.compatibility);
+    const publicKey = createPublicKey(input.privateKey), producers = new Map([[releaseProducerKeyId(publicKey), {
+                publicKey, repository: input.payload.source.repository, channels: new Set([input.compatibility.channel])
+            }]]);
+    const admitted = authenticateReleaseEnvelope(envelope, producers, input.compatibility);
+    validateReleasePayloadIdentity(admitted.manifest, input.canonArchive, input.engineArchive);
+    const root = path.resolve(destination), parent = path.dirname(root);
+    if (root === parent || !fs.existsSync(parent) || !fs.lstatSync(parent).isDirectory())
+        refuse("invalid_output_parent");
+    const envelopeBytes = Buffer.from(JSON.stringify(envelope));
+    const lease = acquireInstallationLock(`${root}.lock`, hybridDigest({ envelope, canon: admitted.manifest.canon.archive, engine: admitted.manifest.engine.archive }));
+    let staging = null;
+    try {
+        if (fs.existsSync(root)) {
+            const retained = readLocalReleaseBundle(root, producers, input.compatibility);
+            if (fs.readdirSync(root).sort().join("/") !== "canon.tgz/engine.tgz/release-envelope.json"
+                || !fs.readFileSync(path.join(root, "release-envelope.json")).equals(envelopeBytes)
+                || !retained.canonArchive.equals(input.canonArchive) || !retained.engineArchive.equals(input.engineArchive))
+                refuse("immutable_bundle_conflict");
+            return { root, replayed: true, producer_key_id: envelope.producer_key_id };
+        }
+        staging = path.join(parent, `.release-staging-${randomUUID()}`);
+        fs.mkdirSync(staging, { mode: 0o700 });
+        for (const [name, bytes] of [["release-envelope.json", envelopeBytes], ["canon.tgz", input.canonArchive], ["engine.tgz", input.engineArchive]]) {
+            const fd = fs.openSync(path.join(staging, name), "wx", 0o600);
+            try {
+                fs.writeFileSync(fd, bytes);
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        readLocalReleaseBundle(staging, producers, input.compatibility);
+        fs.renameSync(staging, root);
+        staging = null;
+        return { root, replayed: false, producer_key_id: envelope.producer_key_id };
+    }
+    finally {
+        if (staging)
+            fs.rmSync(staging, { recursive: true, force: true });
+        lease.release();
+    }
+}