adfinem 0.0.0 → 0.1.1

package/dist/engine/runner.js

@@ -0,0 +1,710 @@
+import { mkdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { EvidenceWriter } from "./evidence.js";
+import { RunContext } from "./context.js";
+import { cancelledStep, durationBetween, failedStep, hashInput, isCancellationError } from "./step-result.js";
+import { RestClient } from "../adapters/api/rest-client.js";
+import { SoapClient } from "../adapters/api/soap-client.js";
+import { OracleClient } from "../adapters/db/oracle-client.js";
+import { assertQueryResult } from "../adapters/db/assertions.js";
+import { SshClient } from "../adapters/unix/ssh-client.js";
+import { BatchRunner } from "../adapters/unix/batch-runner.js";
+import { runBatch } from "../actions/run-eod.js";
+import { writeHtmlReport } from "../reports/html-report.js";
+import { writeJunitReport } from "../reports/junit-report.js";
+import { extractCaptures, mergeCaptureSpecs } from "./captures.js";
+import { applyEvidenceVisibility, evidenceVisibilityMode } from "../config/secrets.js";
+export class ScenarioRunner {
+    scenario;
+    catalogs;
+    env;
+    options;
+    context;
+    evidence;
+    restClient;
+    soapClient;
+    oracleClient;
+    batchRunner;
+    visibility;
+    constructor(scenario, catalogs, env, options) {
+        this.scenario = scenario;
+        this.catalogs = catalogs;
+        this.env = env;
+        this.options = options;
+        this.context = new RunContext(scenario);
+        const runId = `${scenario.id}-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+        this.visibility = evidenceVisibilityMode();
+        this.evidence = new EvidenceWriter(join(options.rootDir, "evidence", runId), this.visibility);
+        this.restClient = new RestClient(env, options.rootDir);
+        this.soapClient = new SoapClient();
+        this.oracleClient = new OracleClient(env);
+        this.batchRunner = new BatchRunner(new SshClient(env), options.rootDir);
+    }
+    async run() {
+        await this.evidence.init();
+        const startedAt = new Date().toISOString();
+        const steps = [];
+        let cursor = 0;
+        for (const step of this.scenario.steps) {
+            if (this.isStopped()) {
+                steps.push(cancelledStep(step.id, this.layerFor(step), new Date().toISOString(), step.input ?? step.params ?? {}));
+                for (const skipped of this.scenario.steps.slice(steps.length)) {
+                    steps.push(this.skipStep(skipped, `Skipped because run was stopped before step '${step.id}'.`));
+                }
+                break;
+            }
+            const results = await this.executePlanStep(step, cursor);
+            cursor += results.length;
+            steps.push(...results);
+            const controlResult = results[0] ?? results[results.length - 1];
+            if (results.some((result) => result.status === "cancelled")) {
+                for (const skipped of this.scenario.steps.slice(steps.length)) {
+                    steps.push(this.skipStep(skipped, `Skipped because run was stopped during step '${step.id}'.`));
+                }
+                break;
+            }
+            if (controlResult?.status === "failed" && !step.continueOnFailure) {
+                for (const skipped of this.scenario.steps.slice(steps.length)) {
+                    steps.push(this.skipStep(skipped, `Skipped because previous step '${step.id}' failed.`));
+                }
+                break;
+            }
+        }
+        const endedAt = new Date().toISOString();
+        const startedMs = Date.parse(startedAt);
+        const endedMs = Date.parse(endedAt);
+        const durationMs = Number.isFinite(startedMs) && Number.isFinite(endedMs)
+            ? Math.max(0, endedMs - startedMs)
+            : undefined;
+        const result = {
+            scenarioId: this.scenario.id,
+            runId: basename(this.evidence.runDir) || this.scenario.id,
+            status: steps.some((step) => step.status === "cancelled")
+                ? "cancelled"
+                : steps.some((step) => step.status === "failed") ? "failed" : "passed",
+            startedAt,
+            endedAt,
+            evidenceDir: this.evidence.runDir,
+            steps,
+            durationMs
+        };
+        const visibleResult = applyEvidenceVisibility(result, this.visibility);
+        const runResultPath = await this.evidence.writeJson("run-result.json", visibleResult);
+        const reportPath = await writeHtmlReport(visibleResult);
+        const junitPath = await writeJunitReport(visibleResult);
+        await this.evidence.writeJson("evidence-manifest.json", buildEvidenceManifest(result, {
+            runResultPath,
+            reportPath,
+            junitPath
+        }));
+        return visibleResult;
+    }
+    async executePlanStep(step, index) {
+        if (step.control === "parallel" || step.action === "__parallel")
+            return this.executeParallelStep(step, index);
+        if (step.control === "loop" || step.action === "__loop")
+            return this.executeLoopStep(step, index);
+        return [await this.executeStep(step, index)];
+    }
+    async executeParallelStep(step, index) {
+        const startedAt = new Date().toISOString();
+        const branches = step.branches ?? [];
+        const branchResults = await Promise.all(branches.map(async (branch, branchIndex) => {
+            const results = [];
+            let localIndex = index + branchIndex + 1;
+            for (const branchStep of branch.steps) {
+                if (this.isStopped()) {
+                    results.push(cancelledStep(branchStep.id, this.layerFor(branchStep), new Date().toISOString(), branchStep.input ?? branchStep.params ?? {}));
+                    break;
+                }
+                const next = await this.executePlanStep(branchStep, localIndex);
+                localIndex += next.length;
+                results.push(...next);
+                const failed = next[0]?.status === "failed" || next.some((result) => result.status === "cancelled");
+                if (failed && !branchStep.continueOnFailure)
+                    break;
+            }
+            return { branch, results };
+        }));
+        const flattened = branchResults.flatMap((branch) => branch.results);
+        const join = step.join ?? "all";
+        const branchPassed = branchResults.map((branch) => branch.results.length > 0 && !branch.results.some((result) => result.status === "failed" || result.status === "cancelled"));
+        const passed = join === "any" ? branchPassed.some(Boolean) : branchPassed.every(Boolean);
+        const endedAt = new Date().toISOString();
+        const group = {
+            stepId: step.id,
+            layer: "engine",
+            status: flattened.some((result) => result.status === "cancelled") ? "cancelled" : passed ? "passed" : "failed",
+            startedAt,
+            endedAt,
+            durationMs: durationBetween(startedAt, endedAt),
+            inputHash: hashInput({ branches: branches.map((branch) => branch.id), join }),
+            captures: {},
+            evidence: [],
+            error: passed ? undefined : {
+                message: `Parallel block '${step.id}' failed using '${join}' join semantics.`
+            }
+        };
+        return [group, ...flattened];
+    }
+    async executeLoopStep(step, index) {
+        const startedAt = new Date().toISOString();
+        const iterations = this.loopIterations(step);
+        const allResults = [];
+        const aggregate = new Map();
+        let failed = false;
+        const loopSteps = step.steps ?? [];
+        for (let i = 0; i < iterations.items.length; i += 1) {
+            if (this.isStopped()) {
+                allResults.push(cancelledStep(`${step.id}_${i}`, "engine", new Date().toISOString(), {}));
+                failed = true;
+                break;
+            }
+            this.context.set(`${step.id}.index`, i);
+            this.context.set(`${step.id}.number`, i + 1);
+            this.context.set(`${step.id}.total`, iterations.items.length);
+            this.context.set(`${step.id}.item`, iterations.items[i]);
+            if (iterations.itemName) {
+                this.context.set(iterations.itemName, iterations.items[i]);
+                this.context.set(`${step.id}.${iterations.itemName}`, iterations.items[i]);
+            }
+            const dateCursor = step.loop?.dateCursor;
+            if (dateCursor) {
+                const outputName = loopDateOutputName(dateCursor);
+                const value = computeLoopDateCursorValue(dateCursor, i, (candidate) => this.context.resolve(candidate));
+                this.context.set(outputName, value);
+                this.context.set(`${step.id}.${outputName}`, value);
+                this.context.set(`${step.id}[${i}].${outputName}`, value);
+                this.context.set(`${step.id}.${i}.${outputName}`, value);
+                this.context.set(`${step.id}.last.${outputName}`, value);
+                const aggregateKey = `${step.id}.all.${outputName}`;
+                const values = aggregate.get(aggregateKey) ?? [];
+                values.push(value);
+                aggregate.set(aggregateKey, values);
+                this.context.set(aggregateKey, values);
+            }
+            for (const child of loopSteps) {
+                const scopedChild = scopedLoopStep(child, step.id, i);
+                const childResults = await this.executePlanStep(scopedChild, index + allResults.length + 1);
+                allResults.push(...childResults);
+                const publishable = childResults.filter((result) => result.status === "passed");
+                for (const result of publishable) {
+                    for (const [capture, value] of Object.entries(result.captures)) {
+                        this.context.set(`${child.id}.${capture}`, value);
+                        this.context.set(`${step.id}[${i}].${child.id}.${capture}`, value);
+                        this.context.set(`${step.id}.${i}.${child.id}.${capture}`, value);
+                        this.context.set(`${step.id}.last.${child.id}.${capture}`, value);
+                        const aggregateKey = `${step.id}.all.${child.id}.${capture}`;
+                        const values = aggregate.get(aggregateKey) ?? [];
+                        values.push(value);
+                        aggregate.set(aggregateKey, values);
+                        this.context.set(aggregateKey, values);
+                    }
+                }
+                if (childResults[0]?.status === "failed" && !child.continueOnFailure) {
+                    failed = true;
+                    break;
+                }
+            }
+            if (failed && !step.continueOnFailure)
+                break;
+        }
+        const endedAt = new Date().toISOString();
+        const group = {
+            stepId: step.id,
+            layer: "engine",
+            status: allResults.some((result) => result.status === "cancelled") ? "cancelled" : failed ? "failed" : "passed",
+            startedAt,
+            endedAt,
+            durationMs: durationBetween(startedAt, endedAt),
+            inputHash: hashInput(step.loop ?? {}),
+            captures: Object.fromEntries(aggregate),
+            evidence: [],
+            error: failed ? { message: `Loop '${step.id}' failed before completing all iterations.` } : undefined
+        };
+        return [group, ...allResults];
+    }
+    loopIterations(step) {
+        const spec = step.loop ?? { mode: "count", count: 1 };
+        const maxIterations = spec.maxIterations ?? 1000;
+        if (spec.mode === "count") {
+            const resolved = this.context.resolve(spec.count ?? 1);
+            const count = Number(resolved);
+            if (!Number.isInteger(count) || count < 0)
+                throw new Error(`Loop '${step.id}' count must resolve to a non-negative integer.`);
+            if (count > maxIterations)
+                throw new Error(`Loop '${step.id}' count ${count} exceeds maxIterations ${maxIterations}.`);
+            return { items: Array.from({ length: count }, (_value, index) => index), itemName: spec.itemName };
+        }
+        const resolved = this.context.resolve(spec.items);
+        const items = Array.isArray(resolved) ? resolved : resolved === undefined || resolved === null ? [] : [resolved];
+        if (items.length > maxIterations)
+            throw new Error(`Loop '${step.id}' foreach item count ${items.length} exceeds maxIterations ${maxIterations}.`);
+        return { items, itemName: spec.itemName ?? "item" };
+    }
+    async executeStep(step, index) {
+        const startedAt = new Date().toISOString();
+        const layer = this.layerFor(step);
+        let resolvedInput = step.input ?? step.params ?? {};
+        const evidence = [];
+        let inputEvidenceWritten = false;
+        this.options.onStepStart?.({ stepId: step.id, layer, startedAt, index });
+        const finish = (result) => {
+            this.options.onStepResult?.(result);
+            return result;
+        };
+        try {
+            resolvedInput = this.context.resolve(step.input ?? step.params ?? {});
+            evidence.push(await this.evidence.writeJson(`${step.id}.input.json`, resolvedInput));
+            inputEvidenceWritten = true;
+            if (this.options.dryRun) {
+                const captures = await this.dryRunCaptures(step);
+                this.publishCaptures(step.id, captures);
+                const dryPayload = { step, resolvedInput, captures, context: this.context.snapshot() };
+                evidence.push(await this.evidence.writeJson(`${step.id}.dry-run.json`, dryPayload));
+                return finish(this.passedStep(step.id, layer, startedAt, resolvedInput, captures, evidence));
+            }
+            const result = await this.dispatch(step, resolvedInput, evidence, index);
+            if (result.status === "failed") {
+                return finish(this.failedEvaluatedStep(step.id, layer, startedAt, resolvedInput, result.captures, evidence, result.message ?? "Step failed.", result.api, result.unix));
+            }
+            this.publishCaptures(step.id, result.captures);
+            return finish(this.passedStep(step.id, layer, startedAt, resolvedInput, result.captures, evidence, result.api, result.unix));
+        }
+        catch (error) {
+            if (!inputEvidenceWritten) {
+                const unresolvedInput = await this.evidence.writeJson(`${step.id}.input-unresolved.json`, resolvedInput).catch(() => undefined);
+                if (unresolvedInput)
+                    evidence.push(unresolvedInput);
+            }
+            if (isCancellationError(error)) {
+                return finish(cancelledStep(step.id, layer, startedAt, resolvedInput, evidence));
+            }
+            const failureEvidence = await this.writeFailureCheckpoint(step, startedAt, resolvedInput, error).catch(() => undefined);
+            if (failureEvidence)
+                evidence.push(failureEvidence);
+            return finish(failedStep(step.id, layer, startedAt, resolvedInput, error, evidence));
+        }
+    }
+    async dispatch(step, input, evidence, index) {
+        if (step.via === "api") {
+            const operation = this.catalogs.apiOperations[step.action];
+            if (!operation)
+                throw new Error(`Unknown API operation '${step.action}'.`);
+            const request = step.request ? this.context.resolve(step.request) : undefined;
+            const result = operation.type === "soap"
+                ? await this.soapClient.execute(operation, input)
+                : await this.restClient.execute(operation, input, request, step.assertions ?? [], step.capture ?? {}, {
+                    expectedOutcome: step.expectedOutcome,
+                    captureOnFailure: step.captureOnFailure,
+                    visibility: this.visibility
+                });
+            if (operation.type === "soap") {
+                const captures = { ...result.captures, ...pickExplicitCaptures(result.response, step.capture ?? {}) };
+                evidence.push(await this.evidence.writeJson(`${step.id}.api.json`, result.evidencePayload));
+                return { status: "passed", captures };
+            }
+            const api = result.apiEvidence;
+            const stepFolder = stepEvidenceFolder(index, step.id);
+            evidence.push(await this.evidence.writeJson(`${step.id}.api.json`, result.evidencePayload));
+            if (api.request)
+                evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/request.json`, { request: api.request, resolvedRequest: api.resolvedRequest }));
+            if (api.response)
+                evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/response.json`, api.response));
+            evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/assertions.json`, api.assertionResults));
+            evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/captures.json`, api.evidenceCaptures));
+            return {
+                status: api.finalStatus,
+                captures: result.captures,
+                api,
+                message: api.failureReason
+            };
+        }
+        if (step.action === "db_assert" || step.action === "db_query" || step.action === "db_execute") {
+            if (!step.query)
+                throw new Error(`${step.action} requires query.`);
+            const entry = this.catalogs.queries[step.query];
+            const stepFolder = stepEvidenceFolder(index, step.id);
+            if (step.action === "db_execute") {
+                if (entry.mode !== "execute")
+                    throw new Error(`DB Action Library template '${step.query}' must be marked mode: execute.`);
+                const result = await this.oracleClient.execute(entry, input);
+                const payload = { query: step.query, ...result };
+                const captureResult = evaluateCaptures(payload, mergeCaptureSpecs(entry.captures, step.capture));
+                const evidencePayload = { ...payload, captures: captureResult.captures, captureError: errorSummary(captureResult.error) };
+                evidence.push(await this.evidence.writeJson(`${step.id}.db-execute.json`, evidencePayload));
+                evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/db-execute.json`, evidencePayload));
+                if (captureResult.error) {
+                    return { status: "failed", captures: {}, message: dbCaptureFailureMessage(payload, captureResult.error) };
+                }
+                return { status: "passed", captures: captureResult.captures };
+            }
+            const rows = await this.oracleClient.query(entry, input);
+            const payload = { query: step.query, rowCount: rows.length, rows };
+            const assertionResult = evaluateDbExpectation(step.action, entry, rows);
+            const captureResult = evaluateCaptures(payload, mergeCaptureSpecs(entry.captures, step.capture));
+            const evidencePayload = {
+                ...payload,
+                assertionError: errorSummary(assertionResult.error),
+                captures: captureResult.captures,
+                captureError: errorSummary(captureResult.error)
+            };
+            evidence.push(await this.evidence.writeJson(`${step.id}.db.json`, evidencePayload));
+            evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/db.json`, evidencePayload));
+            if (assertionResult.error) {
+                return { status: "failed", captures: {}, message: dbQueryFailureMessage(payload, assertionResult.error) };
+            }
+            if (captureResult.error) {
+                return { status: "failed", captures: {}, message: dbCaptureFailureMessage(payload, captureResult.error) };
+            }
+            return { status: "passed", captures: captureResult.captures };
+        }
+        if (step.action === "unix_batch") {
+            if (!step.batch)
+                throw new Error("unix_batch requires batch.");
+            const stepFolder = stepEvidenceFolder(index, step.id);
+            const result = await runBatch(this.batchRunner, this.catalogs.batches[step.batch], input, {
+                attempts: step.retry?.attempts,
+                delayMs: step.retry?.delaySeconds === undefined ? undefined : step.retry.delaySeconds * 1000,
+                downloadDir: join(this.evidence.runDir, ...stepFolder.split("/"), "files"),
+                signal: this.options.signal
+            });
+            evidence.push(await this.evidence.writeJson(`${step.id}.unix.json`, result));
+            evidence.push(await this.evidence.writeJsonPath(`${stepFolder}/unix.json`, result));
+            if (result.status !== "passed") {
+                const last = result.attempts[result.attempts.length - 1];
+                return {
+                    status: "failed",
+                    captures: {},
+                    unix: result,
+                    message: last?.error ?? `Batch '${step.batch}' failed.`
+                };
+            }
+            const captures = extractCaptures(result, mergeCaptureSpecs(this.catalogs.batches[step.batch].captures, step.capture));
+            if (Object.keys(captures).length > 0) {
+                evidence.push(await this.evidence.writeJson(`${step.id}.unix-captures.json`, captures));
+            }
+            return { status: "passed", captures, unix: result };
+        }
+        throw new Error(`No executor for action '${step.action}' via '${step.via ?? ""}'.`);
+    }
+    passedStep(stepId, layer, startedAt, input, captures, evidence, api, unix) {
+        const endedAt = new Date().toISOString();
+        return {
+            stepId,
+            layer,
+            status: "passed",
+            startedAt,
+            endedAt,
+            durationMs: durationBetween(startedAt, endedAt),
+            inputHash: hashInput(input),
+            captures,
+            evidence,
+            api,
+            unix
+        };
+    }
+    failedEvaluatedStep(stepId, layer, startedAt, input, captures, evidence, message, api, unix) {
+        const endedAt = new Date().toISOString();
+        return {
+            stepId,
+            layer,
+            status: "failed",
+            startedAt,
+            endedAt,
+            durationMs: durationBetween(startedAt, endedAt),
+            inputHash: hashInput(input),
+            captures,
+            evidence,
+            api,
+            unix,
+            error: {
+                message,
+                rawOutput: api?.response
+                    ? `HTTP ${api.response.status} ${api.response.statusText}`
+                    : unix
+                        ? unixFailureSummary(unix)
+                        : undefined
+            }
+        };
+    }
+    skipStep(step, reason) {
+        const now = new Date().toISOString();
+        return {
+            stepId: step.id,
+            layer: this.layerFor(step),
+            status: "skipped",
+            startedAt: now,
+            endedAt: now,
+            durationMs: 0,
+            inputHash: hashInput({}),
+            captures: {},
+            evidence: [],
+            error: {
+                message: reason
+            }
+        };
+    }
+    async writeFailureCheckpoint(step, startedAt, input, error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        const context = this.context.snapshot();
+        return await this.evidence.writeJson(`${step.id}.failure.json`, {
+            step,
+            input,
+            error: {
+                message: err.message,
+                stack: err.stack
+            },
+            context,
+            startedAt
+        });
+    }
+    layerFor(step) {
+        if (step.control || step.via === "control")
+            return "engine";
+        if (step.action === "db_assert" || step.action === "db_query" || step.action === "db_execute")
+            return "db";
+        if (step.action === "unix_batch")
+            return "unix";
+        if (step.via === "api")
+            return "api";
+        return "engine";
+    }
+    async dryRunCaptures(step) {
+        const captures = {};
+        if (step.via === "api") {
+            for (const name of Object.keys(this.catalogs.apiOperations[step.action]?.captures ?? {})) {
+                captures[name] = `<dry-run:${name}>`;
+            }
+        }
+        if (step.query) {
+            for (const name of Object.keys(this.catalogs.queries[step.query]?.captures ?? {})) {
+                captures[name] = `<dry-run:${name}>`;
+            }
+        }
+        if (step.batch) {
+            for (const name of Object.keys(this.catalogs.batches[step.batch]?.captures ?? {})) {
+                captures[name] = `<dry-run:${name}>`;
+            }
+        }
+        for (const name of Object.keys(step.capture ?? {})) {
+            captures[name] = `<dry-run:${name}>`;
+        }
+        return captures;
+    }
+    publishCaptures(stepId, captures) {
+        for (const [name, value] of Object.entries(captures)) {
+            this.context.set(name, value);
+            this.context.set(`${stepId}.${name}`, value);
+        }
+    }
+    isStopped() {
+        return Boolean(this.options.signal?.aborted);
+    }
+}
+function scopedLoopStep(step, loopId, index) {
+    const scopedId = `${loopId}_${index}_${step.id}`;
+    if (step.control === "parallel" || step.control === "loop" || step.action === "__parallel" || step.action === "__loop") {
+        return {
+            ...step,
+            id: scopedId,
+            branches: step.branches?.map((branch) => ({
+                ...branch,
+                steps: branch.steps.map((child) => scopedLoopStep(child, loopId, index))
+            })),
+            steps: step.steps?.map((child) => scopedLoopStep(child, loopId, index))
+        };
+    }
+    return {
+        ...step,
+        id: scopedId
+    };
+}
+function loopDateOutputName(cursor) {
+    return cursor.outputName?.trim() || "business_date";
+}
+function computeLoopDateCursorValue(cursor, index, resolve) {
+    const startValue = resolve(cursor.start ?? "");
+    if (typeof startValue !== "string" || !startValue.trim()) {
+        throw new Error("Loop business date start value is required.");
+    }
+    const inputFormat = cursor.inputFormat ?? detectLoopDateFormat(startValue);
+    const outputFormat = cursor.outputFormat ?? inputFormat;
+    const base = parseLoopDate(startValue, inputFormat);
+    const advance = cursor.advance ?? { mode: "months", amount: 1 };
+    const amount = Math.max(1, Number(advance.amount ?? 1));
+    let next;
+    if (advance.mode === "days") {
+        next = addDays(base, amount * index);
+    }
+    else if (advance.mode === "months") {
+        next = addMonthsClamped(base, amount * index);
+    }
+    else {
+        const monthBase = addMonthsClamped(new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth(), 1)), amount * index);
+        if (advance.mode === "first_of_month") {
+            next = monthBase;
+        }
+        else if (advance.mode === "end_of_month") {
+            next = new Date(Date.UTC(monthBase.getUTCFullYear(), monthBase.getUTCMonth(), daysInMonth(monthBase.getUTCFullYear(), monthBase.getUTCMonth())));
+        }
+        else {
+            const requestedDay = Math.max(1, Math.min(31, Number(advance.day ?? base.getUTCDate())));
+            next = new Date(Date.UTC(monthBase.getUTCFullYear(), monthBase.getUTCMonth(), Math.min(requestedDay, daysInMonth(monthBase.getUTCFullYear(), monthBase.getUTCMonth()))));
+        }
+    }
+    return formatLoopDate(next, outputFormat);
+}
+function detectLoopDateFormat(value) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return "YYYY-MM-DD";
+    return "DD/MM/YYYY";
+}
+function parseLoopDate(value, format) {
+    const trimmed = value.trim();
+    let year;
+    let month;
+    let day;
+    if (format === "YYYY-MM-DD") {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+        if (!match)
+            throw new Error(`Loop business date '${value}' must match YYYY-MM-DD.`);
+        year = Number(match[1]);
+        month = Number(match[2]);
+        day = Number(match[3]);
+    }
+    else {
+        const match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(trimmed);
+        if (!match)
+            throw new Error(`Loop business date '${value}' must match ${format}.`);
+        year = Number(match[3]);
+        if (format === "DD/MM/YYYY") {
+            day = Number(match[1]);
+            month = Number(match[2]);
+        }
+        else {
+            month = Number(match[1]);
+            day = Number(match[2]);
+        }
+    }
+    const maxDay = daysInMonth(year, month - 1);
+    if (month < 1 || month > 12 || day < 1 || day > maxDay) {
+        throw new Error(`Loop business date '${value}' is not a valid calendar date.`);
+    }
+    return new Date(Date.UTC(year, month - 1, day));
+}
+function formatLoopDate(date, format) {
+    const year = String(date.getUTCFullYear()).padStart(4, "0");
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(date.getUTCDate()).padStart(2, "0");
+    if (format === "YYYY-MM-DD")
+        return `${year}-${month}-${day}`;
+    if (format === "MM/DD/YYYY")
+        return `${month}/${day}/${year}`;
+    return `${day}/${month}/${year}`;
+}
+function addDays(date, days) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
+}
+function addMonthsClamped(date, months) {
+    const targetMonth = date.getUTCMonth() + months;
+    const first = new Date(Date.UTC(date.getUTCFullYear(), targetMonth, 1));
+    const day = Math.min(date.getUTCDate(), daysInMonth(first.getUTCFullYear(), first.getUTCMonth()));
+    return new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth(), day));
+}
+function daysInMonth(year, zeroBasedMonth) {
+    return new Date(Date.UTC(year, zeroBasedMonth + 1, 0)).getUTCDate();
+}
+function unixFailureSummary(unix) {
+    const last = unix.attempts[unix.attempts.length - 1];
+    if (!last)
+        return undefined;
+    const displayCommand = last.displayCommand ?? unix.displayCommand ?? last.command;
+    const parts = [
+        `Command: ${displayCommand}`,
+        last.command && last.command !== displayCommand
+            ? `Shell-safe command: ${last.command}`
+            : undefined,
+        last.exitCode === undefined ? undefined : `Exit code: ${last.exitCode}`,
+        last.tracePath ? `Script trace path: ${last.tracePath}` : undefined,
+        last.errno ? `Script ERRNO: ${last.errno}` : undefined,
+        last.stdout ? `stdout:\n${last.stdout}` : undefined,
+        last.stderr ? `stderr:\n${last.stderr}` : undefined
+    ].filter(Boolean);
+    return parts.length ? parts.join("\n\n") : undefined;
+}
+function stepEvidenceFolder(index, stepId) {
+    return `steps/${String(index + 1).padStart(2, "0")}_${stepId}`;
+}
+function pickExplicitCaptures(data, captureSpec) {
+    if (!captureSpec)
+        return {};
+    return extractCaptures(data, captureSpec);
+}
+function evaluateCaptures(payload, captureSpec) {
+    try {
+        return { captures: extractCaptures(payload, captureSpec) };
+    }
+    catch (error) {
+        return { captures: {}, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
+function evaluateDbExpectation(action, entry, rows) {
+    if (action !== "db_assert")
+        return {};
+    try {
+        assertQueryResult(entry, rows);
+        return {};
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error : new Error(String(error)) };
+    }
+}
+function errorSummary(error) {
+    return error ? { message: error.message, stack: error.stack } : undefined;
+}
+function dbQueryFailureMessage(payload, error) {
+    return `${error.message} ${dbPayloadDetails(payload)}`;
+}
+function dbCaptureFailureMessage(payload, error) {
+    return `${error.message} ${dbPayloadDetails(payload)}`;
+}
+function dbPayloadDetails(payload) {
+    const rowCount = payload.rowCount ?? payload.rows?.length;
+    const columns = availableColumns(payload.rows ?? []);
+    const parts = [`DB query '${payload.query}' returned ${rowCount ?? 0} row${rowCount === 1 ? "" : "s"}.`];
+    if ((rowCount ?? 0) === 0)
+        parts.push("No rows were available to capture from.");
+    if (columns.length > 0)
+        parts.push(`Available columns: ${columns.join(", ")}.`);
+    return parts.join(" ");
+}
+function availableColumns(rows) {
+    return [...new Set(rows.flatMap((row) => Object.keys(row)))];
+}
+export async function ensureEvidenceRoot(rootDir) {
+    await mkdir(join(rootDir, "evidence"), { recursive: true });
+}
+export function defaultRootDir() {
+    return join(fileURLToPath(new URL("../..", import.meta.url)));
+}
+function buildEvidenceManifest(result, paths) {
+    return {
+        version: 1,
+        scenarioId: result.scenarioId,
+        runId: result.runId,
+        status: result.status,
+        evidenceModel: {
+            flowEvidenceDir: result.evidenceDir,
+            note: "Flow evidence contains scenario reports and per-step API, DB, and Unix evidence."
+        },
+        topLevelFiles: paths,
+        steps: result.steps.map((step) => ({
+            stepId: step.stepId,
+            layer: step.layer,
+            status: step.status,
+            evidence: step.evidence
+        }))
+    };
+}