@xemahq/dsl 0.1.1

package/dist/workflow/lib/compiler/compile.js

@@ -0,0 +1,794 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileWorkflow = compileWorkflow;
+const workflow_1 = require("@xemahq/kernel-contracts/workflow");
+const errors_1 = require("../errors");
+const expression_1 = require("../expression");
+const canonical_json_1 = require("./canonical-json");
+const concurrency_1 = require("./concurrency");
+const dag_1 = require("./dag");
+const inputs_1 = require("./inputs");
+const matrix_1 = require("./matrix");
+const manifest_source_1 = require("./manifest-source");
+const mount_plan_1 = require("./mount-plan");
+const permissions_1 = require("./permissions");
+const review_step_1 = require("./review-step");
+const retry_timeout_1 = require("./retry-timeout");
+const payload_reach_in_1 = require("./payload-reach-in");
+const installation_resource_validator_1 = require("./installation-resource-validator");
+const variable_requirements_1 = require("./variable-requirements");
+function compileWorkflow(input) {
+    const { workflow, workflowRef, trigger, resolvedRefs, workflowDefinitionVersionSha256 } = input;
+    const inputs = (0, inputs_1.bindTriggerInputs)(workflow, trigger, input.previewMode ?? false);
+    const vars = workflow.vars ?? {};
+    const requiredVariables = (0, variable_requirements_1.resolveWalletRequirements)(workflow, input.resolvedWallets);
+    const requiredWallets = Object.freeze([
+        ...(workflow.requires?.wallets ?? []),
+    ]);
+    const permissions = (0, permissions_1.normalizePermissions)(workflow.permissions);
+    const concurrency = (0, concurrency_1.compileConcurrency)(workflow.concurrency, trigger, inputs, vars);
+    const defaults = (0, retry_timeout_1.resolveWorkflowDefaults)(workflow.defaults);
+    validateAllAuthoredExpressions(workflow);
+    (0, variable_requirements_1.validateVariableReferences)(workflow, requiredVariables, input.resolvedWallets);
+    validateAllLiteralReferences(workflow, input.resolvedAgents ?? {}, input.resolvedDeliverableSpecs ?? {});
+    (0, review_step_1.validateReviewSteps)(workflow);
+    const reviewNeedsExtensions = (0, review_step_1.computeReviewNeedsExtensions)(workflow);
+    validateMatrixGather(workflow);
+    validateAllNeedsAccessShapes(workflow);
+    validateDeliverableValueExpressions(workflow, input.resolvedDeliverableSpecs ?? {});
+    (0, payload_reach_in_1.validatePayloadReachIns)(workflow, input.resolvedDeliverableSpecs ?? {}, resolvedRefs);
+    const orderedJobs = (0, dag_1.topologicalSort)(Object.entries(workflow.jobs).map(([key, decl]) => {
+        const authoredNeeds = decl.needs ?? [];
+        const gather = decl.matrixGather ?? [];
+        const reviewExt = reviewNeedsExtensions[key] ?? [];
+        const merged = gather.length > 0 || reviewExt.length > 0
+            ? Array.from(new Set([...authoredNeeds, ...gather, ...reviewExt]))
+            : authoredNeeds;
+        return { key, payload: decl, needs: merged };
+    }));
+    const compiledJobs = orderedJobs.map(({ key, payload, needs }) => {
+        const resolved = lookupResolvedRef(payload.uses, resolvedRefs);
+        const actionRef = {
+            id: resolved.id,
+            version: resolved.version,
+            manifestSha256: resolved.manifestSha256,
+            executionKind: resolveJobExecutionKind(key, payload.with, resolved),
+            taskQueue: resolved.taskQueue,
+            actionKind: resolveActionKind(resolved),
+            isReusableWorkflow: resolved.isReusableWorkflow,
+            inputsSchema: resolved.isReusableWorkflow
+                ? null
+                : resolved.actionManifest?.spec.inputs ?? null,
+        };
+        const jobPermissions = (0, permissions_1.normalizePermissions)(payload.permissions);
+        (0, permissions_1.assertJobPermissionsFit)(jobPermissions, permissions, key);
+        const strategy = (0, matrix_1.compileStrategy)(payload.strategy, key);
+        const mountPlan = resolved.isReusableWorkflow
+            ? { readOnly: {}, readWrite: {} }
+            : (0, mount_plan_1.compileMountPlan)(key, payload.with, resolved.actionManifest);
+        const manifestSource = resolved.isReusableWorkflow
+            ? null
+            : (0, manifest_source_1.compileManifestSource)(key, payload.with, resolved.actionManifest);
+        const retry = (0, retry_timeout_1.resolveJobRetry)(defaults.retry, resolved.actionManifest?.spec.retryDefaults ?? null, payload.retry);
+        const timeoutMs = (0, retry_timeout_1.resolveJobTimeout)(defaults.timeoutMs, resolved.actionManifest?.spec.timeoutDefaults ?? null, payload.timeout);
+        const ifExpression = payload.if !== undefined
+            ? (() => {
+                const body = (0, expression_1.stripInterpolation)(payload.if);
+                const rewritten = rewriteBareNeedsInIf(body);
+                (0, expression_1.compileExpression)(rewritten);
+                return rewritten;
+            })()
+            : null;
+        const compiledWith = (0, review_step_1.rewriteReviewStepWith)(key, payload, workflow);
+        (0, installation_resource_validator_1.validateInstallationResourceBindings)({
+            jobKey: key,
+            actionId: actionRef.id,
+            inputsSchema: actionRef.inputsSchema,
+            withValue: compiledWith,
+            scope: input.installationScope,
+        });
+        return Object.freeze({
+            jobKey: key,
+            title: payload.title ?? null,
+            needs,
+            matrixGather: Object.freeze([...(payload.matrixGather ?? [])]),
+            ifExpression,
+            strategy,
+            action: actionRef,
+            mountPlan,
+            manifestSource,
+            with: Object.freeze({ ...compiledWith }),
+            outputs: compileOutputsMap(payload.outputs, `jobs.${key}.outputs`),
+            retry,
+            timeoutMs,
+            permissions: jobPermissions,
+            reusableCompiledRun: null,
+            payloadReachIns: Object.freeze((0, payload_reach_in_1.collectPayloadReachInsForJob)(workflow, key, payload, input.resolvedDeliverableSpecs ?? {}, resolvedRefs)),
+        });
+    });
+    const snapshotCreatedAt = input.trigger.triggeredAt;
+    const workflowCallOutputs = compileOutputsMap(workflow.on.workflow_call?.outputs, 'on.workflow_call.outputs');
+    const workflowOutputs = compileWorkflowOutputs(workflow);
+    const baseCompiled = {
+        compiledRunVersion: 1,
+        workflowRef,
+        trigger,
+        inputs,
+        vars,
+        requiredWallets,
+        requiredVariables,
+        permissions,
+        concurrency,
+        defaults,
+        jobs: Object.freeze(compiledJobs),
+        snapshotCreatedAt,
+        workflowDefinitionVersionSha256,
+        workflowCallOutputs,
+        workflowOutputs,
+        ...(input.briefcase !== undefined && { briefcase: input.briefcase }),
+    };
+    const snapshotSha256 = (0, canonical_json_1.canonicalJsonSha256)(baseCompiled);
+    const compiled = {
+        ...baseCompiled,
+        snapshotSha256,
+    };
+    assertStrategyInvariants(compiled);
+    return compiled;
+}
+function rewriteBareNeedsInIf(body) {
+    let ast;
+    try {
+        ast = (0, expression_1.compileExpression)(body);
+    }
+    catch {
+        return body;
+    }
+    const upstreamKey = matchBareNeedsRef(ast);
+    if (upstreamKey === null)
+        return body;
+    return `needs.${upstreamKey}.outcome == 'ok'`;
+}
+function matchBareNeedsRef(node) {
+    if (node.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    const target = node.target;
+    if (target.kind !== expression_1.ExpressionNodeKind.IDENTIFIER)
+        return null;
+    if (target.name !== 'needs')
+        return null;
+    return node.property;
+}
+function resolveJobExecutionKind(jobKey, withBlock, resolved) {
+    const inputs = resolved.actionManifest?.spec.inputs;
+    const inputProps = inputs && typeof inputs === 'object'
+        ? inputs.properties
+        : undefined;
+    const declaresExecutionKindInput = inputProps !== null &&
+        typeof inputProps === 'object' &&
+        'executionKind' in inputProps;
+    if (!declaresExecutionKindInput) {
+        return resolved.executionKind;
+    }
+    const raw = withBlock?.executionKind;
+    if (raw === undefined) {
+        return resolved.executionKind;
+    }
+    if (raw !== workflow_1.ActionExecutionKind.ACTIVITY &&
+        raw !== workflow_1.ActionExecutionKind.CHILD_WORKFLOW) {
+        throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `jobs.${jobKey}.with.executionKind must be the literal '${workflow_1.ActionExecutionKind.ACTIVITY}' or '${workflow_1.ActionExecutionKind.CHILD_WORKFLOW}' — the Temporal dispatch primitive is fixed at compile time, so expressions are not allowed.`, { jobKey, executionKind: raw });
+    }
+    return raw;
+}
+function resolveActionKind(resolved) {
+    if (resolved.isReusableWorkflow)
+        return workflow_1.ActionKind.DISPATCH;
+    const declared = resolved.actionManifest?.spec.actionKind;
+    if (declared === undefined)
+        return workflow_1.ActionKind.GENERIC;
+    const known = new Set(Object.values(workflow_1.ActionKind));
+    return known.has(declared) ? declared : workflow_1.ActionKind.GENERIC;
+}
+function lookupResolvedRef(uses, resolvedRefs) {
+    const ref = resolvedRefs[uses];
+    if (!ref) {
+        const isReusable = uses.startsWith('xema://workflow/');
+        throw new errors_1.WorkflowDslError(isReusable
+            ? workflow_1.WorkflowErrorCode.DSL_UNKNOWN_REUSABLE_WORKFLOW
+            : workflow_1.WorkflowErrorCode.DSL_UNKNOWN_ACTION, `Reference '${uses}' is not present in resolvedRefs map passed to compiler.`, { uses });
+    }
+    return ref;
+}
+function validateAllAuthoredExpressions(doc) {
+    for (const [key, job] of Object.entries(doc.jobs)) {
+        validateJobExpressions(key, job);
+    }
+    const callOutputs = doc.on.workflow_call?.outputs;
+    if (callOutputs) {
+        for (const expr of Object.values(callOutputs)) {
+            const body = (0, expression_1.stripInterpolation)(expr);
+            (0, expression_1.compileExpression)(body);
+        }
+    }
+    (0, concurrency_1.validateConcurrencyGroupTemplate)(doc.concurrency);
+}
+function validateAllLiteralReferences(doc, resolvedAgents, resolvedDeliverableSpecs) {
+    const agentValidationEnabled = Object.keys(resolvedAgents).length > 0;
+    const specValidationEnabled = Object.keys(resolvedDeliverableSpecs).length > 0;
+    if (!agentValidationEnabled && !specValidationEnabled) {
+        return;
+    }
+    for (const [jobKey, job] of Object.entries(doc.jobs)) {
+        validateJobLiteralReferences(jobKey, job, agentValidationEnabled ? resolvedAgents : null, specValidationEnabled ? resolvedDeliverableSpecs : null);
+    }
+}
+function validateJobLiteralReferences(jobKey, job, resolvedAgents, resolvedSpecs) {
+    const withMap = job.with;
+    if (withMap) {
+        if (resolvedAgents) {
+            assertLiteralAgent(jobKey, 'with.agentSlug', withMap['agentSlug'], resolvedAgents);
+            validateReviewerAgents(jobKey, withMap['reviewers'], resolvedAgents);
+        }
+        if (resolvedSpecs) {
+            assertLiteralDeliverableSpec(jobKey, 'with.deliverableSpecRef', withMap['deliverableSpecRef'], resolvedSpecs);
+        }
+        assertVersioningMode(jobKey, withMap['versioning']);
+    }
+}
+function validateReviewerAgents(jobKey, reviewers, resolvedAgents) {
+    if (!Array.isArray(reviewers)) {
+        return;
+    }
+    for (let i = 0; i < reviewers.length; i++) {
+        const reviewer = reviewers[i];
+        if (reviewer === null ||
+            typeof reviewer !== 'object' ||
+            Array.isArray(reviewer)) {
+            continue;
+        }
+        assertLiteralAgent(jobKey, `with.reviewers[${i}].agentSlug`, reviewer['agentSlug'], resolvedAgents);
+    }
+}
+function isLiteralStringValue(value) {
+    return typeof value === 'string' && !value.includes('${{');
+}
+function assertLiteralAgent(jobKey, fieldPath, value, resolvedAgents) {
+    if (!isLiteralStringValue(value)) {
+        return;
+    }
+    if (resolvedAgents[value] !== undefined) {
+        return;
+    }
+    const knownPreview = formatKnownPreview(Object.keys(resolvedAgents));
+    throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_UNKNOWN_AGENT, `Job '${jobKey}' ${fieldPath} = '${value}' is not a registered agent. Known: [${knownPreview}].`, { jobKey, fieldPath, value, knownCount: Object.keys(resolvedAgents).length });
+}
+function assertLiteralDeliverableSpec(jobKey, fieldPath, value, resolvedSpecs) {
+    if (!isLiteralStringValue(value)) {
+        return;
+    }
+    if (resolvedSpecs[value] !== undefined) {
+        return;
+    }
+    const knownPreview = formatKnownPreview(Object.keys(resolvedSpecs));
+    throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_SPEC, `Job '${jobKey}' ${fieldPath} = '${value}' is not a registered deliverable spec. Known: [${knownPreview}].`, { jobKey, fieldPath, value, knownCount: Object.keys(resolvedSpecs).length });
+}
+const VALID_VERSIONING_MODES = ['append', 'new', 'replace'];
+function assertVersioningMode(jobKey, value) {
+    if (value === undefined || value === null)
+        return;
+    if (typeof value === 'string' && value.startsWith('${{'))
+        return;
+    if (typeof value === 'string' &&
+        VALID_VERSIONING_MODES.includes(value)) {
+        return;
+    }
+    throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `Job '${jobKey}' with.versioning = ${JSON.stringify(value)} is not a valid ArtifactVersioningMode. Allowed: [${VALID_VERSIONING_MODES.join(', ')}].`, {
+        jobKey,
+        fieldPath: 'with.versioning',
+        value: typeof value === 'string' ? value : JSON.stringify(value),
+        allowed: [...VALID_VERSIONING_MODES],
+    });
+}
+function formatKnownPreview(keys) {
+    if (keys.length === 0) {
+        return '(none)';
+    }
+    const sorted = [...keys].sort((a, b) => a.localeCompare(b));
+    if (sorted.length <= 12) {
+        return sorted.join(', ');
+    }
+    return `${sorted.slice(0, 12).join(', ')}, … (+${sorted.length - 12} more)`;
+}
+function validateJobExpressions(key, job) {
+    if (job.if !== undefined) {
+        const body = (0, expression_1.stripInterpolation)(job.if);
+        (0, expression_1.compileExpression)(body);
+    }
+    if (job.with) {
+        const extracted = (0, expression_1.extractInterpolations)(job.with, [key, 'with']);
+        for (const ext of extracted)
+            (0, expression_1.compileExpression)(ext.source);
+    }
+    if (job.outputs) {
+        for (const expr of Object.values(job.outputs)) {
+            const body = (0, expression_1.stripInterpolation)(expr);
+            (0, expression_1.compileExpression)(body);
+        }
+    }
+    if (job.strategy && 'dynamic' in job.strategy) {
+        const body = (0, expression_1.stripInterpolation)(job.strategy.dynamic.from);
+        (0, expression_1.compileExpression)(body);
+    }
+}
+function compileOutputsMap(raw, contextLabel) {
+    if (!raw || Object.keys(raw).length === 0) {
+        return Object.freeze({});
+    }
+    const stripped = {};
+    for (const [name, expr] of Object.entries(raw)) {
+        try {
+            stripped[name] = (0, expression_1.stripInterpolation)(expr);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_EXPRESSION_INVALID, `${contextLabel}.${name}: ${message}`, { contextLabel, name, expr });
+        }
+    }
+    return Object.freeze(stripped);
+}
+function compileWorkflowOutputs(workflow) {
+    const raw = workflow.outputs;
+    if (!raw || Object.keys(raw).length === 0) {
+        return Object.freeze({});
+    }
+    const seenSlugs = new Set();
+    const compiled = {};
+    for (const [name, decl] of Object.entries(raw)) {
+        const job = workflow.jobs[decl.fromJob];
+        if (!job) {
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `outputs.${name}: fromJob "${decl.fromJob}" is not a declared job`, { outputName: name, fromJob: decl.fromJob });
+        }
+        if (!job.outputs || !(decl.fromOutput in job.outputs)) {
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `outputs.${name}: job "${decl.fromJob}" does not declare an output named "${decl.fromOutput}"`, { outputName: name, fromJob: decl.fromJob, fromOutput: decl.fromOutput });
+        }
+        if (seenSlugs.has(decl.slug)) {
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `outputs.${name}: slug "${decl.slug}" is already used by another output`, { outputName: name, slug: decl.slug });
+        }
+        seenSlugs.add(decl.slug);
+        if (decl.kind === 'deliverable') {
+            compiled[name] = {
+                kind: 'deliverable',
+                slug: decl.slug,
+                fromJob: decl.fromJob,
+                fromOutput: decl.fromOutput,
+                deliverableSpecRef: decl.deliverableSpecRef,
+                ...(decl.description ? { description: decl.description } : {}),
+            };
+        }
+        else if (decl.kind === 'structured') {
+            compiled[name] = {
+                kind: 'structured',
+                slug: decl.slug,
+                fromJob: decl.fromJob,
+                fromOutput: decl.fromOutput,
+                ...(decl.schemaRef ? { schemaRef: decl.schemaRef } : {}),
+                ...(decl.description ? { description: decl.description } : {}),
+            };
+        }
+        else {
+            compiled[name] = {
+                kind: 'text',
+                slug: decl.slug,
+                fromJob: decl.fromJob,
+                fromOutput: decl.fromOutput,
+                ...(decl.description ? { description: decl.description } : {}),
+            };
+        }
+    }
+    return Object.freeze(compiled);
+}
+function validateMatrixGather(doc) {
+    for (const [jobKey, decl] of Object.entries(doc.jobs)) {
+        const gather = decl.matrixGather;
+        if (!gather || gather.length === 0)
+            continue;
+        for (const target of gather) {
+            if (target === jobKey) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `Job '${jobKey}' matrixGather cannot reference itself.`, { jobKey, target });
+            }
+            const targetDecl = doc.jobs[target];
+            if (!targetDecl) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `Job '${jobKey}' matrixGather references unknown job '${target}'.`, { jobKey, target });
+            }
+            if (!targetDecl.strategy || (!('matrix' in targetDecl.strategy) && !('dynamic' in targetDecl.strategy))) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `Job '${jobKey}' matrixGather references '${target}' which has no matrix/dynamic strategy; gathering only makes sense across matrix entries.`, { jobKey, target });
+            }
+        }
+    }
+}
+function validateAllNeedsAccessShapes(doc) {
+    for (const [jobKey, job] of Object.entries(doc.jobs)) {
+        const consumerBinding = extractConsumerBinding(job);
+        const expressions = collectJobExpressions(jobKey, job);
+        for (const { source, fieldPath } of expressions) {
+            const ast = (0, expression_1.compileExpression)(source);
+            walkNeedsAccesses(ast, (access) => {
+                validateNeedsAccess(doc, jobKey, fieldPath, consumerBinding, access);
+            });
+        }
+    }
+    const callOutputs = doc.on.workflow_call?.outputs;
+    if (callOutputs) {
+        for (const [outputName, expr] of Object.entries(callOutputs)) {
+            const ast = (0, expression_1.compileExpression)((0, expression_1.stripInterpolation)(expr));
+            walkNeedsAccesses(ast, (access) => {
+                validateNeedsAccess(doc, '<workflow_call.outputs>', `on.workflow_call.outputs.${outputName}`, null, access);
+            });
+        }
+    }
+}
+function collectJobExpressions(jobKey, job) {
+    const out = [];
+    if (job.if !== undefined) {
+        out.push({ source: (0, expression_1.stripInterpolation)(job.if), fieldPath: `${jobKey}.if` });
+    }
+    if (job.with) {
+        for (const ext of (0, expression_1.extractInterpolations)(job.with, [jobKey, 'with'])) {
+            out.push({ source: ext.source, fieldPath: ext.path.join('.') });
+        }
+    }
+    if (job.outputs) {
+        for (const [name, expr] of Object.entries(job.outputs)) {
+            out.push({
+                source: (0, expression_1.stripInterpolation)(expr),
+                fieldPath: `${jobKey}.outputs.${name}`,
+            });
+        }
+    }
+    if (job.strategy && 'dynamic' in job.strategy) {
+        out.push({
+            source: (0, expression_1.stripInterpolation)(job.strategy.dynamic.from),
+            fieldPath: `${jobKey}.strategy.dynamic.from`,
+        });
+    }
+    return out;
+}
+function extractConsumerBinding(job) {
+    if (job.strategy && 'dynamic' in job.strategy) {
+        return job.strategy.dynamic.as;
+    }
+    return null;
+}
+function walkNeedsAccesses(node, visit) {
+    const access = matchNeedsAccess(node);
+    if (access !== null) {
+        visit(access);
+        for (const step of access.steps) {
+            if (step.kind === 'index') {
+                walkNeedsAccesses(step.node, visit);
+            }
+        }
+        return;
+    }
+    switch (node.kind) {
+        case expression_1.ExpressionNodeKind.MEMBER:
+            walkNeedsAccesses(node.target, visit);
+            return;
+        case expression_1.ExpressionNodeKind.INDEX:
+            walkNeedsAccesses(node.target, visit);
+            walkNeedsAccesses(node.index, visit);
+            return;
+        case expression_1.ExpressionNodeKind.CALL:
+            for (const arg of node.args)
+                walkNeedsAccesses(arg, visit);
+            return;
+        case expression_1.ExpressionNodeKind.UNARY_NOT:
+            walkNeedsAccesses(node.operand, visit);
+            return;
+        case expression_1.ExpressionNodeKind.BINARY_EQ:
+        case expression_1.ExpressionNodeKind.BINARY_NEQ:
+        case expression_1.ExpressionNodeKind.BINARY_AND:
+        case expression_1.ExpressionNodeKind.BINARY_OR:
+            walkNeedsAccesses(node.left, visit);
+            walkNeedsAccesses(node.right, visit);
+            return;
+        case expression_1.ExpressionNodeKind.LITERAL:
+        case expression_1.ExpressionNodeKind.IDENTIFIER:
+            return;
+    }
+}
+function matchNeedsAccess(node) {
+    const reverseSteps = [];
+    let cursor = node;
+    while (cursor.kind === expression_1.ExpressionNodeKind.MEMBER ||
+        cursor.kind === expression_1.ExpressionNodeKind.INDEX) {
+        if (cursor.kind === expression_1.ExpressionNodeKind.MEMBER) {
+            reverseSteps.push({ kind: 'member', name: cursor.property });
+        }
+        else {
+            reverseSteps.push({ kind: 'index', node: cursor.index });
+        }
+        cursor = cursor.target;
+    }
+    if (cursor.kind !== expression_1.ExpressionNodeKind.IDENTIFIER ||
+        cursor.name !== 'needs') {
+        return null;
+    }
+    const steps = reverseSteps.toReversed();
+    if (steps.length < 2)
+        return null;
+    const first = steps[0];
+    const second = steps[1];
+    if (first.kind !== 'member')
+        return null;
+    if (second.kind !== 'member' || second.name !== 'outputs')
+        return null;
+    return {
+        upstreamJobKey: first.name,
+        steps: steps.slice(2),
+    };
+}
+function validateNeedsAccess(doc, consumerJobKey, fieldPath, consumerBinding, access) {
+    const upstream = doc.jobs[access.upstreamJobKey];
+    if (!upstream) {
+        return;
+    }
+    const isDynamicMatrix = !!upstream.strategy && 'dynamic' in upstream.strategy;
+    const isStaticMatrix = !!upstream.strategy && 'matrix' in upstream.strategy;
+    const isMatrix = isDynamicMatrix || isStaticMatrix;
+    if (!isMatrix) {
+        if (access.steps.length > 0 &&
+            access.steps[0].kind === 'member' &&
+            access.steps[0].name === 'byKey') {
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: cannot read 'byKey' on '${access.upstreamJobKey}' because it is not a matrix job. 'byKey' is only available on matrix jobs that declare 'keyBy:'.`, {
+                consumerJobKey,
+                upstreamJobKey: access.upstreamJobKey,
+                fieldPath,
+            });
+        }
+        return;
+    }
+    const consumerJob = doc.jobs[consumerJobKey];
+    if (consumerJob?.matrixGather?.includes(access.upstreamJobKey)) {
+        rejectByKeyOnGathered(access, consumerJobKey, fieldPath);
+        return;
+    }
+    const keyBy = isDynamicMatrix
+        ? upstream.strategy.dynamic.keyBy ?? null
+        : null;
+    if (access.steps.length === 0)
+        return;
+    const head = access.steps[0];
+    if (head.kind === 'member' && head.name === 'byKey') {
+        validateByKeyChain(access, keyBy, consumerJobKey, consumerBinding, fieldPath);
+        return;
+    }
+    if (head.kind === 'member') {
+        if (head.name === 'length')
+            return;
+        throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: cannot read 'needs.${access.upstreamJobKey}.outputs.${head.name}' because '${access.upstreamJobKey}' is a matrix job — its outputs are indexed by entry, not by field. Choose one: (1) read positionally with 'outputs[<n>].${head.name}'; (2) flatten with 'matrixGather: [${access.upstreamJobKey}]' on '${consumerJobKey}' and drop the '.${head.name}' suffix; (3) add 'keyBy: <field>' to '${access.upstreamJobKey}' and use 'outputs.byKey[<key>].${head.name}'.`, {
+            consumerJobKey,
+            upstreamJobKey: access.upstreamJobKey,
+            fieldPath,
+            offendingProperty: head.name,
+        });
+    }
+}
+function rejectByKeyOnGathered(access, consumerJobKey, fieldPath) {
+    const head = access.steps[0];
+    if (head?.kind === 'member' && head.name === 'byKey') {
+        throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: cannot read 'byKey' on '${access.upstreamJobKey}' because the consumer applies 'matrixGather' which flattens the upstream into an array. Drop 'matrixGather' to enable keyed access, or read positional entries via [n].`, {
+            consumerJobKey,
+            upstreamJobKey: access.upstreamJobKey,
+            fieldPath,
+        });
+    }
+}
+function validateByKeyChain(access, upstreamKeyBy, consumerJobKey, consumerBinding, fieldPath) {
+    if (upstreamKeyBy === null) {
+        throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_MATRIX_KEY_NOT_DECLARED, `Job '${consumerJobKey}' ${fieldPath}: cannot read 'needs.${access.upstreamJobKey}.outputs.byKey' because '${access.upstreamJobKey}' has no 'keyBy:' declared on its matrix strategy. Add 'keyBy: <field>' to '${access.upstreamJobKey}.strategy.dynamic' to expose a keyed map.`, {
+            consumerJobKey,
+            upstreamJobKey: access.upstreamJobKey,
+            fieldPath,
+        });
+    }
+    const indexStep = access.steps[1];
+    if (indexStep?.kind !== 'index') {
+        throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: 'needs.${access.upstreamJobKey}.outputs.byKey' must be followed by '[<key>]'. Use a string literal or 'matrix.<binding>.${upstreamKeyBy}'.`, {
+            consumerJobKey,
+            upstreamJobKey: access.upstreamJobKey,
+            fieldPath,
+        });
+    }
+    assertByKeyIndexShape(indexStep.node, upstreamKeyBy, consumerJobKey, consumerBinding, access.upstreamJobKey, fieldPath);
+}
+function assertByKeyIndexShape(indexNode, upstreamKeyBy, consumerJobKey, consumerBinding, upstreamJobKey, fieldPath) {
+    if (indexNode.kind === expression_1.ExpressionNodeKind.LITERAL &&
+        typeof indexNode.value === 'string') {
+        return;
+    }
+    if (indexNode.kind === expression_1.ExpressionNodeKind.MEMBER ||
+        indexNode.kind === expression_1.ExpressionNodeKind.INDEX) {
+        const path = collectMatrixMemberPath(indexNode);
+        if (path) {
+            if (consumerBinding === null) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: 'matrix.*' indices into 'needs.${upstreamJobKey}.outputs.byKey' require the consumer job to declare its own 'strategy.dynamic'. Use a string literal key instead, or convert '${consumerJobKey}' into a dynamic matrix.`, { consumerJobKey, upstreamJobKey, fieldPath });
+            }
+            if (path.binding !== consumerBinding) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: 'matrix.${path.binding}' is not bound here — '${consumerJobKey}' binds 'matrix.${consumerBinding}'.`, { consumerJobKey, upstreamJobKey, fieldPath });
+            }
+            if (path.path !== upstreamKeyBy) {
+                throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: 'byKey' index reads 'matrix.${path.binding}.${path.path}' but '${upstreamJobKey}' is keyed by '${upstreamKeyBy}'. Match the upstream's 'keyBy:' path or change the upstream's 'keyBy:' to '${path.path}'.`, { consumerJobKey, upstreamJobKey, fieldPath });
+            }
+            return;
+        }
+    }
+    throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_INVALID_MATRIX_OUTPUT_ACCESS, `Job '${consumerJobKey}' ${fieldPath}: 'needs.${upstreamJobKey}.outputs.byKey[…]' index must be a string literal or 'matrix.<binding>.${upstreamKeyBy}'.`, { consumerJobKey, upstreamJobKey, fieldPath });
+}
+function collectMatrixMemberPath(node) {
+    const reverseProperties = [];
+    let cursor = node;
+    while (cursor.kind === expression_1.ExpressionNodeKind.MEMBER) {
+        reverseProperties.push(cursor.property);
+        cursor = cursor.target;
+    }
+    if (cursor.kind !== expression_1.ExpressionNodeKind.IDENTIFIER ||
+        cursor.name !== 'matrix') {
+        return null;
+    }
+    const props = reverseProperties.toReversed();
+    if (props.length < 2)
+        return null;
+    const [binding, ...rest] = props;
+    return { binding: binding, path: rest.join('.') };
+}
+function assertStrategyInvariants(compiled) {
+    for (const job of compiled.jobs) {
+        if (job.strategy.kind === workflow_1.MatrixStrategyKind.STATIC && job.strategy.entries.length === 0) {
+            throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_SEMANTIC_INVALID, `Job '${job.jobKey}' static strategy expansion produced zero entries.`, { jobKey: job.jobKey });
+        }
+    }
+    const _permissionRef = compiled.permissions;
+    void _permissionRef;
+}
+function validateDeliverableValueExpressions(doc, resolvedSpecs) {
+    if (Object.keys(resolvedSpecs).length === 0)
+        return;
+    for (const [jobKey, job] of Object.entries(doc.jobs)) {
+        const expressions = collectJobExpressions(jobKey, job);
+        for (const { source, fieldPath } of expressions) {
+            const ast = (0, expression_1.compileExpression)(source);
+            walkDeliverableAccesses(ast, (access) => {
+                validateDeliverableAccess(doc, jobKey, fieldPath, access, resolvedSpecs);
+            });
+        }
+    }
+    const callOutputs = doc.on.workflow_call?.outputs;
+    if (callOutputs) {
+        for (const [outputName, expr] of Object.entries(callOutputs)) {
+            const ast = (0, expression_1.compileExpression)((0, expression_1.stripInterpolation)(expr));
+            walkDeliverableAccesses(ast, (access) => {
+                validateDeliverableAccess(doc, '<workflow_call.outputs>', `on.workflow_call.outputs.${outputName}`, access, resolvedSpecs);
+            });
+        }
+    }
+}
+function walkDeliverableAccesses(node, visit) {
+    const valueField = matchDeliverableValueFieldAccess(node);
+    if (valueField !== null) {
+        visit(valueField);
+        return;
+    }
+    switch (node.kind) {
+        case expression_1.ExpressionNodeKind.MEMBER:
+            walkDeliverableAccesses(node.target, visit);
+            return;
+        case expression_1.ExpressionNodeKind.INDEX:
+            walkDeliverableAccesses(node.target, visit);
+            walkDeliverableAccesses(node.index, visit);
+            return;
+        case expression_1.ExpressionNodeKind.CALL:
+            for (const arg of node.args)
+                walkDeliverableAccesses(arg, visit);
+            return;
+        case expression_1.ExpressionNodeKind.UNARY_NOT:
+            walkDeliverableAccesses(node.operand, visit);
+            return;
+        case expression_1.ExpressionNodeKind.BINARY_EQ:
+        case expression_1.ExpressionNodeKind.BINARY_NEQ:
+        case expression_1.ExpressionNodeKind.BINARY_AND:
+        case expression_1.ExpressionNodeKind.BINARY_OR:
+            walkDeliverableAccesses(node.left, visit);
+            walkDeliverableAccesses(node.right, visit);
+            return;
+        case expression_1.ExpressionNodeKind.LITERAL:
+        case expression_1.ExpressionNodeKind.IDENTIFIER:
+            return;
+    }
+}
+function matchDeliverableValueFieldAccess(node) {
+    if (node.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    const field = node.property;
+    const valueNode = node.target;
+    if (valueNode.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    if (valueNode.property !== 'value')
+        return null;
+    const contentNode = valueNode.target;
+    if (contentNode.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    if (contentNode.property !== 'content')
+        return null;
+    const deliverableNode = contentNode.target;
+    if (deliverableNode.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    if (deliverableNode.property !== 'deliverable')
+        return null;
+    const outputsNode = deliverableNode.target;
+    if (outputsNode.kind !== expression_1.ExpressionNodeKind.MEMBER)
+        return null;
+    if (outputsNode.property !== 'outputs')
+        return null;
+    const rootNode = outputsNode.target;
+    if (rootNode.kind === expression_1.ExpressionNodeKind.IDENTIFIER &&
+        rootNode.name === 'job') {
+        return { upstreamJobKey: null, field };
+    }
+    if (rootNode.kind === expression_1.ExpressionNodeKind.MEMBER) {
+        const needsRoot = rootNode.target;
+        if (needsRoot.kind === expression_1.ExpressionNodeKind.IDENTIFIER &&
+            needsRoot.name === 'needs') {
+            return {
+                upstreamJobKey: rootNode.property,
+                field,
+            };
+        }
+        if (needsRoot.kind === expression_1.ExpressionNodeKind.MEMBER) {
+            const upstreamRoot = needsRoot.target;
+            if (needsRoot.property === 'outputs' &&
+                upstreamRoot.kind === expression_1.ExpressionNodeKind.MEMBER) {
+                const needsParent = upstreamRoot.target;
+                if (upstreamRoot.property === 'byKey' &&
+                    needsParent.kind === expression_1.ExpressionNodeKind.IDENTIFIER &&
+                    needsParent.name === 'needs') {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+function validateDeliverableAccess(doc, consumerJobKey, fieldPath, access, resolvedSpecs) {
+    const producingJobKey = access.upstreamJobKey ?? consumerJobKey;
+    const producingJob = doc.jobs[producingJobKey];
+    if (!producingJob)
+        return;
+    if (access.upstreamJobKey !== null) {
+        if (producingJob.outputs && Object.keys(producingJob.outputs).length > 0) {
+            return;
+        }
+    }
+    const withMap = producingJob.with;
+    const specRef = withMap?.['deliverableSpecRef'];
+    if (typeof specRef !== 'string' || specRef.length === 0)
+        return;
+    if (specRef.includes('${{'))
+        return;
+    const spec = resolvedSpecs[specRef];
+    if (!spec)
+        return;
+    if (!spec.topLevelKeys || spec.topLevelKeys.length === 0)
+        return;
+    if (spec.topLevelKeys.includes(access.field))
+        return;
+    const knownPreview = formatKnownPreview(spec.topLevelKeys);
+    throw new errors_1.WorkflowDslError(workflow_1.WorkflowErrorCode.DSL_UNKNOWN_DELIVERABLE_FIELD, `${fieldPath}: deliverable.content.value.${access.field} is not a top-level field on deliverable spec '${spec.ref}' (produced by job '${producingJobKey}'). Known fields: [${knownPreview}].`, {
+        consumerJobKey,
+        fieldPath,
+        producingJobKey,
+        specRef: spec.ref,
+        field: access.field,
+        knownFields: [...spec.topLevelKeys],
+    });
+}
+//# sourceMappingURL=compile.js.map