stageflow 0.1.0

package/dist/config/resolvePipelineDag.js

@@ -0,0 +1,282 @@
+const ALLOWED_STAGE_REF_KEYS = new Set(["id", "needs"]);
+function pipelineLabel(ctx) {
+    return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
+}
+function formatError(ctx, message) {
+    return `${pipelineLabel(ctx)}: ${message}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parsePipelineStageEntries(raw, ctx) {
+    if (!Array.isArray(raw)) {
+        throw new Error(formatError(ctx, "stages[] is required"));
+    }
+    if (raw.length === 0) {
+        throw new Error(formatError(ctx, "stages must be non-empty"));
+    }
+    const entries = [];
+    for (let index = 0; index < raw.length; index++) {
+        const entry = raw[index];
+        if (typeof entry === "string") {
+            if (!entry) {
+                throw new Error(formatError(ctx, `invalid stage entry at index ${index}: stage id must be a non-empty string`));
+            }
+            entries.push(entry);
+            continue;
+        }
+        if (!isPlainObject(entry)) {
+            throw new Error(formatError(ctx, `invalid stage entry at index ${index}`));
+        }
+        const keys = Object.keys(entry);
+        for (const key of keys) {
+            if (!ALLOWED_STAGE_REF_KEYS.has(key)) {
+                throw new Error(formatError(ctx, `invalid stage entry "${String(entry.id ?? index)}": unknown key "${key}"`));
+            }
+        }
+        if (typeof entry.id !== "string" || !entry.id) {
+            throw new Error(formatError(ctx, `invalid stage entry at index ${index}: id must be a non-empty string`));
+        }
+        if (entry.needs === undefined) {
+            entries.push({ id: entry.id });
+            continue;
+        }
+        if (Array.isArray(entry.needs)) {
+            if (entry.needs.length > 1) {
+                throw new Error(formatError(ctx, `stage "${entry.id}": fan-in not supported; needs must be a single stage id`));
+            }
+            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a string, not an array`));
+        }
+        if (typeof entry.needs !== "string" || !entry.needs) {
+            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
+        }
+        entries.push({ id: entry.id, needs: entry.needs });
+    }
+    return entries;
+}
+function normalizeToEdges(entries) {
+    const edges = [];
+    for (let index = 0; index < entries.length; index++) {
+        const entry = entries[index];
+        if (typeof entry === "string") {
+            edges.push({
+                id: entry,
+                needs: index > 0 ? entries[index - 1] : null,
+                stageIndex: index,
+            });
+            continue;
+        }
+        edges.push({
+            id: entry.id,
+            needs: entry.needs ?? null,
+            stageIndex: index,
+        });
+    }
+    return edges;
+}
+function detectDuplicateIds(edges, ctx) {
+    const seen = new Set();
+    for (const edge of edges) {
+        if (seen.has(edge.id)) {
+            throw new Error(formatError(ctx, `duplicate stage "${edge.id}"`));
+        }
+        seen.add(edge.id);
+    }
+}
+function validateNeedsTargets(edges, ctx) {
+    const declared = new Set(edges.map((edge) => edge.id));
+    for (const edge of edges) {
+        if (edge.needs !== null && !declared.has(edge.needs)) {
+            throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${edge.needs}"`));
+        }
+    }
+}
+function detectCycle(edges, ctx) {
+    const indegree = new Map();
+    const children = new Map();
+    for (const edge of edges) {
+        indegree.set(edge.id, 0);
+        children.set(edge.id, []);
+    }
+    for (const edge of edges) {
+        if (edge.needs === null)
+            continue;
+        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+        children.get(edge.needs)?.push(edge.id);
+    }
+    const queue = [];
+    for (const [id, degree] of indegree) {
+        if (degree === 0)
+            queue.push(id);
+    }
+    let visited = 0;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        visited++;
+        for (const child of children.get(current) ?? []) {
+            const nextDegree = (indegree.get(child) ?? 0) - 1;
+            indegree.set(child, nextDegree);
+            if (nextDegree === 0)
+                queue.push(child);
+        }
+    }
+    if (visited !== edges.length) {
+        throw new Error(formatError(ctx, "dependency cycle detected"));
+    }
+}
+function computeAncestors(edges) {
+    const needsById = new Map(edges.map((edge) => [edge.id, edge.needs]));
+    const ancestorsById = new Map();
+    function ancestorsFor(id) {
+        const cached = ancestorsById.get(id);
+        if (cached)
+            return cached;
+        const needs = needsById.get(id) ?? null;
+        if (needs === null) {
+            ancestorsById.set(id, []);
+            return [];
+        }
+        const parentAncestors = ancestorsFor(needs);
+        const ancestors = [...parentAncestors, needs];
+        ancestorsById.set(id, ancestors);
+        return ancestors;
+    }
+    for (const edge of edges) {
+        ancestorsFor(edge.id);
+    }
+    return ancestorsById;
+}
+function topologicalSort(edges) {
+    const byId = new Map(edges.map((edge) => [edge.id, edge]));
+    const indegree = new Map();
+    const children = new Map();
+    for (const edge of edges) {
+        indegree.set(edge.id, 0);
+        children.set(edge.id, []);
+    }
+    for (const edge of edges) {
+        if (edge.needs === null)
+            continue;
+        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+        children.get(edge.needs)?.push(edge.id);
+    }
+    for (const [parent, childIds] of children) {
+        childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
+    }
+    const roots = edges
+        .filter((edge) => edge.needs === null)
+        .sort((a, b) => a.stageIndex - b.stageIndex)
+        .map((edge) => edge.id);
+    const sorted = [];
+    const queue = [...roots];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const edge = byId.get(current);
+        if (edge)
+            sorted.push(edge);
+        for (const child of children.get(current) ?? []) {
+            const nextDegree = (indegree.get(child) ?? 0) - 1;
+            indegree.set(child, nextDegree);
+            if (nextDegree === 0)
+                queue.push(child);
+        }
+    }
+    return sorted;
+}
+function buildResolvedPipelineDag(edges) {
+    const ancestorsById = computeAncestors(edges);
+    const sortedEdges = topologicalSort(edges);
+    const childrenOf = {};
+    for (const edge of edges) {
+        childrenOf[edge.id] = [];
+    }
+    for (const edge of edges) {
+        if (edge.needs !== null) {
+            childrenOf[edge.needs].push(edge.id);
+        }
+    }
+    for (const id of Object.keys(childrenOf)) {
+        childrenOf[id].sort((a, b) => (edges.find((edge) => edge.id === a)?.stageIndex ?? 0) -
+            (edges.find((edge) => edge.id === b)?.stageIndex ?? 0));
+    }
+    const roots = edges
+        .filter((edge) => edge.needs === null)
+        .sort((a, b) => a.stageIndex - b.stageIndex)
+        .map((edge) => edge.id);
+    const nodes = sortedEdges.map((edge) => ({
+        id: edge.id,
+        needs: edge.needs,
+        ancestors: ancestorsById.get(edge.id) ?? [],
+        stageIndex: edge.stageIndex,
+    }));
+    return { nodes, roots, childrenOf };
+}
+export function resolvePipelineDag(rawStages, ctx) {
+    const entries = parsePipelineStageEntries(rawStages, ctx);
+    const edges = normalizeToEdges(entries);
+    detectDuplicateIds(edges, ctx);
+    validateNeedsTargets(edges, ctx);
+    detectCycle(edges, ctx);
+    const stages = edges
+        .slice()
+        .sort((a, b) => a.stageIndex - b.stageIndex)
+        .map((edge) => edge.id);
+    const dag = buildResolvedPipelineDag(edges);
+    return { stages, dag };
+}
+export function areResolvedDagsEquivalent(a, b) {
+    const nodeIdsA = new Set(a.nodes.map((node) => node.id));
+    const nodeIdsB = new Set(b.nodes.map((node) => node.id));
+    if (nodeIdsA.size !== nodeIdsB.size)
+        return false;
+    for (const id of nodeIdsA) {
+        if (!nodeIdsB.has(id))
+            return false;
+    }
+    const byIdA = new Map(a.nodes.map((node) => [node.id, node]));
+    const byIdB = new Map(b.nodes.map((node) => [node.id, node]));
+    for (const id of nodeIdsA) {
+        const nodeA = byIdA.get(id);
+        const nodeB = byIdB.get(id);
+        if (nodeA.needs !== nodeB.needs)
+            return false;
+        if (nodeA.ancestors.length !== nodeB.ancestors.length)
+            return false;
+        for (let i = 0; i < nodeA.ancestors.length; i++) {
+            if (nodeA.ancestors[i] !== nodeB.ancestors[i])
+                return false;
+        }
+    }
+    return true;
+}
+export function extractPipelineStageIds(rawStages) {
+    if (!Array.isArray(rawStages) || rawStages.length === 0) {
+        return null;
+    }
+    const stageIds = [];
+    for (const entry of rawStages) {
+        if (typeof entry === "string") {
+            if (!entry)
+                return null;
+            stageIds.push(entry);
+            continue;
+        }
+        if (!isPlainObject(entry))
+            return null;
+        const keys = Object.keys(entry);
+        for (const key of keys) {
+            if (!ALLOWED_STAGE_REF_KEYS.has(key))
+                return null;
+        }
+        if (typeof entry.id !== "string" || !entry.id)
+            return null;
+        if (entry.needs !== undefined) {
+            if (Array.isArray(entry.needs))
+                return null;
+            if (typeof entry.needs !== "string" || !entry.needs)
+                return null;
+        }
+        stageIds.push(entry.id);
+    }
+    return stageIds;
+}

