@rex0220/ksql-flownet 1.0.0

package/dist/cli/run-network-command.js

@@ -0,0 +1,418 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { hostname } from "node:os";
+import { resolve } from "node:path";
+import { downloadBundle, readStoreZip, uploadBundle } from "../bundle/index.js";
+import { loadNetworkDefinition, loadNetworkDefinitionSource, } from "../domain/load-network.js";
+import { AttemptExecutor } from "../executor/attempt-executor.js";
+import { KintoneJobLogReader } from "../executor/job-log-reader.js";
+import { KsqlFlowCli } from "../executor/ksql-flow-cli.js";
+import { RunSubprocess } from "../executor/run-subprocess.js";
+import { loadIoConfig } from "../io/io-config.js";
+import { ensureRun, EnsureRunError, } from "../orchestration/ensure-run.js";
+import { runSequentialScheduler, } from "../orchestration/sequential-scheduler.js";
+import { KintonePersistenceRepository } from "../persistence/kintone/repository.js";
+import { LeaseMonitor, NetworkLockManager, } from "../persistence/network-lock.js";
+export async function runRunNetworkCommand(args, dependencies) {
+    const parsed = parseRunNetworkArguments(args);
+    let created;
+    if (parsed.errors.length > 0 || parsed.networkPath === undefined) {
+        if (parsed.json) {
+            writeJsonResult({
+                outcome: "REJECTED",
+                run_id: parsed.resumeRunId ?? null,
+                invocation_id: null,
+                aggregate_status: null,
+                invocation_result_code: "INVALID_ARGUMENTS",
+                retry_brake_node_ids: [],
+                blocked_run_ids: [],
+            });
+        }
+        else {
+            process.stderr.write(`Invalid run-network arguments:\n${parsed.errors.map((error) => `- ${error}`).join("\n")}\n`);
+        }
+        return 1;
+    }
+    try {
+        const runtime = dependencies ?? productionDependencies(parsed);
+        const result = await runtime.invoke({
+            networkPath: parsed.networkPath,
+            profile: runtime.profile,
+            requestedBy: runtime.requestedBy,
+            host: runtime.host,
+            resume: parsed.resume,
+            ...(parsed.scheduledFor === undefined
+                ? {}
+                : { scheduledFor: parsed.scheduledFor }),
+            ...(parsed.businessKey === undefined
+                ? {}
+                : { businessKey: parsed.businessKey }),
+            ...(parsed.resumeRunId === undefined
+                ? {}
+                : { resumeRunId: parsed.resumeRunId }),
+            ...(parsed.rerunFrom === undefined
+                ? {}
+                : { rerunFrom: parsed.rerunFrom }),
+        });
+        if (result.outcome === "NOOP") {
+            if (parsed.json) {
+                writeJsonResult({
+                    outcome: "NOOP",
+                    run_id: result.run.value.run_id,
+                    invocation_id: null,
+                    aggregate_status: "SUCCESS",
+                    invocation_result_code: "NOOP_ALREADY_SUCCESS",
+                    retry_brake_node_ids: [],
+                    blocked_run_ids: [],
+                });
+            }
+            else {
+                process.stdout.write(`NO-OP: Run ${result.run.value.run_id} is already SUCCESS; nothing was executed.\n`);
+            }
+            return 0;
+        }
+        created = {
+            outcome: result.outcome,
+            runId: result.run.value.run_id,
+            invocationId: result.invocation.value.invocation_id,
+        };
+        const summary = await runtime.schedule(result);
+        if (parsed.json) {
+            writeJsonResult({
+                outcome: result.outcome,
+                run_id: result.run.value.run_id,
+                invocation_id: result.invocation.value.invocation_id,
+                aggregate_status: summary.aggregateStatus,
+                invocation_result_code: summary.invocationResultCode,
+                retry_brake_node_ids: summary.retryBrakeNodeIds,
+                blocked_run_ids: [],
+            });
+        }
+        else {
+            process.stdout.write(`${result.outcome}: Run ${result.run.value.run_id} finished with aggregate ${summary.aggregateStatus} (${summary.invocationResultCode}).\n`);
+        }
+        return summary.aggregateStatus === "SUCCESS" ? 0 : 1;
+    }
+    catch (error) {
+        const code = errorCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        if (parsed.json) {
+            writeJsonResult({
+                outcome: created?.outcome ?? "REJECTED",
+                run_id: created?.runId ?? parsed.resumeRunId ?? null,
+                invocation_id: created?.invocationId ?? null,
+                aggregate_status: null,
+                invocation_result_code: code,
+                retry_brake_node_ids: [],
+                blocked_run_ids: error instanceof EnsureRunError ? error.blockedBy : [],
+            });
+        }
+        else {
+            process.stderr.write(`Error [${code}]: ${message}\n`);
+        }
+        if (!parsed.json &&
+            error instanceof EnsureRunError &&
+            error.blockedBy.length > 0) {
+            process.stderr.write(`Blocking run_id(s): ${error.blockedBy.join(", ")}\n`);
+        }
+        return 1;
+    }
+}
+function parseRunNetworkArguments(args) {
+    let networkPath;
+    let scheduledFor;
+    let businessKey;
+    let resumeRunId;
+    let rerunFrom;
+    let ksqlFlowBin;
+    let ksqlFlowConfig;
+    let ksqlFlowWorkdir;
+    let resume = false;
+    let json = false;
+    const errors = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--json") {
+            if (json)
+                errors.push("--json was specified more than once");
+            json = true;
+            continue;
+        }
+        if (argument === "--resume") {
+            if (resume)
+                errors.push("--resume was specified more than once");
+            resume = true;
+            continue;
+        }
+        if (argument === "--scheduled-for" ||
+            argument === "--business-key" ||
+            argument === "--resume-run" ||
+            argument === "--rerun-from" ||
+            argument === "--ksql-flow-bin" ||
+            argument === "--ksql-flow-config" ||
+            argument === "--ksql-flow-workdir") {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--")) {
+                errors.push(`${argument} requires a value`);
+                continue;
+            }
+            if (argument === "--scheduled-for") {
+                if (scheduledFor !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                scheduledFor = value;
+            }
+            else if (argument === "--business-key") {
+                if (businessKey !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                businessKey = value;
+            }
+            else if (argument === "--resume-run") {
+                if (resumeRunId !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                resumeRunId = value;
+            }
+            else if (argument === "--rerun-from") {
+                if (rerunFrom !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                rerunFrom = value;
+            }
+            else if (argument === "--ksql-flow-bin") {
+                if (ksqlFlowBin !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                ksqlFlowBin = value;
+            }
+            else if (argument === "--ksql-flow-config") {
+                if (ksqlFlowConfig !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                ksqlFlowConfig = value;
+            }
+            else {
+                if (ksqlFlowWorkdir !== undefined)
+                    errors.push(`${argument} was specified more than once`);
+                ksqlFlowWorkdir = value;
+            }
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("-"))
+            errors.push(`unknown option '${argument}'`);
+        else if (networkPath === undefined)
+            networkPath = argument;
+        else
+            errors.push(`unexpected argument '${argument}'`);
+    }
+    if (networkPath === undefined)
+        errors.push("run-network requires one <network> path");
+    if (resumeRunId !== undefined &&
+        (scheduledFor !== undefined || businessKey !== undefined || resume)) {
+        errors.push("--resume-run must not be combined with --resume, --scheduled-for, or --business-key");
+    }
+    if (rerunFrom !== undefined && resumeRunId === undefined && !resume) {
+        errors.push("--rerun-from requires --resume-run or --resume");
+    }
+    return {
+        resume,
+        json,
+        errors,
+        ...(networkPath === undefined ? {} : { networkPath }),
+        ...(scheduledFor === undefined ? {} : { scheduledFor }),
+        ...(businessKey === undefined ? {} : { businessKey }),
+        ...(resumeRunId === undefined ? {} : { resumeRunId }),
+        ...(rerunFrom === undefined ? {} : { rerunFrom }),
+        ...(ksqlFlowBin === undefined ? {} : { ksqlFlowBin }),
+        ...(ksqlFlowConfig === undefined ? {} : { ksqlFlowConfig }),
+        ...(ksqlFlowWorkdir === undefined ? {} : { ksqlFlowWorkdir }),
+    };
+}
+function writeJsonResult(result) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+function productionDependencies(parsed) {
+    const profile = requiredEnvironment("KSQL_FLOWNET_PROFILE");
+    const baseUrl = requiredEnvironment("KSQL_FLOWNET_BASE_URL").replace(/\/$/u, "");
+    const stateAppId = positiveIntegerEnvironment("KSQL_FLOWNET_STATE_APP_ID");
+    const auditAppId = positiveIntegerEnvironment("KSQL_FLOWNET_AUDIT_APP_ID");
+    const stateApiToken = requiredEnvironment("KSQL_FLOWNET_STATE_API_TOKEN");
+    const auditApiToken = requiredEnvironment("KSQL_FLOWNET_AUDIT_API_TOKEN");
+    const command = parsed.ksqlFlowBin ?? requiredEnvironment("KSQL_FLOW_BIN");
+    const binArgs = ksqlFlowBinArgsEnvironment();
+    const configPath = resolve(parsed.ksqlFlowConfig ?? requiredEnvironment("KSQL_FLOW_CONFIG"));
+    const executionDirectory = resolve(parsed.ksqlFlowWorkdir ?? requiredEnvironment("KSQL_FLOW_WORKDIR"));
+    const jobLogAppId = positiveIntegerEnvironment("KSQL_FLOW_LOG_APP_ID");
+    const jobLogApiToken = requiredEnvironment("KSQL_FLOW_LOG_API_TOKEN");
+    const gracePeriodMs = optionalNonNegativeIntegerEnvironment("KSQL_FLOW_GRACE_PERIOD_MS", 30_000);
+    mkdirSync(executionDirectory, { recursive: true });
+    const requestedBy = process.env.KSQL_FLOWNET_REQUESTED_BY ?? process.env.USERNAME ?? "unknown";
+    const host = process.env.KSQL_FLOWNET_HOST ?? hostname();
+    const ownerInstanceId = resolveOwnerInstanceId(host);
+    let resources;
+    return {
+        profile,
+        requestedBy,
+        host,
+        async invoke(input) {
+            const invocationId = `invoke_${randomUUID()}`;
+            const loaded = loadNetworkDefinition(input.networkPath);
+            if (loaded.definition === undefined || loaded.errors.length > 0) {
+                throw new Error("network definition is invalid");
+            }
+            let ioConfig;
+            const repository = new KintonePersistenceRepository({
+                baseUrl,
+                stateAppId,
+                stateApiToken,
+                auditAppId,
+                auditApiToken,
+            });
+            const lockManager = new NetworkLockManager({
+                baseUrl,
+                appId: stateAppId,
+                apiToken: stateApiToken,
+                profile,
+                networkId: loaded.definition.network_id,
+                ownerInvocationId: invocationId,
+                ownerInstanceId,
+                leaseDurationSec: loaded.definition.network_lock.lease_duration_sec,
+            });
+            const executor = new KsqlFlowCli({
+                command,
+                binArgs,
+                profile,
+                configPath,
+            });
+            const endpoint = `${baseUrl}/k/v1/file.json`;
+            const headers = { "X-Cybozu-API-Token": stateApiToken };
+            const ensured = await ensureRun({
+                ...input,
+                invocationId,
+                repository,
+                lockManager,
+                executor,
+                beforeLock(definition) {
+                    if (definition.nodes.some((node) => Object.keys(node.inputs ?? {}).length > 0 ||
+                        Object.keys(node.outputs ?? {}).length > 0)) {
+                        ioConfig = loadIoConfig();
+                        return ioConfig;
+                    }
+                    return undefined;
+                },
+                bundleStore: {
+                    upload: (zipBytes) => uploadBundle({ endpoint, zipBytes, fetch, headers }),
+                    download: (fileKey) => downloadBundle({ endpoint, fileKey, fetch, headers }),
+                },
+            });
+            resources = {
+                repository,
+                lockManager,
+                configPath,
+                ...(ioConfig === undefined ? {} : { ioRoot: ioConfig.root }),
+            };
+            return ensured;
+        },
+        async schedule(result) {
+            if (result.outcome === "NOOP")
+                throw new Error("NO-OP run cannot be scheduled");
+            if (resources === undefined)
+                throw new Error("scheduler resources are missing");
+            const networkBytes = readStoreZip(result.bundleBytes).find(({ name }) => name === "network.yaml")?.data;
+            if (networkBytes === undefined)
+                throw new Error("bundle has no network.yaml");
+            const loaded = loadNetworkDefinitionSource(networkBytes.toString("utf8"));
+            if (loaded.definition === undefined || loaded.errors.length > 0)
+                throw new Error("stored network definition is invalid");
+            const monitor = new LeaseMonitor(resources.lockManager, result.lock, {
+                leaseDurationSec: loaded.definition.network_lock.lease_duration_sec,
+                heartbeatIntervalSec: loaded.definition.network_lock.heartbeat_interval_sec,
+            });
+            const runner = new RunSubprocess({
+                command,
+                binArgs,
+                executionDirectory,
+                timeoutMs: result.run.value.resolved_profile_snapshot.limits
+                    .batch_timeout_sec === null
+                    ? null
+                    : result.run.value.resolved_profile_snapshot.limits
+                        .batch_timeout_sec * 1000,
+                gracePeriodMs,
+            });
+            const jobLogReader = new KintoneJobLogReader({
+                baseUrl,
+                appId: jobLogAppId,
+                apiToken: jobLogApiToken,
+            });
+            return runSequentialScheduler({
+                run: result.run,
+                invocation: result.invocation,
+                bundleBytes: result.bundleBytes,
+                repository: resources.repository,
+                jobLogReader,
+                attemptExecutor: new AttemptExecutor({
+                    repository: resources.repository,
+                    runner,
+                    jobLogReader,
+                }),
+                leaseMonitor: monitor,
+                profile,
+                configPath: resources.configPath,
+                executionRoot: executionDirectory,
+                ...(resources.ioRoot === undefined ? {} : { ioRoot: resources.ioRoot }),
+                close: (finalization) => result.close(finalization),
+            });
+        },
+    };
+}
+export function resolveOwnerInstanceId(host, configured = process.env.KSQL_FLOWNET_OWNER_INSTANCE_ID, pid = process.pid) {
+    return configured ?? `local-pid://${host}/${pid}`;
+}
+export function ksqlFlowBinArgsEnvironment(environment = process.env) {
+    const raw = environment.KSQL_FLOW_BIN_ARGS?.trim();
+    if (!raw)
+        return [];
+    if (!raw.startsWith("["))
+        return raw.split(/\s+/u);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error("KSQL_FLOW_BIN_ARGS must be a valid JSON string array", {
+            cause: error,
+        });
+    }
+    if (!Array.isArray(parsed) ||
+        !parsed.every((value) => typeof value === "string")) {
+        throw new Error("KSQL_FLOW_BIN_ARGS must be a JSON string array");
+    }
+    return parsed;
+}
+function requiredEnvironment(name) {
+    const value = process.env[name];
+    if (value === undefined || value.trim() === "")
+        throw new Error(`${name} is required`);
+    return value;
+}
+function positiveIntegerEnvironment(name) {
+    const value = Number(requiredEnvironment(name));
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+}
+function optionalNonNegativeIntegerEnvironment(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${name} must be a non-negative integer`);
+    return value;
+}
+function errorCode(error) {
+    if (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string") {
+        return error.code;
+    }
+    return "RUN_NETWORK_FAILED";
+}
+//# sourceMappingURL=run-network-command.js.map

package/dist/cli/status-command.d.ts

@@ -0,0 +1,5 @@
+import { type StatusDependencies, type StatusOutput } from "../orchestration/status.js";
+export type StatusCommandDependencies = StatusDependencies;
+export declare function runStatusCommand(args: readonly string[], dependencies?: StatusCommandDependencies): Promise<number>;
+export declare function renderStatusText(output: StatusOutput): string;
+//# sourceMappingURL=status-command.d.ts.map

package/dist/cli/status-command.js

@@ -0,0 +1,137 @@
+import { inspectStatus, } from "../orchestration/status.js";
+import { KintoneNetworkLockStatusReader } from "../persistence/network-lock-reader.js";
+import { repositoryFromEnvironment, requiredEnvironment, } from "./resolve-node-command.js";
+export async function runStatusCommand(args, dependencies) {
+    const parsed = parseStatusArguments(args);
+    if (parsed.errors.length > 0) {
+        process.stderr.write(`Invalid status arguments:\n${parsed.errors.map((error) => `- ${error}`).join("\n")}\n`);
+        return 1;
+    }
+    try {
+        const result = await inspectStatus({
+            networkId: parsed.networkId,
+            profile: parsed.profile,
+            ...(parsed.runId === undefined ? {} : { runId: parsed.runId }),
+            ...(parsed.businessKey === undefined
+                ? {}
+                : { businessKey: parsed.businessKey }),
+        }, dependencies ?? productionDependencies());
+        process.stdout.write(parsed.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : renderStatusText(result));
+        return 0;
+    }
+    catch (error) {
+        const code = typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            typeof error.code === "string"
+            ? error.code
+            : "STATUS_FAILED";
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Error [${code}]: ${message}\n`);
+        return 1;
+    }
+}
+function parseStatusArguments(args) {
+    const errors = [];
+    const positional = [];
+    const values = new Map();
+    let json = false;
+    const valueOptions = new Set(["--profile", "--run-id", "--business-key"]);
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--json") {
+            if (json)
+                errors.push("--json was specified more than once");
+            json = true;
+            continue;
+        }
+        if (!argument.startsWith("--")) {
+            positional.push(argument);
+            continue;
+        }
+        if (!valueOptions.has(argument)) {
+            errors.push(`unknown option '${argument}'`);
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            errors.push(`${argument} requires a value`);
+            continue;
+        }
+        if (values.has(argument)) {
+            errors.push(`${argument} was specified more than once`);
+        }
+        values.set(argument, value);
+        index += 1;
+    }
+    if (positional.length === 0)
+        errors.push("<network_id> is required");
+    for (const argument of positional.slice(1)) {
+        errors.push(`unexpected argument '${argument}'`);
+    }
+    if (!values.has("--profile"))
+        errors.push("--profile is required");
+    if (values.has("--run-id") && values.has("--business-key")) {
+        errors.push("--run-id and --business-key are mutually exclusive");
+    }
+    return {
+        json,
+        errors,
+        ...(positional[0] === undefined ? {} : { networkId: positional[0] }),
+        ...(values.has("--profile") ? { profile: values.get("--profile") } : {}),
+        ...(values.has("--run-id") ? { runId: values.get("--run-id") } : {}),
+        ...(values.has("--business-key")
+            ? { businessKey: values.get("--business-key") }
+            : {}),
+    };
+}
+export function renderStatusText(output) {
+    const lines = [`Network: ${output.network_id}`, `Profile: ${output.profile}`];
+    if (output.lock === null) {
+        lines.push("Lock: none");
+    }
+    else {
+        lines.push("Lock:");
+        for (const [key, value] of Object.entries(output.lock)) {
+            lines.push(`  ${key}: ${String(value)}`);
+        }
+    }
+    lines.push(`Runs: ${output.runs.length}`);
+    for (const run of output.runs) {
+        lines.push(`- run_id: ${run.run_id}`);
+        for (const [key, value] of Object.entries(run)) {
+            if (key === "run_id")
+                continue;
+            if (typeof value === "object" && value !== null) {
+                lines.push(`  ${key}: ${JSON.stringify(value)}`);
+            }
+            else {
+                lines.push(`  ${key}: ${String(value)}`);
+            }
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function productionDependencies() {
+    const baseUrl = requiredEnvironment("KSQL_FLOWNET_BASE_URL").replace(/\/$/u, "");
+    const stateAppId = positiveIntegerEnvironment("KSQL_FLOWNET_STATE_APP_ID");
+    const stateApiToken = requiredEnvironment("KSQL_FLOWNET_STATE_API_TOKEN");
+    return {
+        repository: repositoryFromEnvironment(),
+        lockReader: new KintoneNetworkLockStatusReader({
+            baseUrl,
+            stateAppId,
+            stateApiToken,
+        }),
+    };
+}
+function positiveIntegerEnvironment(name) {
+    const value = Number(requiredEnvironment(name));
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
+//# sourceMappingURL=status-command.js.map

package/dist/cli/validate-command.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationError } from "../domain/network-definition.js";
+import { validateNetworkPath, validateSqlFiles } from "../domain/validate-network-path.js";
+export { validateNetworkPath, validateSqlFiles };
+export declare function runValidateCommand(networkPath: string): number;
+export declare function writeValidationErrors(errors: readonly ValidationError[]): void;
+//# sourceMappingURL=validate-command.d.ts.map

package/dist/cli/validate-command.js

@@ -0,0 +1,17 @@
+import { validateNetworkPath, validateSqlFiles, } from "../domain/validate-network-path.js";
+export { validateNetworkPath, validateSqlFiles };
+export function runValidateCommand(networkPath) {
+    const validated = validateNetworkPath(networkPath);
+    if (validated.errors.length > 0) {
+        writeValidationErrors(validated.errors);
+        return 1;
+    }
+    process.stdout.write(`Valid network definition: ${networkPath}\n`);
+    return 0;
+}
+export function writeValidationErrors(errors) {
+    process.stderr.write(`Network validation failed with ${errors.length} error(s):\n${errors
+        .map((error) => `- [${error.code}] ${error.path}: ${error.message}`)
+        .join("\n")}\n`);
+}
+//# sourceMappingURL=validate-command.js.map

package/dist/dag/descendants.d.ts

@@ -0,0 +1,9 @@
+import type { NetworkDefinition } from "../domain/network-definition.js";
+export type DescendantsErrorCode = "DESCENDANTS_NODE_NOT_FOUND" | "DESCENDANTS_DAG_INVALID";
+export declare class DescendantsError extends Error {
+    readonly code: DescendantsErrorCode;
+    constructor(code: DescendantsErrorCode, message: string);
+}
+/** Returns the selected node and all of its transitive descendants in definition order. */
+export declare function descendantsIncludingSelf(definition: NetworkDefinition, nodeId: string): readonly string[];
+//# sourceMappingURL=descendants.d.ts.map

package/dist/dag/descendants.js

@@ -0,0 +1,67 @@
+export class DescendantsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DescendantsError";
+    }
+}
+/** Returns the selected node and all of its transitive descendants in definition order. */
+export function descendantsIncludingSelf(definition, nodeId) {
+    const nodesById = new Map();
+    for (const node of definition.nodes) {
+        if (nodesById.has(node.id)) {
+            throw new DescendantsError("DESCENDANTS_DAG_INVALID", `snapshot DAG has duplicate node id '${node.id}'`);
+        }
+        nodesById.set(node.id, node);
+    }
+    if (!nodesById.has(nodeId)) {
+        throw new DescendantsError("DESCENDANTS_NODE_NOT_FOUND", `node '${nodeId}' does not exist in the snapshot DAG`);
+    }
+    const dependents = new Map(definition.nodes.map((node) => [node.id, []]));
+    const indegree = new Map(definition.nodes.map((node) => [node.id, node.depends_on.length]));
+    for (const node of definition.nodes) {
+        const dependencies = new Set();
+        for (const dependency of node.depends_on) {
+            if (dependency === node.id ||
+                dependencies.has(dependency) ||
+                !nodesById.has(dependency)) {
+                throw new DescendantsError("DESCENDANTS_DAG_INVALID", `snapshot DAG has an invalid dependency '${dependency}' for node '${node.id}'`);
+            }
+            dependencies.add(dependency);
+            dependents.get(dependency).push(node.id);
+        }
+    }
+    const ready = definition.nodes
+        .filter((node) => indegree.get(node.id) === 0)
+        .map((node) => node.id);
+    let visited = 0;
+    while (ready.length > 0) {
+        const current = ready.shift();
+        visited += 1;
+        for (const dependent of dependents.get(current)) {
+            const remaining = indegree.get(dependent) - 1;
+            indegree.set(dependent, remaining);
+            if (remaining === 0)
+                ready.push(dependent);
+        }
+    }
+    if (visited !== definition.nodes.length) {
+        throw new DescendantsError("DESCENDANTS_DAG_INVALID", "snapshot DAG contains a cycle");
+    }
+    const selected = new Set([nodeId]);
+    const queue = [nodeId];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        for (const dependent of dependents.get(current)) {
+            if (selected.has(dependent))
+                continue;
+            selected.add(dependent);
+            queue.push(dependent);
+        }
+    }
+    return definition.nodes
+        .map((node) => node.id)
+        .filter((id) => selected.has(id));
+}
+//# sourceMappingURL=descendants.js.map

package/dist/dag/topological-sort.d.ts

@@ -0,0 +1,7 @@
+import type { NetworkNodeDefinition } from "../domain/network-definition.js";
+export interface TopologicalSortResult {
+    readonly order: readonly string[];
+    readonly cyclicNodeIds: readonly string[];
+}
+export declare function stableTopologicalSort(nodes: readonly NetworkNodeDefinition[]): TopologicalSortResult;
+//# sourceMappingURL=topological-sort.d.ts.map