akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/ir/environment-v4.js

@@ -1,330 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Durable-v4 symbolic workflow environments.
- *
- * Env-file values are the deliberately narrow live-value exception to a
- * frozen workflow plan. Freeze persists only the qualified owner, physical
- * containment, exact key set, and secret-token topology. Materialization
- * later reads current values directly through that descriptor, without
- * consulting config, the index, or authored workflow source.
- */
-import fs from "node:fs";
-import path from "node:path";
-import dotenv from "dotenv";
-import { assetPathForName } from "../../core/asset/asset-placement.js";
-import { isWithin } from "../../core/common.js";
-import { NotFoundError, UsageError } from "../../core/errors.js";
-import { warn } from "../../core/warn.js";
-import { captureGuardedExecutionSource, GuardedExecutionSourceCollector } from "../../execution/guarded-source.js";
-const SECRET_TOKEN_RE = /\$\{secret:([A-Za-z0-9_./-]+)\}/g;
-const ENVIRONMENT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const QUALIFIED_ENV_REF_RE = /^([^/]+)\/\/env\/(.+)$/;
-/** Freeze value-free descriptors in authored ref order. */
-export function freezeWorkflowEnvironment(refs, options) {
-    const collector = options.collector ?? new GuardedExecutionSourceCollector();
-    const logical = new Set();
-    const physical = new Map();
-    const out = [];
-    for (const [precedence, inputRef] of refs.entries()) {
-        const resolved = options.resolveRef(inputRef);
-        const match = QUALIFIED_ENV_REF_RE.exec(resolved.ref);
-        if (!match || match[1] !== resolved.bundle) {
-            throw new UsageError(`Workflow env ref ${JSON.stringify(inputRef)} did not resolve to a canonical fully-qualified owner.`, "WORKFLOW_SOURCE_INVALID");
-        }
-        if (logical.has(resolved.ref)) {
-            continue;
-        }
-        logical.add(resolved.ref);
-        trackParentDirectories(collector, resolved.root, resolved.path);
-        const retained = collector.capture(resolved.path, resolved.root, { authored: true });
-        const captured = collector.bindIdentity(resolved.path, resolved.root, {
-            ref: resolved.ref,
-            bundle: resolved.bundle,
-            adapter: resolved.adapter,
-            file: retained.relativePath,
-            hash: retained.sha256,
-        });
-        const physicalKey = `${captured.containmentPhysicalIdentity}\0${captured.physicalIdentity}`;
-        const alias = physical.get(physicalKey);
-        if (alias !== undefined && alias !== resolved.ref) {
-            warn(`Workflow env ref ${resolved.ref} aliases the same physical environment source as ${alias} under a different logical owner. Using ${alias}.`);
-            continue;
-        }
-        physical.set(physicalKey, resolved.ref);
-        const parsed = dotenv.parse(Buffer.from(captured.bytesBase64, "base64"));
-        const keys = sortedCodePoints(Object.keys(parsed));
-        const secretNames = secretTokenNames(parsed);
-        out.push(Object.freeze({
-            kind: "env-ref",
-            ref: resolved.ref,
-            owner: Object.freeze({
-                bundle: resolved.bundle,
-                adapter: resolved.adapter,
-                requestedRoot: captured.containmentRoot,
-                realRoot: captured.containmentRealPath,
-                rootPhysicalIdentity: captured.containmentPhysicalIdentity,
-                requestedPath: captured.sourcePath,
-                realPath: captured.realPath,
-                relativePath: captured.relativePath,
-            }),
-            keys: Object.freeze(keys),
-            secretNames: Object.freeze(secretNames),
-            precedence,
-        }));
-    }
-    return out;
-}
-/**
- * Materialize all current values atomically from frozen descriptors. Nothing
- * is returned until every owner/key/token check and every secret lookup has
- * succeeded.
- */
-export function materializeFrozenWorkflowEnvironment(descriptors, options = {}) {
-    const values = {};
-    const sensitive = new Set();
-    const audits = [];
-    const seenRefs = new Set();
-    let priorPrecedence = -1;
-    for (const descriptor of descriptors) {
-        if (!descriptor || typeof descriptor !== "object")
-            invalid("environment descriptor must be an object");
-        if (descriptor.kind === "literal") {
-            exactKeys(descriptor, ["kind", "name", "value"]);
-            environmentName(descriptor.name);
-            if (typeof descriptor.value !== "string")
-                invalid("literal environment value must be a string");
-            values[descriptor.name] = descriptor.value;
-            if (descriptor.value)
-                sensitive.add(descriptor.value);
-            continue;
-        }
-        if (descriptor.kind === "pass-through") {
-            exactKeys(descriptor, ["kind", "name"]);
-            environmentName(descriptor.name);
-            const value = options.readPassThrough ? options.readPassThrough(descriptor.name) : process.env[descriptor.name];
-            if (value !== undefined) {
-                values[descriptor.name] = value;
-                if (value)
-                    sensitive.add(value);
-            }
-            continue;
-        }
-        if (descriptor.kind !== "env-ref")
-            invalid("environment descriptor has an unsupported kind");
-        exactKeys(descriptor, ["kind", "ref", "owner", "keys", "secretNames", "precedence"]);
-        validateEnvRefDescriptor(descriptor);
-        if (seenRefs.has(descriptor.ref))
-            invalid(`duplicate environment ref ${descriptor.ref}`);
-        if (descriptor.precedence <= priorPrecedence)
-            invalid("env-ref precedence must be strictly increasing");
-        seenRefs.add(descriptor.ref);
-        priorPrecedence = descriptor.precedence;
-        const source = options.readEnvFile ? options.readEnvFile(descriptor) : readFrozenEnvironmentFile(descriptor.owner);
-        const parsed = dotenv.parse(typeof source === "string" ? source : Buffer.from(source));
-        const keys = sortedCodePoints(Object.keys(parsed));
-        const tokenNames = secretTokenNames(parsed);
-        if (!sameStrings(keys, descriptor.keys)) {
-            invalid(`environment ${descriptor.ref} key set changed after it was frozen`);
-        }
-        if (!sameStrings(tokenNames, descriptor.secretNames)) {
-            invalid(`environment ${descriptor.ref} secret-token topology changed after it was frozen`);
-        }
-        const secretValues = new Map();
-        for (const name of descriptor.secretNames) {
-            const raw = options.readSecret
-                ? options.readSecret({ name, descriptor })
-                : readFrozenSecret(descriptor.owner, name);
-            if (raw === undefined) {
-                throw new NotFoundError(`Environment ${descriptor.ref} references missing secret ${name}; nothing was materialized.`, "FILE_NOT_FOUND");
-            }
-            const value = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
-            secretValues.set(name, value);
-            if (value)
-                sensitive.add(value);
-        }
-        for (const [key, rawValue] of Object.entries(parsed)) {
-            const resolved = rawValue.replace(SECRET_TOKEN_RE, (_token, name) => {
-                const secret = secretValues.get(name);
-                if (secret === undefined)
-                    invalid(`environment ${descriptor.ref} secret ${name} was not materialized`);
-                return secret;
-            });
-            values[key] = resolved;
-            if (resolved)
-                sensitive.add(resolved);
-        }
-        audits.push(Object.freeze({
-            eventType: "env_access",
-            ref: descriptor.ref,
-            keys: Object.freeze([...descriptor.keys]),
-            secretNames: Object.freeze([...descriptor.secretNames]),
-        }));
-    }
-    return {
-        values,
-        sensitiveValues: [...sensitive],
-        audits,
-    };
-}
-function validateEnvRefDescriptor(descriptor) {
-    const match = QUALIFIED_ENV_REF_RE.exec(descriptor.ref);
-    if (!match || match[1] !== descriptor.owner.bundle)
-        invalid("env-ref has a noncanonical qualified owner");
-    exactKeys(descriptor.owner, [
-        "bundle",
-        "adapter",
-        "requestedRoot",
-        "realRoot",
-        "rootPhysicalIdentity",
-        "requestedPath",
-        "realPath",
-        "relativePath",
-    ]);
-    for (const value of [descriptor.owner.bundle, descriptor.owner.adapter, descriptor.owner.rootPhysicalIdentity]) {
-        if (typeof value !== "string" || !value)
-            invalid("env-ref owner identity is incomplete");
-    }
-    for (const value of [
-        descriptor.owner.requestedRoot,
-        descriptor.owner.realRoot,
-        descriptor.owner.requestedPath,
-        descriptor.owner.realPath,
-    ]) {
-        if (typeof value !== "string" || !path.isAbsolute(value))
-            invalid("env-ref owner paths must be absolute");
-    }
-    const relative = descriptor.owner.relativePath;
-    if (typeof relative !== "string" ||
-        !relative ||
-        relative.includes("\\") ||
-        relative.startsWith("../") ||
-        path.isAbsolute(relative)) {
-        invalid("env-ref owner relative path is noncanonical");
-    }
-    if (path.resolve(descriptor.owner.requestedRoot, relative) !== path.resolve(descriptor.owner.requestedPath)) {
-        invalid("env-ref requested path does not match its owner");
-    }
-    if (path.resolve(descriptor.owner.realRoot, relative) !== path.resolve(descriptor.owner.realPath)) {
-        invalid("env-ref real path does not match its owner");
-    }
-    sortedUnique(descriptor.keys, "env-ref keys", ENVIRONMENT_NAME_RE);
-    sortedUnique(descriptor.secretNames, "env-ref secret names", /^[A-Za-z0-9_./-]+$/);
-    if (!Number.isSafeInteger(descriptor.precedence) || descriptor.precedence < 0) {
-        invalid("env-ref precedence is invalid");
-    }
-}
-function readFrozenEnvironmentFile(owner) {
-    const rootLstat = fs.lstatSync(owner.requestedRoot, { bigint: true });
-    if (rootLstat.isSymbolicLink() || !rootLstat.isDirectory())
-        invalid("environment owner root physical identity changed");
-    const currentRealRoot = fs.realpathSync(owner.requestedRoot);
-    if (currentRealRoot !== owner.realRoot ||
-        physicalIdentity(currentRealRoot, rootLstat) !== owner.rootPhysicalIdentity) {
-        invalid("environment owner root physical identity changed");
-    }
-    const captured = captureGuardedExecutionSource(owner.requestedPath, owner.requestedRoot, { authored: true });
-    if (captured.realPath !== owner.realPath ||
-        captured.relativePath !== owner.relativePath ||
-        captured.containmentRealPath !== owner.realRoot ||
-        captured.containmentPhysicalIdentity !== owner.rootPhysicalIdentity) {
-        invalid("environment owner/path physical identity changed");
-    }
-    return Buffer.from(captured.bytesBase64, "base64");
-}
-function readFrozenSecret(owner, name) {
-    const secretsRoot = path.join(owner.requestedRoot, "secrets");
-    const secretPath = assetPathForName("secret", secretsRoot, name);
-    if (!isWithin(secretPath, secretsRoot))
-        invalid(`secret name ${name} escapes its frozen owner`);
-    let descriptor;
-    try {
-        const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-        descriptor = fs.openSync(secretPath, fs.constants.O_RDONLY | noFollow);
-        const before = fs.fstatSync(descriptor, { bigint: true });
-        if (!before.isFile())
-            invalid(`secret ${name} is not a regular file`);
-        const bytes = fs.readFileSync(descriptor);
-        const after = fs.fstatSync(descriptor, { bigint: true });
-        if (before.dev !== after.dev ||
-            before.ino !== after.ino ||
-            before.size !== after.size ||
-            before.mtimeNs !== after.mtimeNs) {
-            invalid(`secret ${name} changed while it was read`);
-        }
-        return bytes;
-    }
-    catch (cause) {
-        if (cause.code === "ENOENT")
-            return undefined;
-        throw cause;
-    }
-    finally {
-        if (descriptor !== undefined)
-            fs.closeSync(descriptor);
-    }
-}
-function trackParentDirectories(collector, rootInput, fileInput) {
-    const root = path.resolve(rootInput);
-    const parent = path.dirname(path.resolve(fileInput));
-    const relative = path.relative(root, parent);
-    if (relative.startsWith("..") || path.isAbsolute(relative))
-        invalid("environment source escapes its owner root");
-    let current = root;
-    collector.trackDirectory(current, root);
-    if (relative === "")
-        return;
-    for (const segment of relative.split(path.sep)) {
-        current = path.join(current, segment);
-        collector.trackDirectory(current, root);
-    }
-}
-function secretTokenNames(values) {
-    const names = new Set();
-    for (const value of Object.values(values)) {
-        for (const match of value.matchAll(SECRET_TOKEN_RE)) {
-            const name = match[1];
-            if (name)
-                names.add(name);
-        }
-    }
-    return sortedCodePoints([...names]);
-}
-function sortedCodePoints(values) {
-    return values.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
-}
-function sortedUnique(values, label, pattern) {
-    if (!Array.isArray(values))
-        invalid(`${label} must be an array`);
-    let prior;
-    for (const value of values) {
-        if (typeof value !== "string" || !pattern.test(value) || value.includes(".."))
-            invalid(`${label} is invalid`);
-        if (prior !== undefined && prior >= value)
-            invalid(`${label} must be sorted and unique`);
-        prior = value;
-    }
-}
-function sameStrings(left, right) {
-    return left.length === right.length && left.every((value, index) => value === right[index]);
-}
-function exactKeys(value, keys) {
-    const allowed = new Set(keys);
-    for (const key of Object.keys(value))
-        if (!allowed.has(key))
-            invalid(`environment descriptor contains unknown key ${key}`);
-    for (const key of keys)
-        if (!Object.hasOwn(value, key))
-            invalid(`environment descriptor is missing ${key}`);
-}
-function environmentName(value) {
-    if (typeof value !== "string" || !ENVIRONMENT_NAME_RE.test(value))
-        invalid("environment name is invalid");
-}
-function physicalIdentity(realPath, stat) {
-    return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
-}
-function invalid(message) {
-    throw new UsageError(`Invalid frozen workflow environment: ${message}.`, "WORKFLOW_SOURCE_INVALID");
-}

