@rex0220/ksql-flownet 1.0.0

package/dist/executor/attempt-executor.js

@@ -0,0 +1,236 @@
+import { KintoneApiError, KintoneTransportError, } from "../persistence/kintone/client.js";
+import { decideMissingResult, } from "./job-log-reader.js";
+import { NO_EXECUTION_RESULT, readAndClassifyResult, } from "./result-classifier.js";
+import { serializeIoAuditSummary, serializeInputAuditSummary, serializeInputBaseline, serializeOutputAuditSummary, } from "../io/input-baseline.js";
+export class AttemptResultPersistenceDeferredError extends Error {
+    classification;
+    process;
+    code = "NETWORK_LEASE_INTERRUPTED";
+    constructor(classification, process) {
+        super("subprocess completed but the Network lease does not permit result persistence");
+        this.classification = classification;
+        this.process = process;
+        this.name = "AttemptResultPersistenceDeferredError";
+    }
+}
+/** FN-10 entry point for one already-created RUNNING attempt and node state. */
+export class AttemptExecutor {
+    options;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    async execute(input) {
+        assertPrepared(input);
+        const startedAttempt = await this.options.repository.setAttemptExecutionStarted(input.attempt.value.node_attempt_id, input.attempt.revision, { execution_started_at: input.executionStartedAt });
+        const process = await this.options.runner.run(input);
+        let classification = await readAndClassifyResult(process.resultJsonPath, {
+            correlationId: input.correlationId,
+            attemptId: input.attemptId,
+            processExitCode: process.exitCode,
+        }, this.options.resultFileReader);
+        if (classification.kind === "VALID_RESULT" &&
+            (input.imports?.length ?? 0) > 0) {
+            const receipts = classification.result?.input_files;
+            const actual = [...(receipts ?? [])]
+                .sort((left, right) => left.name.localeCompare(right.name))
+                .map(({ name, sha256, bytes }) => ({ name, sha256, bytes }));
+            const expectedWithBytes = [...(input.imports ?? [])]
+                .sort((left, right) => left.name.localeCompare(right.name))
+                .map(({ name, sha256, bytes }) => ({ name, sha256, bytes }));
+            if (receipts === undefined ||
+                JSON.stringify(actual) !== JSON.stringify(expectedWithBytes)) {
+                classification = {
+                    kind: "INVALID_RESULT",
+                    attemptOutcome: "UNKNOWN",
+                    resultCode: null,
+                    details: ["input_files does not match the preflight input baseline"],
+                    result: null,
+                    invocationResultCode: "INVALID_EXECUTION_RESULT",
+                };
+            }
+        }
+        if (classification.kind === "VALID_RESULT" &&
+            (input.exports?.length ?? 0) > 0) {
+            const receipts = classification.result?.output_files;
+            const expectedNames = [...(input.exports ?? [])]
+                .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0)
+                .map(({ name }) => name);
+            const actualNames = (receipts ?? []).map(({ name }) => name);
+            let previousIndex = -1;
+            const matchesConfiguredOutputs = actualNames.every((name) => {
+                const index = expectedNames.indexOf(name);
+                if (index < 0 || index <= previousIndex)
+                    return false;
+                previousIndex = index;
+                return true;
+            });
+            if (receipts === undefined || !matchesConfiguredOutputs) {
+                classification = {
+                    kind: "INVALID_RESULT",
+                    attemptOutcome: "UNKNOWN",
+                    resultCode: null,
+                    details: ["output_files does not match the configured export sinks"],
+                    result: null,
+                    invocationResultCode: "INVALID_EXECUTION_RESULT",
+                };
+            }
+        }
+        else if (classification.kind === "VALID_RESULT" &&
+            (classification.result?.output_files?.length ?? 0) > 0) {
+            classification = {
+                kind: "INVALID_RESULT",
+                attemptOutcome: "UNKNOWN",
+                resultCode: null,
+                details: ["output_files contains an unconfigured export sink"],
+                result: null,
+                invocationResultCode: "INVALID_EXECUTION_RESULT",
+            };
+        }
+        if (process.forced) {
+            classification = {
+                kind: "INVALID_RESULT",
+                attemptOutcome: "UNKNOWN",
+                resultCode: null,
+                details: [
+                    "process exceeded its grace period and was forcibly terminated",
+                ],
+                result: null,
+                invocationResultCode: "FORCED_TERMINATION",
+            };
+        }
+        const controlPlane = input.runControlPlaneOperation ??
+            ((operation) => operation());
+        const marker = await controlPlane(() => this.readMarker(input.attemptId, classification.result?.executionId));
+        const runnerStartedAt = marker?.runnerExecutionStartedAt ?? null;
+        let terminalStatus;
+        let resultCode;
+        let stateStatus;
+        let invocationResultCode = classification.invocationResultCode;
+        if (classification.kind === "VALID_RESULT") {
+            if (classification.attemptOutcome === "LOCK_CONFLICT") {
+                terminalStatus = "CANCELLED";
+                resultCode = "PREPARE_FAILED";
+                stateStatus = "WAITING";
+            }
+            else {
+                terminalStatus = classification.attemptOutcome;
+                resultCode = classification.resultCode;
+                stateStatus = terminalStatus;
+            }
+        }
+        else {
+            const missingDecision = decideMissingResult({
+                orchestratorExecutionStartedAt: startedAttempt.value.execution_started_at,
+                runnerExecutionStartedAt: runnerStartedAt,
+                durableLaunchFailureConfirmed: process.launchFailureConfirmed && marker !== undefined,
+            });
+            if (missingDecision === "NOT_EXECUTED") {
+                terminalStatus = "CANCELLED";
+                resultCode = "PREPARE_FAILED";
+                stateStatus = "WAITING";
+                invocationResultCode ??= "PREPARE_FAILED";
+            }
+            else {
+                terminalStatus = "UNKNOWN";
+                resultCode = process.forced
+                    ? "FORCED_TERMINATION"
+                    : classification.kind === "NO_RESULT"
+                        ? NO_EXECUTION_RESULT
+                        : "INVALID_EXECUTION_RESULT";
+                stateStatus = "UNKNOWN";
+            }
+        }
+        const result = classification.result;
+        const finishedAt = result?.finishedAt ?? this.now();
+        if (input.authorizeResultPersistence !== undefined &&
+            !(await input.authorizeResultPersistence())) {
+            throw new AttemptResultPersistenceDeferredError(classification, process);
+        }
+        const attempt = await controlPlane(() => this.options.repository.finalizeAttempt(startedAttempt.value.node_attempt_id, startedAttempt.revision, {
+            status: terminalStatus,
+            result_code: resultCode,
+            runner_execution_started_at: runnerStartedAt,
+            execution_id: result?.executionId ?? marker?.executionId ?? null,
+            finished_at: finishedAt,
+            duration_sec: result ? result.durationMs / 1000 : null,
+            error_message: auditSummary(input, result, classification),
+            read_count: result?.readCount ?? 0,
+            written_count: result?.writtenCount ?? 0,
+            last_successful_chunk_no: result?.lastSuccessfulChunkNo ?? null,
+            last_written_key: result?.lastWrittenKey ?? null,
+        }));
+        const waiting = stateStatus === "WAITING";
+        const nodeState = await controlPlane(() => this.options.repository.upsertNodeState({
+            expected_revision: input.nodeState.revision,
+            value: {
+                ...input.nodeState.value,
+                status: stateStatus,
+                active_attempt_id: null,
+                status_reason: waiting ? "PREPARE_FAILED" : resultCode,
+                started_at: waiting ? null : input.nodeState.value.started_at,
+                finished_at: waiting ? null : finishedAt,
+                updated_at: finishedAt,
+            },
+        }));
+        return {
+            classification,
+            process,
+            attempt,
+            nodeState,
+            invocationResultCode,
+        };
+    }
+    async readMarker(attemptId, executionId) {
+        try {
+            return await this.options.jobLogReader.findExecutionStarted({
+                attemptId,
+                ...(executionId === undefined ? {} : { executionId }),
+            });
+        }
+        catch (error) {
+            if (error instanceof KintoneTransportError ||
+                error instanceof KintoneApiError)
+                throw error;
+            return undefined;
+        }
+    }
+}
+function auditSummary(input, result, classification) {
+    const imports = input.imports ?? [];
+    const exports = input.exports ?? [];
+    if (result !== null && imports.length > 0 && exports.length > 0) {
+        return serializeIoAuditSummary(imports, (result.input_files ?? []).map((file) => ({
+            source: file.name,
+            sha256: file.sha256,
+            bytes: file.bytes,
+            rows: file.rows,
+            encoding: file.encoding,
+        })), result.output_files ?? []);
+    }
+    if (result !== null && exports.length > 0) {
+        return serializeOutputAuditSummary(result.output_files ?? []);
+    }
+    if (imports.length > 0) {
+        return result?.input_files === undefined
+            ? serializeInputBaseline(imports)
+            : serializeInputAuditSummary(imports, result.input_files.map((file) => ({
+                source: file.name,
+                sha256: file.sha256,
+                bytes: file.bytes,
+                rows: file.rows,
+                encoding: file.encoding,
+            })));
+    }
+    return result?.error?.message ?? (classification.details.join("; ") || null);
+}
+function assertPrepared(input) {
+    if (input.attempt.value.status !== "RUNNING" ||
+        input.nodeState.value.status !== "RUNNING" ||
+        input.nodeState.value.active_attempt_id !==
+            input.attempt.value.node_attempt_id ||
+        input.attempt.value.node_attempt_id !== input.attemptId)
+        throw new Error("attempt and node state must be the same prepared RUNNING execution");
+}
+//# sourceMappingURL=attempt-executor.js.map