package/dist/config/validateCatalog.d.ts

@@ -0,0 +1,36 @@
+import type { LoadIssue } from "./loadOutcome.js";
+export type ValidationSeverity = "error" | "warning";
+export type ValidationCategory = "pipeline" | "stage" | "catalog";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "catalog.duplicate_pipeline_id" | "catalog.orphan_stage";
+export type ValidationFinding = {
+    severity: ValidationSeverity;
+    code: ValidationFindingCode | string;
+    path: string;
+    message: string;
+    category: ValidationCategory;
+    pipelineId?: string;
+    stageId?: string;
+};
+export type ValidationScope = "full" | "pipeline";
+export type ValidateCatalogOptions = {
+    cwd?: string;
+    stagesDir?: string;
+    scope: ValidationScope;
+    pipeline?: string;
+    strict?: boolean;
+};
+export type ValidationResult = {
+    scope: ValidationScope;
+    ok: boolean;
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+    findings: ValidationFinding[];
+};
+export declare function relPath(cwd: string, absPath: string): string;
+export declare function effectiveSeverity(finding: ValidationFinding, strict: boolean): ValidationSeverity;
+export declare function buildValidationResult(scope: ValidationScope, findings: ValidationFinding[], strict: boolean): ValidationResult;
+export declare function findingsFromLoadIssues(cwd: string, absPath: string, issues: LoadIssue[]): ValidationFinding[];
+export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
+export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;

