@rex0220/ksql-flownet 1.0.0

package/dist/orchestration/ensure-run.js

@@ -0,0 +1,632 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { buildBundle, readStoreZip, verifyBundle } from "../bundle/index.js";
+import { resolveBusinessKey } from "../domain/business-key.js";
+import { nodeStateKey } from "../domain/canonical-record-key.js";
+import { descendantsIncludingSelf, DescendantsError, } from "../dag/descendants.js";
+import { loadNetworkDefinition, loadNetworkDefinitionSource, } from "../domain/load-network.js";
+import { inputBaselinesEqual, parseInputBaseline, } from "../io/input-baseline.js";
+import { InputPathError, resolveNodeInputs } from "../io/io-path.js";
+import { assertProfileSnapshot, canonicalJsonSha256, profileSnapshot, sha256Hex, validateCapabilities, validateJobInspections, } from "../executor/preflight.js";
+import { RepositoryError } from "../persistence/repository.js";
+import { reconcileRun } from "./reconciliation.js";
+import { isCancelHold } from "./cancel-request.js";
+export class EnsureRunError extends Error {
+    code;
+    blockedBy;
+    constructor(code, message, blockedBy = [], options) {
+        super(message, options);
+        this.code = code;
+        this.blockedBy = blockedBy;
+        this.name = "EnsureRunError";
+    }
+}
+export async function ensureRun(input) {
+    const now = input.now ?? (() => new Date());
+    const uuid = input.uuid ?? randomUUID;
+    const loaded = loadNetworkDefinition(input.networkPath);
+    if (loaded.definition === undefined || loaded.errors.length > 0) {
+        throw new EnsureRunError("NETWORK_VALIDATION_FAILED", formatValidationErrors(loaded.errors));
+    }
+    const definition = loaded.definition;
+    const businessKey = resolveEnsureBusinessKey(input, definition.network_id, definition.business_key_policy, now);
+    // Contract 9.1: capability failure must not acquire the Network lock.
+    const capabilities = await input.executor.capabilities();
+    validateCapabilities(capabilities, [
+        ...(definition.nodes.some((node) => Object.keys(node.inputs ?? {}).length > 0)
+            ? ["importCsv"]
+            : []),
+        ...(definition.nodes.some((node) => Object.keys(node.outputs ?? {}).length > 0)
+            ? ["resultCsv"]
+            : []),
+    ]);
+    const configuredIo = await input.beforeLock?.(definition);
+    const ioRoot = configuredIo?.root ?? input.ioRoot;
+    const ioRetentionDays = configuredIo?.retentionDays ?? input.ioRetentionDays ?? 90;
+    let lock = null;
+    let invocation = null;
+    let handedOff = false;
+    try {
+        lock = await input.lockManager.acquire();
+        let run = await findRunInsideLock(input, definition.network_id, businessKey);
+        let outcome;
+        let bundleBytes;
+        if (run === null) {
+            if (input.resumeRunId !== undefined || input.rerunFrom !== undefined) {
+                throw new EnsureRunError("RUN_NOT_FOUND", input.resumeRunId === undefined
+                    ? "--rerun-from requires an existing Run selected by --resume"
+                    : `run '${input.resumeRunId}' was not found`);
+            }
+            const blockedBy = (await input.repository.listRuns(input.profile, definition.network_id))
+                .filter(({ value }) => value.business_key !== businessKey &&
+                value.resume_allowed &&
+                value.lifecycle_status !== "ARCHIVED" &&
+                value.status !== "SUCCESS")
+                .map(({ value }) => value.run_id)
+                .sort();
+            if (blockedBy.length >= definition.max_active_runs) {
+                throw new EnsureRunError("MAX_ACTIVE_RUNS", `max_active_runs=${definition.max_active_runs} is reached; blocking run_id(s): ${blockedBy.join(", ")}`, blockedBy);
+            }
+            const created = await createNewRun(input, definition, businessKey, capabilities, now, uuid, async (createdRun) => {
+                invocation = await createInvocation(input, createdRun, "NEW", now, uuid, definition.nodes.map((node) => node.id));
+            });
+            run = created.run;
+            bundleBytes = created.bundleBytes;
+            outcome = "NEW";
+        }
+        else {
+            assertRunIdentity(run.value, input.profile, definition.network_id);
+            if (run.value.status === "SUCCESS" && input.rerunFrom === undefined) {
+                await input.lockManager.release(lock, "SUCCESS", "ALREADY_SUCCESS");
+                lock = null;
+                return {
+                    outcome: "NOOP",
+                    run,
+                    invocation: null,
+                    blockedBy: [],
+                    businessKey: run.value.business_key,
+                };
+            }
+            if (input.resume !== true &&
+                input.resumeRunId === undefined &&
+                input.rerunFrom === undefined) {
+                throw new EnsureRunError("RUN_ALREADY_EXISTS", `run '${run.value.run_id}' already exists for this business key; use RERUN to continue it`, [run.value.run_id]);
+            }
+            const cancelRequest = await input.repository.getCancelRequest(run.value.run_id);
+            if (isCancelHold(cancelRequest)) {
+                throw new EnsureRunError("RUN_ON_HOLD", `run '${run.value.run_id}' is on hold by CANCEL:${run.value.run_id} (${cancelRequest.value.state}, revision ${cancelRequest.revision})`);
+            }
+            outcome = "RESUME";
+            if (input.rerunFrom === undefined &&
+                !definition.nodes.some((node) => Object.keys(node.inputs ?? {}).length > 0)) {
+                invocation = await createInvocation(input, run, outcome, now, uuid);
+            }
+            if (!(input.rerunFrom !== undefined && run.value.status === "SUCCESS")) {
+                assertRunResumable(run.value);
+            }
+            const description = await input.executor.describeProfile();
+            assertDescriptionProfile(description, input.profile);
+            assertStoredProfile(description, run.value);
+            bundleBytes = Buffer.from(await input.bundleStore.download(run.value.source_bundle_attachment));
+            verifyBundle(bundleBytes, { zipSha256: run.value.source_bundle_sha256 });
+            const snapshotDefinition = definitionFromBundle(bundleBytes, run.value);
+            assertInputRetention(run.value, snapshotDefinition, ioRetentionDays, now());
+            await ensureNodeStates(input.repository, run.value.run_id, snapshotDefinition, now().toISOString(), uuid);
+            await reconcileRun(input.repository, run.value.run_id);
+            run = await input.repository.getRun(run.value.run_id);
+            if (input.rerunFrom !== undefined) {
+                const selectedNodeIds = await prepareRerunFrom(input.repository, run, snapshotDefinition, input.rerunFrom, now, (selectedIds) => verifyExistingInputBaselines(input.repository, run.value, snapshotDefinition, new Set(selectedIds), ioRoot, input.profile));
+                invocation = await createInvocation(input, run, "RERUN_FROM", now, uuid, selectedNodeIds);
+            }
+            else if (invocation === null) {
+                const states = await input.repository.getNodeStates(run.value.run_id);
+                const resumeTargets = new Set(states
+                    .filter(({ value }) => value.idempotent &&
+                    (value.status === "FAILED" || value.status === "CANCELLED"))
+                    .map(({ value }) => value.node_id));
+                await verifyExistingInputBaselines(input.repository, run.value, snapshotDefinition, resumeTargets, ioRoot, input.profile);
+                invocation = await createInvocation(input, run, outcome, now, uuid);
+            }
+        }
+        if (invocation === null) {
+            invocation = await createInvocation(input, run, outcome, now, uuid);
+        }
+        if (outcome === "NEW") {
+            await reconcileRun(input.repository, run.value.run_id);
+            run = await input.repository.getRun(run.value.run_id);
+        }
+        const activeLock = lock;
+        const activeInvocation = invocation;
+        let closed = false;
+        handedOff = true;
+        return {
+            outcome,
+            run,
+            invocation,
+            blockedBy: [],
+            businessKey: run.value.business_key,
+            bundleBytes,
+            lock: activeLock,
+            async close(finalization) {
+                if (closed)
+                    return;
+                closed = true;
+                let finalizationError;
+                if (finalization.persistInvocation !== false) {
+                    try {
+                        await input.repository.finalizeInvocation(activeInvocation.value.invocation_id, activeInvocation.revision, {
+                            status: finalization.status,
+                            result_code: finalization.resultCode,
+                            finished_at: now().toISOString(),
+                            ...(finalization.selectedNodeIds === undefined
+                                ? {}
+                                : { selected_node_ids: finalization.selectedNodeIds }),
+                            ...(finalization.preservedNodeIds === undefined
+                                ? {}
+                                : { preserved_node_ids: finalization.preservedNodeIds }),
+                            ...(finalization.blockedNodeIds === undefined
+                                ? {}
+                                : { blocked_node_ids: finalization.blockedNodeIds }),
+                            ...(finalization.reason === undefined
+                                ? {}
+                                : {
+                                    reason: `${activeInvocation.value.reason}; ${finalization.reason}`,
+                                }),
+                        });
+                    }
+                    catch (error) {
+                        finalizationError = error;
+                    }
+                }
+                try {
+                    await input.lockManager.release(activeLock, finalization.status, finalization.resultCode);
+                }
+                catch (releaseError) {
+                    throw new AggregateError(finalizationError === undefined
+                        ? [releaseError]
+                        : [finalizationError, releaseError], "ensure-run close failed", { cause: releaseError });
+                }
+                if (finalizationError !== undefined)
+                    throw finalizationError;
+            },
+        };
+    }
+    catch (error) {
+        let invocationFinalizationError;
+        if (invocation !== null) {
+            try {
+                await input.repository.finalizeInvocation(invocation.value.invocation_id, invocation.revision, {
+                    status: "FAILED",
+                    result_code: errorCode(error),
+                    finished_at: now().toISOString(),
+                });
+            }
+            catch (finalizationError) {
+                invocationFinalizationError = finalizationError;
+            }
+        }
+        if (invocationFinalizationError !== undefined) {
+            throw new AggregateError([normalizeEnsureError(error), invocationFinalizationError], "ensure-run failed and its Invocation could not be finalized", { cause: error });
+        }
+        throw normalizeEnsureError(error);
+    }
+    finally {
+        if (lock !== null && !handedOff) {
+            await input.lockManager.release(lock, "FAILED", "ENSURE_RUN_FAILED");
+        }
+    }
+}
+async function findRunInsideLock(input, networkId, businessKey) {
+    try {
+        if (input.resumeRunId !== undefined) {
+            return await input.repository.getRun(input.resumeRunId);
+        }
+        return await input.repository.getRunByBusinessKey(input.profile, networkId, businessKey);
+    }
+    catch (error) {
+        if (error instanceof RepositoryError && error.code === "MULTIPLE_RECORDS") {
+            throw new EnsureRunError("MULTIPLE_RUNS", "multiple runs matched profile + network_id + business_key");
+        }
+        if (input.resumeRunId !== undefined &&
+            error instanceof RepositoryError &&
+            error.code === "RECORD_NOT_FOUND") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function createNewRun(input, definition, businessKey, capabilities, now, uuid, onRunCreated) {
+    const description = await input.executor.describeProfile();
+    assertDescriptionProfile(description, input.profile);
+    const networkBytes = await readFile(input.networkPath);
+    const root = dirname(input.networkPath);
+    const inspected = await Promise.all(definition.nodes.map(async (node) => {
+        const sqlPath = resolve(root, node.sql);
+        const before = await readFile(sqlPath);
+        const inspection = await input.executor.inspectJob(sqlPath);
+        const after = await readFile(sqlPath);
+        if (!before.equals(after)) {
+            throw new EnsureRunError("BUNDLE_INPUT_CHANGED", `SQL file changed while it was inspected: ${sqlPath}`);
+        }
+        return { node, sqlBytes: after, inspection };
+    }));
+    const inspectionMap = new Map(inspected.map(({ node, inspection }) => [node.id, inspection]));
+    const validated = validateJobInspections(definition.nodes, inspectionMap);
+    const validatedByNode = new Map(validated.map((item) => [item.nodeId, item]));
+    const jobs = inspected.map(({ node, sqlBytes }) => ({
+        path: `jobs/${node.id}.sql`,
+        sqlBytes,
+        inspectedNode: validatedByNode.get(node.id),
+    }));
+    const dialects = [
+        ...new Set(inspected.map(({ inspection }) => inspection.dialect)),
+    ];
+    if (dialects.length !== 1) {
+        throw new EnsureRunError("BUNDLE_DIALECT_MISMATCH", `inspected jobs do not have one dialect: ${dialects.join(", ")}`);
+    }
+    const bundle = buildBundle({ networkYamlBytes: networkBytes, jobs });
+    verifyBundle(bundle.zipBytes, {
+        zipSha256: bundle.zipSha256,
+        manifestSha256: bundle.manifestSha256,
+        manifest: bundle.manifest,
+    });
+    const uploadFileKey = await input.bundleStore.upload(bundle.zipBytes);
+    const at = now().toISOString();
+    const snapshot = persistenceProfileSnapshot(description);
+    const value = {
+        run_id: `netrun_${uuid()}`,
+        network_id: definition.network_id,
+        business_key: businessKey,
+        max_active_runs: definition.max_active_runs,
+        status: "CREATED",
+        lifecycle_status: "ACTIVE",
+        resume_allowed: true,
+        as_of: input.scheduledFor ?? null,
+        definition_schema_version: definition.schema_version,
+        definition_sha256: sha256Hex(networkBytes),
+        source_bundle_sha256: bundle.zipSha256,
+        source_bundle_attachment: uploadFileKey,
+        resolved_profile_snapshot: snapshot,
+        resolved_profile_sha256: profileSnapshot(description).canonicalJsonSha256,
+        ksql_flow_version: capabilities.ksqlFlowVersion,
+        engine_version: capabilities.engineVersion,
+        dialect: dialects[0],
+        created_at: at,
+        started_at: null,
+        finished_at: null,
+        updated_at: at,
+    };
+    const created = await input.repository.createRun(value);
+    // Re-read after attachment consumption so kintone supplies the downloadable fileKey.
+    const stored = await input.repository.getRun(created.value.run_id);
+    await onRunCreated(stored);
+    const persistedBytes = Buffer.from(await input.bundleStore.download(stored.value.source_bundle_attachment));
+    verifyBundle(persistedBytes, { zipSha256: bundle.zipSha256 });
+    await ensureNodeStates(input.repository, stored.value.run_id, definition, at, uuid);
+    return { run: stored, bundleBytes: persistedBytes };
+}
+function definitionFromBundle(bundleBytes, run) {
+    const networkBytes = readStoreZip(bundleBytes).find(({ name }) => name === "network.yaml")?.data;
+    if (networkBytes === undefined ||
+        sha256Hex(networkBytes) !== run.definition_sha256) {
+        throw new EnsureRunError("RUN_SNAPSHOT_MISMATCH", "stored network definition does not match the Run definition SHA-256");
+    }
+    const loaded = loadNetworkDefinitionSource(networkBytes.toString("utf8"));
+    if (loaded.definition === undefined || loaded.errors.length > 0) {
+        throw new EnsureRunError("RUN_SNAPSHOT_MISMATCH", `stored network definition is invalid: ${formatValidationErrors(loaded.errors)}`);
+    }
+    if (loaded.definition.network_id !== run.network_id ||
+        loaded.definition.schema_version !== run.definition_schema_version) {
+        throw new EnsureRunError("RUN_SNAPSHOT_MISMATCH", "stored network definition identity does not match the Run");
+    }
+    return loaded.definition;
+}
+async function ensureNodeStates(repository, runId, definition, at, uuid) {
+    const existing = await repository.getNodeStates(runId);
+    const nodesById = new Map(definition.nodes.map((node) => [node.id, node]));
+    for (const state of existing) {
+        const node = nodesById.get(state.value.node_id);
+        if (node === undefined ||
+            state.value.job_id !== node.job_id ||
+            state.value.idempotent !== node.idempotent ||
+            state.value.trigger_rule !== node.trigger_rule) {
+            throw new EnsureRunError("RUN_SNAPSHOT_MISMATCH", `Node State '${state.value.node_id}' does not match the stored bundle`);
+        }
+    }
+    const existingIds = new Set(existing.map(({ value }) => value.node_id));
+    for (const node of definition.nodes) {
+        if (existingIds.has(node.id))
+            continue;
+        await repository.upsertNodeState({
+            value: initialNodeState(runId, node, at, uuid),
+            expected_revision: null,
+        });
+    }
+}
+function initialNodeState(runId, node, at, uuid) {
+    return {
+        node_state_id: `nodestate_${uuid()}`,
+        node_state_key: nodeStateKey(runId, node.id),
+        run_id: runId,
+        node_id: node.id,
+        job_id: node.job_id,
+        status: "WAITING",
+        latest_attempt_no: 0,
+        active_attempt_id: null,
+        revision: 1,
+        idempotent: node.idempotent,
+        trigger_rule: "all_success",
+        blocked_by: [],
+        status_reason: null,
+        started_at: null,
+        finished_at: null,
+        updated_at: at,
+    };
+}
+async function createInvocation(input, run, mode, now, uuid, selectedNodeIds) {
+    const states = selectedNodeIds === undefined
+        ? await input.repository.getNodeStates(run.value.run_id)
+        : [];
+    const preserved = states
+        .filter(({ value }) => value.status === "SUCCESS")
+        .map(({ value }) => value.node_id)
+        .sort();
+    const blocked = states
+        .filter(({ value }) => value.status === "UNKNOWN" ||
+        ((value.status === "FAILED" || value.status === "CANCELLED") &&
+            !value.idempotent))
+        .map(({ value }) => value.node_id)
+        .sort();
+    const blockedSet = new Set(blocked);
+    const selected = selectedNodeIds === undefined
+        ? states
+            .filter(({ value }) => value.status !== "SUCCESS" && !blockedSet.has(value.node_id))
+            .map(({ value }) => value.node_id)
+            .sort()
+        : [...selectedNodeIds];
+    return input.repository.createInvocation({
+        invocation_id: input.invocationId ?? `invoke_${uuid()}`,
+        run_id: run.value.run_id,
+        mode,
+        requested_by: input.requestedBy,
+        host: input.host,
+        started_at: now().toISOString(),
+        finished_at: null,
+        status: "RUNNING",
+        result_code: "PENDING",
+        selected_node_ids: selected,
+        preserved_node_ids: preserved,
+        blocked_node_ids: blocked,
+        reason: mode === "NEW"
+            ? "new business run"
+            : mode === "RERUN_FROM"
+                ? `rerun from ${input.rerunFrom}`
+                : "resume incomplete run",
+    });
+}
+async function prepareRerunFrom(repository, run, definition, nodeId, now, beforeTransitions) {
+    let selected;
+    try {
+        selected = descendantsIncludingSelf(definition, nodeId);
+    }
+    catch (error) {
+        if (error instanceof DescendantsError) {
+            throw new EnsureRunError(error.code === "DESCENDANTS_NODE_NOT_FOUND"
+                ? "RERUN_FROM_NODE_NOT_FOUND"
+                : "RERUN_FROM_DAG_INVALID", error.message, [], { cause: error });
+        }
+        throw error;
+    }
+    const states = await repository.getNodeStates(run.value.run_id);
+    const byId = new Map(states.map((state) => [state.value.node_id, state]));
+    const selectedStates = selected.map((id) => {
+        const state = byId.get(id);
+        if (state === undefined) {
+            throw new EnsureRunError("RERUN_FROM_DAG_INVALID", `Node State '${id}' is missing for the snapshot DAG`);
+        }
+        return state;
+    });
+    // All safety checks complete before the first rerun state transition.
+    if (run.value.status === "SUCCESS") {
+        throw new EnsureRunError("RERUN_FROM_SUCCESS_RUN", `run '${run.value.run_id}' is terminal SUCCESS and cannot be reopened; create a new correction business key`);
+    }
+    const unknown = selectedStates
+        .filter(({ value }) => value.status === "UNKNOWN")
+        .map(({ value }) => value.node_id);
+    if (unknown.length > 0) {
+        throw new EnsureRunError("RERUN_FROM_UNKNOWN_STATE", `rerun target contains unresolved UNKNOWN Node State(s): ${unknown.join(", ")}`);
+    }
+    const nonIdempotent = selectedStates
+        .filter(({ value }) => !value.idempotent && value.latest_attempt_no > 0)
+        .map(({ value }) => value.node_id);
+    if (nonIdempotent.length > 0) {
+        throw new EnsureRunError("RERUN_FROM_NON_IDEMPOTENT", `rerun target contains executed idempotent=false node(s): ${nonIdempotent.join(", ")}`);
+    }
+    await beforeTransitions?.(selected);
+    const at = now().toISOString();
+    for (const state of selectedStates) {
+        await repository.upsertNodeState({
+            expected_revision: state.revision,
+            value: {
+                ...state.value,
+                status: "WAITING",
+                active_attempt_id: null,
+                blocked_by: [],
+                status_reason: null,
+                finished_at: null,
+                updated_at: at,
+            },
+        });
+    }
+    return selected;
+}
+function assertInputRetention(run, definition, retentionDays, now) {
+    if (!definition.nodes.some((node) => Object.keys(node.inputs ?? {}).length > 0))
+        return;
+    if (!Number.isSafeInteger(retentionDays) || retentionDays <= 0)
+        throw new EnsureRunError("INPUT_RETENTION_EXPIRED", "input retention period configuration is invalid; create a new Run only after correcting it");
+    const createdAt = Date.parse(run.created_at);
+    if (!Number.isFinite(createdAt))
+        throw new EnsureRunError("RUN_SNAPSHOT_MISMATCH", "stored Run creation time is invalid");
+    const expiresAt = createdAt + retentionDays * 86_400_000;
+    // kintone DATETIME values may lose seconds; allow the full final minute.
+    if (now.getTime() <= expiresAt + 59_999)
+        return;
+    throw new EnsureRunError("INPUT_RETENTION_EXPIRED", `input retention period (${retentionDays} days from Run creation) has expired; create a new Run with a correction business key`);
+}
+async function verifyExistingInputBaselines(repository, run, definition, targetNodeIds, ioRoot, profile) {
+    if (targetNodeIds.size === 0 || ioRoot === undefined)
+        return;
+    const attempts = await repository.getAttempts(run.run_id);
+    for (const node of definition.nodes) {
+        const patterns = node.inputs ?? {};
+        if (!targetNodeIds.has(node.id) || Object.keys(patterns).length === 0)
+            continue;
+        const previous = latestStoredBaseline(attempts, node.id);
+        if (previous === null)
+            continue;
+        let current;
+        try {
+            current = await resolveNodeInputs({
+                ioRoot,
+                patterns,
+                businessKey: run.business_key,
+                profile,
+            });
+        }
+        catch (error) {
+            if (error instanceof InputPathError)
+                continue;
+            throw error;
+        }
+        if (!inputBaselinesEqual(previous, current)) {
+            throw new EnsureRunError("INPUT_FILE_MUTATED", `input file changed for node '${node.id}'; restore the original file or create a new Run with a correction business key`);
+        }
+    }
+}
+function latestStoredBaseline(attempts, nodeId) {
+    try {
+        for (const attempt of attempts
+            .filter(({ value }) => value.node_id === nodeId)
+            .sort((left, right) => right.value.attempt_no - left.value.attempt_no)) {
+            const baseline = parseInputBaseline(attempt.value.error_message);
+            if (baseline !== null)
+                return baseline;
+        }
+        return null;
+    }
+    catch (error) {
+        throw new EnsureRunError("INPUT_FILE_MUTATED", `stored input baseline for node '${nodeId}' is invalid; create a new Run with a correction business key`, [], { cause: error });
+    }
+}
+function resolveEnsureBusinessKey(input, networkId, policy, now) {
+    if (input.resumeRunId !== undefined)
+        return "";
+    const manual = input.resume !== true &&
+        input.scheduledFor === undefined &&
+        input.businessKey === undefined
+        ? `${networkId}@manual-${manualTimestamp(now())}`
+        : undefined;
+    const selectedBusinessKey = input.businessKey ?? manual;
+    const resolved = resolveBusinessKey({
+        networkId,
+        policy,
+        ...(input.scheduledFor === undefined
+            ? {}
+            : { scheduledFor: input.scheduledFor }),
+        ...(selectedBusinessKey === undefined
+            ? {}
+            : { businessKey: selectedBusinessKey }),
+    });
+    if (resolved.businessKey === undefined || resolved.errors.length > 0) {
+        throw new EnsureRunError("BUSINESS_KEY_INVALID", formatValidationErrors(resolved.errors));
+    }
+    return resolved.businessKey;
+}
+function manualTimestamp(value) {
+    return value
+        .toISOString()
+        .replaceAll("-", "")
+        .replaceAll(":", "")
+        .replace(".", "");
+}
+function assertRunIdentity(run, profile, networkId) {
+    const mismatches = [];
+    if (run.network_id !== networkId)
+        mismatches.push("network_id");
+    if (run.resolved_profile_snapshot.profile !== profile)
+        mismatches.push("profile");
+    if (mismatches.length > 0) {
+        throw new EnsureRunError("RUN_ID_MISMATCH", `specified run does not match ${mismatches.join(", ")}`);
+    }
+}
+function assertRunResumable(run) {
+    if (!run.resume_allowed || run.lifecycle_status === "ARCHIVED") {
+        throw new EnsureRunError("RUN_NOT_RESUMABLE", `run '${run.run_id}' is not resumable (lifecycle_status=${run.lifecycle_status}, resume_allowed=${String(run.resume_allowed)})`);
+    }
+}
+function assertDescriptionProfile(description, profile) {
+    if (description.profile !== profile) {
+        throw new EnsureRunError("PROFILE_DESCRIPTION_INVALID", `describe-profile returned '${description.profile}', expected '${profile}'`);
+    }
+}
+function assertStoredProfile(description, run) {
+    const snapshot = run.resolved_profile_snapshot;
+    assertProfileSnapshot(description, {
+        canonicalJsonSha256: run.resolved_profile_sha256,
+        baseUrl: snapshot.base_url,
+        guestSpaceId: snapshot.guest_space_id,
+        apps: snapshot.apps,
+        timezone: snapshot.timezone,
+    });
+}
+function persistenceProfileSnapshot(description) {
+    const maxApiCalls = description.limits.maxApiCalls;
+    const maxReadRows = description.limits.maxReadRows;
+    const batchTimeoutSec = description.limits.batchTimeoutSec;
+    if (description.timezone === null ||
+        !isFiniteNumberOrNull(maxApiCalls) ||
+        !isFiniteNumberOrNull(maxReadRows) ||
+        !isFiniteNumberOrNull(batchTimeoutSec)) {
+        throw new EnsureRunError("PROFILE_DESCRIPTION_INVALID", "describe-profile is missing timezone or required limits");
+    }
+    return {
+        profile: description.profile,
+        base_url: description.baseUrl,
+        guest_space_id: description.guestSpaceId,
+        timezone: description.timezone,
+        apps: { ...description.apps },
+        limits: {
+            max_api_calls: maxApiCalls,
+            max_read_rows: maxReadRows,
+            batch_timeout_sec: batchTimeoutSec,
+        },
+    };
+}
+function isFiniteNumberOrNull(value) {
+    return (value === null || (typeof value === "number" && Number.isFinite(value)));
+}
+function formatValidationErrors(errors) {
+    return errors
+        .map((error) => `[${error.code}] ${error.path}: ${error.message}`)
+        .join("; ");
+}
+function errorCode(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return "ENSURE_RUN_FAILED";
+}
+function normalizeEnsureError(error) {
+    if (error instanceof Error)
+        return error;
+    return new EnsureRunError("ENSURE_RUN_FAILED", "ensure-run failed with a non-Error value", [], { cause: error });
+}
+export function profileDescriptionSha256(description) {
+    return canonicalJsonSha256(description);
+}
+//# sourceMappingURL=ensure-run.js.map

package/dist/orchestration/job-lock-audit.d.ts

@@ -0,0 +1,24 @@
+import type { JobLockRecoveryOperationAudit, LockRecoveryResult } from "../domain/persistence-model.js";
+import type { PersistenceRepository } from "../persistence/repository.js";
+export type JobLockAuditRepository = Pick<PersistenceRepository, "getRun" | "getNodeStates" | "appendOperationAudit">;
+export interface RecordJobUnlockInput {
+    repository: JobLockAuditRepository;
+    runId: string;
+    nodeId: string;
+    result: unknown;
+    reason: string;
+    evidenceRef: string;
+    servicePrincipal: string;
+    requestedBy: string;
+    stopConfirmedBy: string;
+    now?: () => Date;
+    uuid?: () => string;
+}
+export declare class JobLockAuditError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Records the kSQL-Flow result only. This module has no Job lock mutation dependency. */
+export declare function recordJobUnlock(input: RecordJobUnlockInput): Promise<JobLockRecoveryOperationAudit>;
+export declare function parseLockRecoveryResult(value: unknown): LockRecoveryResult;
+//# sourceMappingURL=job-lock-audit.d.ts.map