package/dist/executor/job-log-reader.d.ts

@@ -0,0 +1,37 @@
+export interface JobLogLookup {
+    readonly attemptId: string;
+    readonly executionId?: string;
+}
+export interface JobLogMarker {
+    readonly runnerExecutionStartedAt: string | null;
+    readonly executionId: string | null;
+}
+export interface JobLogAttemptResult extends JobLogMarker {
+    readonly status: string;
+    readonly finishedAt: string | null;
+}
+export interface JobLogReader {
+    findExecutionStarted(lookup: JobLogLookup): Promise<JobLogMarker | null>;
+    findAttemptResult(attemptId: string): Promise<JobLogAttemptResult | null>;
+}
+export interface KintoneJobLogReaderOptions {
+    readonly baseUrl: string;
+    readonly appId: number;
+    readonly apiToken: string;
+    readonly fetch?: typeof fetch;
+}
+export declare class KintoneJobLogReader implements JobLogReader {
+    private readonly options;
+    private readonly fetchImpl;
+    constructor(options: KintoneJobLogReaderOptions);
+    findExecutionStarted(lookup: JobLogLookup): Promise<JobLogMarker | null>;
+    findAttemptResult(attemptId: string): Promise<JobLogAttemptResult | null>;
+    private findRecord;
+}
+export type MissingResultDecision = "NOT_EXECUTED" | "UNKNOWN";
+export declare function decideMissingResult(input: {
+    readonly orchestratorExecutionStartedAt: string | null;
+    readonly runnerExecutionStartedAt: string | null;
+    readonly durableLaunchFailureConfirmed: boolean;
+}): MissingResultDecision;
+//# sourceMappingURL=job-log-reader.d.ts.map