package/dist/config/validateCatalog.js

@@ -0,0 +1,322 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { loadPipelineOutcome, loadPipelineValidated } from "./loadPipeline.js";
+import { loadStageOutcome } from "./loadStage.js";
+import { readYamlObject } from "./readYamlObject.js";
+import { extractPipelineStageIds } from "./resolvePipelineDag.js";
+export function relPath(cwd, absPath) {
+    return path.relative(cwd, absPath);
+}
+const SEVERITY_RANK = {
+    error: 0,
+    warning: 1,
+};
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const pathCmp = a.path.localeCompare(b.path);
+        if (pathCmp !== 0)
+            return pathCmp;
+        const sevCmp = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+        if (sevCmp !== 0)
+            return sevCmp;
+        const codeCmp = a.code.localeCompare(b.code);
+        if (codeCmp !== 0)
+            return codeCmp;
+        return a.message.localeCompare(b.message);
+    });
+}
+export function effectiveSeverity(finding, strict) {
+    if (strict &&
+        finding.severity === "warning" &&
+        finding.code === "catalog.orphan_stage") {
+        return "error";
+    }
+    return finding.severity;
+}
+function summarizeFindings(findings, strict) {
+    let errors = 0;
+    let warnings = 0;
+    for (const finding of findings) {
+        const severity = effectiveSeverity(finding, strict);
+        if (severity === "error")
+            errors++;
+        else
+            warnings++;
+    }
+    return { errors, warnings };
+}
+export function buildValidationResult(scope, findings, strict) {
+    const sorted = sortFindings(findings);
+    const summary = summarizeFindings(sorted, strict);
+    const ok = summary.errors === 0;
+    return { scope, ok, summary, findings: sorted };
+}
+function baseFinding(fields, severity) {
+    return {
+        severity,
+        code: fields.code,
+        path: relPath(fields.cwd, fields.absPath),
+        message: fields.message,
+        category: fields.category,
+        ...(fields.pipelineId !== undefined ? { pipelineId: fields.pipelineId } : {}),
+        ...(fields.stageId !== undefined ? { stageId: fields.stageId } : {}),
+    };
+}
+function findingPipelineError(cwd, absPath, message, code, pipelineId) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "pipeline",
+        pipelineId,
+    }, "error");
+}
+function findingStageError(cwd, absPath, message, code, stageId) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message,
+        code,
+        category: "stage",
+        stageId,
+    }, "error");
+}
+export function findingsFromLoadIssues(cwd, absPath, issues) {
+    return issues.flatMap((issue) => {
+        if (issue.category === "pipeline") {
+            return [
+                findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId),
+            ];
+        }
+        if (issue.category === "stage") {
+            return [
+                findingStageError(cwd, absPath, issue.message, issue.code, issue.stageId),
+            ];
+        }
+        return [];
+    });
+}
+export function findingStageIdFilenameMismatch(cwd, absPath, fileStem, declaredId) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message: `Stage id "${declaredId}" does not match filename stem "${fileStem}"`,
+        code: "stage.id_filename_mismatch",
+        category: "stage",
+        stageId: declaredId,
+    }, "error");
+}
+function findingCatalogDuplicatePipelineId(cwd, absPath, pipelineId, conflictingPaths) {
+    const relConflicts = conflictingPaths.map((p) => relPath(cwd, p));
+    return baseFinding({
+        cwd,
+        absPath,
+        message: `Duplicate pipeline id "${pipelineId}" declared in: ${relConflicts.join(", ")}`,
+        code: "catalog.duplicate_pipeline_id",
+        category: "catalog",
+        pipelineId,
+    }, "error");
+}
+function findingCatalogOrphanStage(cwd, absPath, stageId) {
+    return baseFinding({
+        cwd,
+        absPath,
+        message: `Stage "${stageId}" is not referenced by any pipeline`,
+        code: "catalog.orphan_stage",
+        category: "catalog",
+        stageId,
+    }, "warning");
+}
+async function listYamlFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+        .map((entry) => path.join(dir, entry.name))
+        .sort((a, b) => a.localeCompare(b));
+}
+async function checkStageIdFilename(cwd, stagePath) {
+    const fileStem = path.basename(stagePath, ".yaml");
+    try {
+        const raw = await readYamlObject(stagePath);
+        if (typeof raw?.id === "string" && raw.id !== fileStem) {
+            return findingStageIdFilenameMismatch(cwd, stagePath, fileStem, raw.id);
+        }
+    }
+    catch {
+        // loadStageOutcome will report read errors
+    }
+    return null;
+}
+async function validateStageFile(cwd, stagePath) {
+    const findings = [];
+    const mismatch = await checkStageIdFilename(cwd, stagePath);
+    if (mismatch)
+        findings.push(mismatch);
+    const outcome = await loadStageOutcome(stagePath);
+    if (!outcome.ok) {
+        findings.push(...findingsFromLoadIssues(cwd, stagePath, outcome.issues));
+        return findings;
+    }
+    if (!mismatch && path.basename(stagePath, ".yaml") !== outcome.value.id) {
+        findings.push(findingStageIdFilenameMismatch(cwd, stagePath, path.basename(stagePath, ".yaml"), outcome.value.id));
+    }
+    return findings;
+}
+async function validatePipelineFile(pipelinePath, options) {
+    const { cwd, stagesDir, validateStages } = options;
+    const findings = [];
+    const referencedStageIds = new Set();
+    let pipelineId;
+    try {
+        const raw = await readYamlObject(pipelinePath);
+        if (typeof raw?.id === "string") {
+            pipelineId = raw.id;
+            if (Array.isArray(raw.stages)) {
+                const stageIds = extractPipelineStageIds(raw.stages);
+                if (stageIds) {
+                    for (const stageId of stageIds) {
+                        referencedStageIds.add(stageId);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // loadPipelineOutcome will report read errors
+    }
+    const outcome = await loadPipelineOutcome(pipelinePath, { cwd, stagesDir });
+    if (!outcome.ok) {
+        findings.push(...findingsFromLoadIssues(cwd, pipelinePath, outcome.issues));
+        if (validateStages) {
+            for (const stageId of referencedStageIds) {
+                const stagePath = path.join(stagesDir, `${stageId}.yaml`);
+                findings.push(...(await validateStageFile(cwd, stagePath)));
+            }
+        }
+        return { findings, pipelineId, referencedStageIds };
+    }
+    for (const stageId of outcome.value.pipeline.stages) {
+        referencedStageIds.add(stageId);
+        if (validateStages) {
+            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
+            findings.push(...(await validateStageFile(cwd, stagePath)));
+        }
+    }
+    return { findings, pipelineId: outcome.value.pipeline.id, referencedStageIds };
+}
+async function collectPipelineIds(pipelinesDir) {
+    const files = await listYamlFiles(pipelinesDir);
+    const idToPaths = new Map();
+    for (const filePath of files) {
+        try {
+            const raw = await readYamlObject(filePath);
+            if (typeof raw?.id !== "string")
+                continue;
+            const existing = idToPaths.get(raw.id) ?? [];
+            existing.push(filePath);
+            idToPaths.set(raw.id, existing);
+        }
+        catch {
+            // unreadable files handled in pipeline validation loop
+        }
+    }
+    return idToPaths;
+}
+function findingsForDuplicatePipelineIds(cwd, idToPaths) {
+    const findings = [];
+    for (const [pipelineId, paths] of idToPaths) {
+        if (paths.length <= 1)
+            continue;
+        for (const filePath of paths) {
+            findings.push(findingCatalogDuplicatePipelineId(cwd, filePath, pipelineId, paths));
+        }
+    }
+    return findings;
+}
+async function collectReferencedStageIds(pipelinesDir) {
+    const files = await listYamlFiles(pipelinesDir);
+    const referenced = new Set();
+    for (const filePath of files) {
+        try {
+            const raw = await readYamlObject(filePath);
+            if (typeof raw?.id !== "string" || !Array.isArray(raw.stages))
+                continue;
+            const stageIds = extractPipelineStageIds(raw.stages);
+            if (!stageIds)
+                continue;
+            for (const stageId of stageIds) {
+                referenced.add(stageId);
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    return referenced;
+}
+async function findingsForOrphanStages(cwd, stagesDir, referencedStageIds) {
+    const findings = [];
+    const stageFiles = await listYamlFiles(stagesDir);
+    for (const stagePath of stageFiles) {
+        const stageId = path.basename(stagePath, ".yaml");
+        if (referencedStageIds.has(stageId))
+            continue;
+        findings.push(findingCatalogOrphanStage(cwd, stagePath, stageId));
+        findings.push(...(await validateStageFile(cwd, stagePath)));
+    }
+    return findings;
+}
+export async function validateCatalog(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const stagesDir = options.stagesDir ?? path.join(cwd, "stages");
+    const strict = options.strict ?? false;
+    const pipelinesDir = path.join(cwd, "pipelines");
+    if (options.scope === "pipeline" && !options.pipeline) {
+        throw new Error("validateCatalog: pipeline is required when scope is \"pipeline\"");
+    }
+    const allFindings = [];
+    if (options.scope === "pipeline") {
+        const result = await loadPipelineValidated(options.pipeline, {
+            cwd,
+            stagesDir,
+            validateStages: true,
+        });
+        if (!result.ok) {
+            allFindings.push(...result.findings);
+        }
+    }
+    else {
+        const referencedStageIds = await collectReferencedStageIds(pipelinesDir);
+        const pipelineFiles = await listYamlFiles(pipelinesDir);
+        for (const pipelinePath of pipelineFiles) {
+            const result = await validatePipelineFile(pipelinePath, {
+                cwd,
+                stagesDir,
+                validateStages: false,
+            });
+            allFindings.push(...result.findings);
+            for (const stageId of result.referencedStageIds) {
+                referencedStageIds.add(stageId);
+            }
+        }
+        const validatedStages = new Set();
+        for (const stageId of referencedStageIds) {
+            if (validatedStages.has(stageId))
+                continue;
+            validatedStages.add(stageId);
+            const stagePath = path.join(stagesDir, `${stageId}.yaml`);
+            allFindings.push(...(await validateStageFile(cwd, stagePath)));
+        }
+        const idToPaths = await collectPipelineIds(pipelinesDir);
+        allFindings.push(...findingsForDuplicatePipelineIds(cwd, idToPaths));
+        allFindings.push(...(await findingsForOrphanStages(cwd, stagesDir, referencedStageIds)));
+    }
+    return buildValidationResult(options.scope, allFindings, strict);
+}

package/dist/envelope/check.d.ts

@@ -0,0 +1,3 @@
+import { type StageEnvelope } from "../types/envelope.js";
+export declare function assertRequiredEnvelope(value: unknown): StageEnvelope;
+export declare function isAdvancingEnvelope(envelope: StageEnvelope): boolean;

package/dist/envelope/check.js

@@ -0,0 +1,52 @@
+import { EnvelopeError, } from "../types/envelope.js";
+export function assertRequiredEnvelope(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new EnvelopeError("envelope must be an object");
+    }
+    const record = value;
+    const status = record.status;
+    if (status !== "success" && status !== "failure") {
+        throw new EnvelopeError('status must be "success" or "failure"');
+    }
+    if (typeof record.summary !== "string" || record.summary.trim() === "") {
+        throw new EnvelopeError("summary must be a non-empty string");
+    }
+    if (!("artifacts" in record)) {
+        throw new EnvelopeError("artifacts field is required");
+    }
+    if (!Array.isArray(record.artifacts)) {
+        throw new EnvelopeError("artifacts must be an array");
+    }
+    if (!record.artifacts.every((item) => typeof item === "string")) {
+        throw new EnvelopeError("artifacts must be an array of strings");
+    }
+    const envelope = {
+        status,
+        summary: record.summary,
+        artifacts: record.artifacts,
+    };
+    if (record.payload !== undefined) {
+        if (record.payload === null ||
+            typeof record.payload !== "object" ||
+            Array.isArray(record.payload)) {
+            throw new EnvelopeError("payload must be an object when present");
+        }
+        envelope.payload = record.payload;
+    }
+    if (record.stage_id !== undefined) {
+        if (typeof record.stage_id !== "string") {
+            throw new EnvelopeError("stage_id must be a string when present");
+        }
+        envelope.stage_id = record.stage_id;
+    }
+    if (record.notes !== undefined) {
+        if (typeof record.notes !== "string") {
+            throw new EnvelopeError("notes must be a string when present");
+        }
+        envelope.notes = record.notes;
+    }
+    return envelope;
+}
+export function isAdvancingEnvelope(envelope) {
+    return envelope.status === "success";
+}