package/dist/workflows/ir/freeze-v4.js

@@ -1,153 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { createHash } from "node:crypto";
-import path from "node:path";
-import { parseBundleRef } from "../../core/asset/asset-ref.js";
-import { COMPOSITION_INVALID_MULTI_JOB_HINT, UsageError } from "../../core/errors.js";
-import { GuardedExecutionSourceCollector } from "../../execution/guarded-source.js";
-import { defaultMapConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
-import { assertChildOutputReferences } from "../freeze/child-output-references.js";
-import { resolveWorkflowSourceV4 } from "../freeze/source-freeze.js";
-import { compileWorkflowPlan } from "./compile.js";
-import { canonicalJson } from "./plan-hash.js";
-import { decodeWorkflowPlanV4, WORKFLOW_IR_V5_VERSION, } from "./schema-v4.js";
-/** Compile, resolve, and freeze one executable plan without publishing any state. */
-export async function compileResolveFreezeWorkflowV4(asset, config, options = {}) {
-    const sourceCollector = options.sourceCollector ?? new GuardedExecutionSourceCollector();
-    const composition = options.composition ?? {
-        depth: 0,
-        refPath: [asset.ref],
-        budget: { embeddedBytes: 0 },
-    };
-    // Injected rather than imported (A-N7/step-values.ts's `ChildCompositionContext`
-    // doc): `targets/child-workflow.ts` is downstream of this module (via
-    // `resolve-steps.ts` <- `source-freeze.ts`, imported directly above — the
-    // `source-freeze-v4.ts` shim P4 deleted used to sit on this edge), so it
-    // cannot import `compileResolveFreezeWorkflowV4` directly without closing
-    // a static import cycle
-    // (tests/architecture/import-cycle-ratchet.test.ts, shrink-only, empty
-    // baseline). This closure is this function's own recursive call, passed
-    // down as a plain value through `ResolutionContext.freezeChild`.
-    const freezeChild = async (request) => {
-        const child = await compileResolveFreezeWorkflowV4(request.asset, config, {
-            sourceCollector: request.sourceCollector,
-            composition: request.composition,
-        });
-        return { plan: child.plan, sourceCollector: child.sourceCollector };
-    };
-    const workflowSource = captureWorkflowSource(asset, sourceCollector);
-    const resolved = await resolveWorkflowSourceV4(asset, workflowSource, config, sourceCollector, composition, freezeChild);
-    const compiled = compileWorkflowPlan(resolved.sourceIr, asset.title, resolved.units);
-    if (!compiled.ok) {
-        // P4-N2's mapping (docs/plans/specs/p4-deletions-closeout.md §3.3.4)
-        // applies here too, though `resolved.sourceIr` is already guaranteed
-        // exactly one job by this point (source-freeze.ts's own compile already
-        // succeeded), so this compiler's own errors never carry the
-        // multi-job-unsupported code — the arm always resolves to
-        // WORKFLOW_SOURCE_INVALID.
-        const isMultiJob = compiled.errors.length === 1 && compiled.errors[0]?.code === "multi-job-unsupported";
-        const code = isMultiJob ? "COMPOSITION_INVALID" : "WORKFLOW_SOURCE_INVALID";
-        throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"), code, isMultiJob ? COMPOSITION_INVALID_MULTI_JOB_HINT : undefined);
-    }
-    const steps = compiled.plan.steps.map((step) => {
-        const frozenJudge = step.gate.criteria.length === 0 ? null : (resolved.judges.get(step.stepId) ?? null);
-        const gate = Object.freeze({ ...step.gate, maxLoops: step.gate.maxLoops ?? 1, frozenJudge });
-        if (!step.root) {
-            const { root: _root, ...withoutRoot } = step;
-            return Object.freeze({ ...withoutRoot, gate });
-        }
-        const frozen = resolved.units.get(step.stepId);
-        if (!frozen)
-            throw new Error(`resolved workflow target missing for step ${step.stepId}`);
-        const root = step.root.kind === "map"
-            ? {
-                ...step.root,
-                concurrency: step.root.concurrency ?? defaultMapConcurrency(config.workflow?.defaultMapConcurrency),
-                template: freezeResolvedUnit(step.root.template, frozen),
-            }
-            : freezeResolvedUnit(step.root, frozen);
-        return Object.freeze({ ...step, root, gate });
-    });
-    // P3b, spec §4.4: after every step's target is resolved (so every embedded
-    // child plan is available) and before the plan object is assembled.
-    assertChildOutputReferences(steps);
-    const sourceReadSet = sourceCollector
-        .snapshot()
-        .sources.filter((source) => Boolean(source.identity))
-        .map((source) => sourceSnapshot(source));
-    const plan = decodeWorkflowPlanV4({
-        irVersion: WORKFLOW_IR_V5_VERSION,
-        title: compiled.plan.title,
-        ...(compiled.plan.params ? { params: compiled.plan.params } : {}),
-        ...(compiled.plan.paramSchemas ? { paramSchemas: compiled.plan.paramSchemas } : {}),
-        ...(compiled.plan.budget ? { budget: compiled.plan.budget } : {}),
-        execution: { maxConcurrency: workflowMaxConcurrency(config.workflow?.maxConcurrency) },
-        sourceReadSet,
-        steps,
-        ...(compiled.plan.outputs ? { outputs: compiled.plan.outputs } : {}),
-    });
-    return Object.freeze({
-        plan,
-        warnings: compiled.warnings,
-        ...(resolved.engineAnnouncement ? { engineAnnouncement: resolved.engineAnnouncement } : {}),
-        sourceCollector,
-    });
-}
-function freezeResolvedUnit(unit, resolved) {
-    const frozenTarget = resolved.target.kind === "shell"
-        ? Object.freeze({
-            ...resolved.target,
-            contentHash: createHash("sha256")
-                .update("akm.workflow.shell.v1\0")
-                .update(canonicalJson({
-                exec: resolved.target.exec,
-                environment: resolved.environment,
-                cwdIdentity: resolved.target.cwdIdentity,
-            }))
-                .digest("hex"),
-        })
-        : resolved.target;
-    const { exec: _exec, ...common } = unit;
-    return Object.freeze({
-        ...common,
-        isolation: common.isolation ?? "none",
-        frozenTarget,
-        environment: Object.freeze([...resolved.environment]),
-    });
-}
-function captureWorkflowSource(asset, collector) {
-    const root = path.resolve(asset.sourcePath);
-    const file = path.resolve(asset.path);
-    collector.trackDirectory(root, root);
-    const parent = path.dirname(file);
-    const relativeParent = path.relative(root, parent);
-    if (relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) {
-        throw new UsageError(`${file} resolves outside its workflow source root.`, "PATH_ESCAPE_VIOLATION");
-    }
-    let current = root;
-    for (const segment of relativeParent === "" ? [] : relativeParent.split(path.sep)) {
-        current = path.join(current, segment);
-        collector.trackDirectory(current, root);
-    }
-    const captured = collector.capture(file, root, { authored: true });
-    const parsed = parseBundleRef(asset.ref);
-    if (!parsed.bundle || !asset.adapterId) {
-        throw new UsageError(`Workflow ${asset.ref} has no fully-qualified bundle/adapter owner for durable publication.`, "WORKFLOW_SOURCE_INVALID");
-    }
-    return collector.bindIdentity(file, root, {
-        ref: asset.ref,
-        bundle: parsed.bundle,
-        adapter: asset.adapterId,
-        file: captured.relativePath,
-        hash: captured.sha256,
-    });
-}
-function sourceSnapshot(source) {
-    return Object.freeze({
-        identity: source.identity,
-        containmentPhysicalIdentity: source.containmentPhysicalIdentity,
-        physicalIdentity: source.physicalIdentity,
-        size: source.size,
-    });
-}