package/dist/executor/job-log-reader.js

@@ -0,0 +1,91 @@
+import { KintoneApiError, KintoneTransportError, } from "../persistence/kintone/client.js";
+export class KintoneJobLogReader {
+    options;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async findExecutionStarted(lookup) {
+        const record = await this.findRecord(lookup);
+        return record === null
+            ? null
+            : {
+                runnerExecutionStartedAt: fieldString(record.runner_execution_started_at),
+                executionId: fieldString(record.execution_id),
+            };
+    }
+    async findAttemptResult(attemptId) {
+        const record = await this.findRecord({ attemptId });
+        if (record === null)
+            return null;
+        const status = fieldString(record.status);
+        if (status === null)
+            throw new Error("job log status is missing");
+        return {
+            status,
+            runnerExecutionStartedAt: fieldString(record.runner_execution_started_at),
+            executionId: fieldString(record.execution_id),
+            finishedAt: fieldString(record.finished_at),
+        };
+    }
+    async findRecord(lookup) {
+        const clauses = [`attempt_id = "${escapeQuery(lookup.attemptId)}"`];
+        if (lookup.executionId)
+            clauses.push(`execution_id = "${escapeQuery(lookup.executionId)}"`);
+        const query = `${clauses.join(" and ")} order by runner_execution_started_at desc limit 2`;
+        const url = new URL(`${this.options.baseUrl.replace(/\/$/, "")}/k/v1/records.json`);
+        url.searchParams.set("app", String(this.options.appId));
+        url.searchParams.set("query", query);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: "GET",
+                headers: { "X-Cybozu-API-Token": this.options.apiToken },
+            });
+        }
+        catch (error) {
+            throw new KintoneTransportError(error);
+        }
+        const body = await response.json().catch(() => null);
+        if (!response.ok) {
+            const apiCode = isRecord(body) && typeof body.code === "string" ? body.code : null;
+            throw new KintoneApiError(response.status, apiCode, body);
+        }
+        if (!isRecord(body) || !Array.isArray(body.records))
+            throw new Error("job log GET returned an invalid response");
+        const records = body.records;
+        if (records.length === 0)
+            return null;
+        if (records.length > 1)
+            throw new Error("job log lookup is ambiguous");
+        const record = records[0];
+        if (!isRecord(record))
+            throw new Error("job log record is invalid");
+        return record;
+    }
+}
+export function decideMissingResult(input) {
+    if (input.orchestratorExecutionStartedAt === null &&
+        input.runnerExecutionStartedAt === null)
+        return "NOT_EXECUTED";
+    if (input.orchestratorExecutionStartedAt !== null &&
+        input.runnerExecutionStartedAt === null &&
+        input.durableLaunchFailureConfirmed)
+        return "NOT_EXECUTED";
+    return "UNKNOWN";
+}
+function escapeQuery(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function fieldString(value) {
+    if (!isRecord(value))
+        return null;
+    return typeof value.value === "string" && value.value.length > 0
+        ? value.value
+        : null;
+}
+//# sourceMappingURL=job-log-reader.js.map

package/dist/executor/ksql-flow-cli.d.ts

@@ -0,0 +1,86 @@
+export interface CapabilitiesResult {
+    readonly formatVersion: 1;
+    readonly kind: "CAPABILITIES";
+    readonly ksqlFlowVersion: string;
+    readonly engineVersion: string;
+    readonly executionContracts: readonly string[];
+    readonly resultSchema: {
+        readonly $id: string;
+        readonly contract: string;
+    };
+    readonly features: Readonly<Record<string, boolean | string>>;
+}
+export interface ProfileDescription {
+    readonly formatVersion: 1;
+    readonly kind: "PROFILE_DESCRIPTION";
+    readonly profile: string;
+    readonly baseUrl: string;
+    readonly guestSpaceId: number | null;
+    readonly timezone: string | null;
+    readonly apps: Readonly<Record<string, number>>;
+    readonly logApp: {
+        readonly name: string;
+        readonly appId: number;
+    } | null;
+    readonly limits: Readonly<Record<string, number | null>>;
+    readonly retry: {
+        readonly initialDelayMs: number;
+        readonly maxAttempts: number;
+        readonly maxDelayMs: number;
+        readonly respectRetryAfter: boolean;
+        readonly [key: string]: unknown;
+    };
+    readonly httpTimeoutMs: number;
+}
+export interface InspectionDiagnostic {
+    readonly code: string;
+    readonly severity: string;
+    readonly line: number;
+    readonly column: number;
+    readonly message: string;
+}
+export interface JobInspection {
+    readonly formatVersion: 1;
+    readonly kind: "JOB_INSPECTION";
+    readonly jobId: string;
+    readonly fileName: string;
+    readonly dialect: number;
+    readonly statementCount: number;
+    readonly dependsOn: readonly string[];
+    readonly timeoutSec: number | null;
+    readonly diagnostics: readonly InspectionDiagnostic[];
+    readonly nondeterministicElements: readonly InspectionDiagnostic[];
+}
+export type KsqlFlowCliErrorCode = "KSQL_FLOW_PROCESS_FAILED" | "KSQL_FLOW_INVALID_JSON" | "KSQL_FLOW_EXIT_MISMATCH" | "KSQL_FLOW_OUTPUT_INVALID";
+export declare class KsqlFlowCliError extends Error {
+    readonly code: KsqlFlowCliErrorCode;
+    constructor(code: KsqlFlowCliErrorCode, message: string, options?: ErrorOptions);
+}
+export interface SpawnRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface SpawnResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export type SpawnInvoker = (request: SpawnRequest) => Promise<SpawnResult>;
+export interface KsqlFlowCliOptions {
+    readonly command: string;
+    readonly binArgs?: readonly string[];
+    readonly profile: string;
+    readonly configPath: string;
+    readonly spawn?: SpawnInvoker;
+}
+export declare class KsqlFlowCli {
+    private readonly options;
+    private readonly invokeSpawn;
+    constructor(options: KsqlFlowCliOptions);
+    capabilities(): Promise<CapabilitiesResult>;
+    describeProfile(): Promise<ProfileDescription>;
+    inspectJob(sqlPath: string): Promise<JobInspection>;
+    private invokeJson;
+}
+export declare const spawnProcess: SpawnInvoker;
+//# sourceMappingURL=ksql-flow-cli.d.ts.map

package/dist/executor/ksql-flow-cli.js

@@ -0,0 +1,161 @@
+import { spawn } from "node:child_process";
+export class KsqlFlowCliError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "KsqlFlowCliError";
+    }
+}
+export class KsqlFlowCli {
+    options;
+    invokeSpawn;
+    constructor(options) {
+        this.options = options;
+        this.invokeSpawn = options.spawn ?? spawnProcess;
+    }
+    capabilities() {
+        return this.invokeJson(["capabilities", "--json"], isCapabilities, "CAPABILITIES");
+    }
+    describeProfile() {
+        return this.invokeJson([
+            "describe-profile",
+            "--profile",
+            this.options.profile,
+            "--config",
+            this.options.configPath,
+            "--json",
+        ], isProfileDescription, "PROFILE_DESCRIPTION");
+    }
+    inspectJob(sqlPath) {
+        return this.invokeJson([
+            "inspect-job",
+            "-f",
+            sqlPath,
+            "--profile",
+            this.options.profile,
+            "--config",
+            this.options.configPath,
+            "--json",
+        ], isJobInspection, "JOB_INSPECTION");
+    }
+    async invokeJson(args, validate, expectedKind) {
+        let result;
+        try {
+            result = await this.invokeSpawn({
+                command: this.options.command,
+                args: [...(this.options.binArgs ?? []), ...args],
+            });
+        }
+        catch (error) {
+            throw new KsqlFlowCliError("KSQL_FLOW_PROCESS_FAILED", `kSQL-Flow process could not be started for ${args[0]}`, { cause: error });
+        }
+        if (result.exitCode === null) {
+            throw new KsqlFlowCliError("KSQL_FLOW_PROCESS_FAILED", `kSQL-Flow process ended without an exit code for ${args[0]}`);
+        }
+        if (result.exitCode !== 0) {
+            throw new KsqlFlowCliError("KSQL_FLOW_EXIT_MISMATCH", `kSQL-Flow ${args[0]} exited with ${result.exitCode}; expected 0`);
+        }
+        let value;
+        try {
+            value = JSON.parse(result.stdout);
+        }
+        catch (error) {
+            throw new KsqlFlowCliError("KSQL_FLOW_INVALID_JSON", `kSQL-Flow ${args[0]} returned invalid JSON`, { cause: error });
+        }
+        if (!validate(value)) {
+            throw new KsqlFlowCliError("KSQL_FLOW_OUTPUT_INVALID", `kSQL-Flow ${args[0]} output does not match ${expectedKind} formatVersion 1`);
+        }
+        return value;
+    }
+}
+export const spawnProcess = ({ command, args }) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+        stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += chunk;
+    });
+    child.once("error", reject);
+    child.once("close", (exitCode) => resolve({ exitCode, stdout, stderr }));
+});
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return (Array.isArray(value) && value.every((item) => typeof item === "string"));
+}
+function isCapabilities(value) {
+    if (!isRecord(value) ||
+        !isRecord(value.resultSchema) ||
+        !isRecord(value.features)) {
+        return false;
+    }
+    return (value.formatVersion === 1 &&
+        value.kind === "CAPABILITIES" &&
+        typeof value.ksqlFlowVersion === "string" &&
+        typeof value.engineVersion === "string" &&
+        isStringArray(value.executionContracts) &&
+        typeof value.resultSchema.$id === "string" &&
+        typeof value.resultSchema.contract === "string" &&
+        Object.values(value.features).every((feature) => typeof feature === "boolean" || typeof feature === "string"));
+}
+function isProfileDescription(value) {
+    if (!isRecord(value) ||
+        !isRecord(value.apps) ||
+        !isRecord(value.limits) ||
+        !isRecord(value.retry)) {
+        return false;
+    }
+    const logAppValid = value.logApp === null ||
+        (isRecord(value.logApp) &&
+            typeof value.logApp.name === "string" &&
+            Number.isSafeInteger(value.logApp.appId));
+    return (value.formatVersion === 1 &&
+        value.kind === "PROFILE_DESCRIPTION" &&
+        typeof value.profile === "string" &&
+        typeof value.baseUrl === "string" &&
+        (value.guestSpaceId === null || Number.isSafeInteger(value.guestSpaceId)) &&
+        (value.timezone === null || typeof value.timezone === "string") &&
+        Object.values(value.apps).every(Number.isSafeInteger) &&
+        logAppValid &&
+        Object.values(value.limits).every((item) => item === null || typeof item === "number") &&
+        typeof value.retry.initialDelayMs === "number" &&
+        typeof value.retry.maxAttempts === "number" &&
+        typeof value.retry.maxDelayMs === "number" &&
+        typeof value.retry.respectRetryAfter === "boolean" &&
+        typeof value.httpTimeoutMs === "number");
+}
+function isDiagnostic(value) {
+    return (isRecord(value) &&
+        typeof value.code === "string" &&
+        typeof value.severity === "string" &&
+        Number.isSafeInteger(value.line) &&
+        Number.isSafeInteger(value.column) &&
+        typeof value.message === "string");
+}
+function isJobInspection(value) {
+    return (isRecord(value) &&
+        value.formatVersion === 1 &&
+        value.kind === "JOB_INSPECTION" &&
+        typeof value.jobId === "string" &&
+        typeof value.fileName === "string" &&
+        Number.isSafeInteger(value.dialect) &&
+        Number.isSafeInteger(value.statementCount) &&
+        isStringArray(value.dependsOn) &&
+        (value.timeoutSec === null || Number.isSafeInteger(value.timeoutSec)) &&
+        Array.isArray(value.diagnostics) &&
+        value.diagnostics.every(isDiagnostic) &&
+        Array.isArray(value.nondeterministicElements) &&
+        value.nondeterministicElements.every(isDiagnostic));
+}
+//# sourceMappingURL=ksql-flow-cli.js.map

package/dist/executor/preflight.d.ts

@@ -0,0 +1,41 @@
+import type { NetworkNodeDefinition } from "../domain/network-definition.js";
+import type { CapabilitiesResult, JobInspection, ProfileDescription } from "./ksql-flow-cli.js";
+export declare const EXECUTION_CONTRACT = "ksql-flow.execution/v1";
+export declare const REQUIRED_CAPABILITY_FEATURES: readonly ["resultJson", "correlationIds", "describeProfile", "inspectJob", "durableExecutionStarted"];
+export declare const NONDETERMINISTIC_CODES: readonly ["KSQL1306"];
+export interface ApprovedInspectionException {
+    readonly node_id: string;
+    readonly code: (typeof NONDETERMINISTIC_CODES)[number];
+    readonly approved_by: string;
+    readonly reason: string;
+    readonly approved_at: string;
+}
+export interface ProfileSnapshot {
+    readonly canonicalJsonSha256: string;
+    readonly baseUrl: string;
+    readonly guestSpaceId: number | null;
+    readonly apps: Readonly<Record<string, number>>;
+    readonly timezone: string | null;
+}
+export interface InspectedNode {
+    readonly nodeId: string;
+    readonly jobId: string;
+    readonly inspection: JobInspection;
+    readonly nondeterministicCodes: readonly string[];
+    readonly approvedExceptions: readonly ApprovedInspectionException[];
+}
+export type PreflightErrorCode = "CAPABILITY_CONTRACT_MISSING" | "CAPABILITY_FEATURE_MISSING" | "PROFILE_SNAPSHOT_MISMATCH" | "JOB_ID_MISMATCH" | "NONDETERMINISTIC_IDEMPOTENT_JOB" | "INSPECTION_EXCEPTION_INVALID" | "INSPECTION_EXCEPTION_NOT_DETECTED";
+export declare class PreflightError extends Error {
+    readonly code: PreflightErrorCode;
+    readonly details: readonly string[];
+    constructor(code: PreflightErrorCode, message: string, details?: readonly string[]);
+}
+export declare function validateCapabilities(capabilities: CapabilitiesResult, additionalFeatures?: readonly string[]): void;
+/** All object keys are sorted recursively; array order remains significant. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(value: Uint8Array | string): string;
+export declare function canonicalJsonSha256(value: unknown): string;
+export declare function profileSnapshot(description: ProfileDescription): ProfileSnapshot;
+export declare function assertProfileSnapshot(description: ProfileDescription, expected: ProfileSnapshot): void;
+export declare function validateJobInspections(nodes: readonly NetworkNodeDefinition[], inspections: ReadonlyMap<string, JobInspection>, exceptions?: readonly ApprovedInspectionException[]): readonly InspectedNode[];
+//# sourceMappingURL=preflight.d.ts.map