@rex0220/ksql-flownet 1.0.0

package/dist/executor/preflight.js

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+export const EXECUTION_CONTRACT = "ksql-flow.execution/v1";
+export const REQUIRED_CAPABILITY_FEATURES = [
+    "resultJson",
+    "correlationIds",
+    "describeProfile",
+    "inspectJob",
+    "durableExecutionStarted",
+];
+export const NONDETERMINISTIC_CODES = ["KSQL1306"];
+export class PreflightError extends Error {
+    code;
+    details;
+    constructor(code, message, details = []) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "PreflightError";
+    }
+}
+export function validateCapabilities(capabilities, additionalFeatures = []) {
+    if (!capabilities.executionContracts.includes(EXECUTION_CONTRACT)) {
+        throw new PreflightError("CAPABILITY_CONTRACT_MISSING", `required execution contract '${EXECUTION_CONTRACT}' is not supported`);
+    }
+    const required = [...REQUIRED_CAPABILITY_FEATURES, ...additionalFeatures];
+    const missing = required.filter((feature) => capabilities.features[feature] !== true);
+    if (missing.length > 0) {
+        throw new PreflightError("CAPABILITY_FEATURE_MISSING", `required capability features are not true: ${missing.join(", ")}`, missing);
+    }
+}
+/** All object keys are sorted recursively; array order remains significant. */
+export function canonicalJson(value) {
+    const serialized = JSON.stringify(sortJsonKeys(value));
+    if (serialized === undefined) {
+        throw new TypeError("value cannot be represented as canonical JSON");
+    }
+    return serialized;
+}
+export function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function canonicalJsonSha256(value) {
+    return sha256Hex(Buffer.from(canonicalJson(value), "utf8"));
+}
+export function profileSnapshot(description) {
+    return {
+        canonicalJsonSha256: canonicalJsonSha256(description),
+        baseUrl: description.baseUrl,
+        guestSpaceId: description.guestSpaceId,
+        apps: description.apps,
+        timezone: description.timezone,
+    };
+}
+export function assertProfileSnapshot(description, expected) {
+    const actual = profileSnapshot(description);
+    const mismatches = [];
+    if (actual.canonicalJsonSha256 !== expected.canonicalJsonSha256) {
+        mismatches.push("canonicalJsonSha256");
+    }
+    if (actual.baseUrl !== expected.baseUrl)
+        mismatches.push("baseUrl");
+    if (actual.guestSpaceId !== expected.guestSpaceId) {
+        mismatches.push("guestSpaceId");
+    }
+    if (actual.timezone !== expected.timezone)
+        mismatches.push("timezone");
+    if (canonicalJson(actual.apps) !== canonicalJson(expected.apps)) {
+        mismatches.push("apps");
+    }
+    if (mismatches.length > 0) {
+        throw new PreflightError("PROFILE_SNAPSHOT_MISMATCH", `resolved profile differs from snapshot: ${mismatches.join(", ")}`, mismatches);
+    }
+}
+export function validateJobInspections(nodes, inspections, exceptions = []) {
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    validateExceptionFields(exceptions, nodesById);
+    const duplicateKeys = new Set();
+    const seenKeys = new Set();
+    for (const exception of exceptions) {
+        const key = `${exception.node_id}\0${exception.code}`;
+        if (seenKeys.has(key))
+            duplicateKeys.add(key);
+        seenKeys.add(key);
+    }
+    if (duplicateKeys.size > 0) {
+        throw new PreflightError("INSPECTION_EXCEPTION_INVALID", "duplicate approved inspection exception");
+    }
+    const result = [];
+    for (const node of nodes) {
+        const inspection = inspections.get(node.id);
+        if (inspection === undefined) {
+            throw new PreflightError("JOB_ID_MISMATCH", `inspection is missing for node '${node.id}'`, [node.id]);
+        }
+        if (inspection.jobId !== node.job_id) {
+            throw new PreflightError("JOB_ID_MISMATCH", `node '${node.id}' expects job_id '${node.job_id}', inspected '${inspection.jobId}'`, [node.id]);
+        }
+        // D-23 deliberately recognizes only the engine's public KSQL1306 code.
+        // KSQL1305 remains a warning and static inspection does not prove idempotency.
+        const detected = uniqueSorted(inspection.nondeterministicElements
+            .filter((diagnostic) => NONDETERMINISTIC_CODES.includes(diagnostic.code))
+            .map((diagnostic) => diagnostic.code));
+        const approved = exceptions.filter((exception) => exception.node_id === node.id);
+        for (const exception of approved) {
+            if (!detected.includes(exception.code)) {
+                throw new PreflightError("INSPECTION_EXCEPTION_NOT_DETECTED", `exception ${exception.code} for node '${node.id}' has no matching detected diagnostic`, [node.id, exception.code]);
+            }
+        }
+        const unapproved = detected.filter((code) => !approved.some((exception) => exception.code === code));
+        if (node.idempotent && unapproved.length > 0) {
+            throw new PreflightError("NONDETERMINISTIC_IDEMPOTENT_JOB", `idempotent node '${node.id}' has unapproved nondeterministic elements: ${unapproved.join(", ")}`, [node.id, ...unapproved]);
+        }
+        result.push({
+            nodeId: node.id,
+            jobId: inspection.jobId,
+            inspection,
+            nondeterministicCodes: detected,
+            approvedExceptions: approved,
+        });
+    }
+    return result;
+}
+function sortJsonKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortJsonKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort()) {
+        sorted[key] = sortJsonKeys(source[key]);
+    }
+    return sorted;
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort();
+}
+function validateExceptionFields(exceptions, nodesById) {
+    for (const exception of exceptions) {
+        const validTimestamp = typeof exception.approved_at === "string" &&
+            Number.isFinite(Date.parse(exception.approved_at));
+        if (!nodesById.has(exception.node_id) ||
+            !NONDETERMINISTIC_CODES.includes(exception.code) ||
+            exception.approved_by.trim() === "" ||
+            exception.reason.trim() === "" ||
+            !validTimestamp) {
+            throw new PreflightError("INSPECTION_EXCEPTION_INVALID", `approved inspection exception is invalid for node '${exception.node_id}'`, [exception.node_id, exception.code]);
+        }
+    }
+}
+//# sourceMappingURL=preflight.js.map

package/dist/executor/result-classifier.d.ts

@@ -0,0 +1,69 @@
+export declare const NO_EXECUTION_RESULT: "NO_EXECUTION_RESULT";
+export type AttemptOutcome = "SUCCESS" | "FAILED" | "CANCELLED" | "UNKNOWN" | "LOCK_CONFLICT";
+export interface ExecutionError {
+    readonly category: string;
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+    readonly detailsTruncated: boolean;
+}
+export interface ExecutionInputFile {
+    readonly name: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly rows: number;
+    readonly encoding: string;
+}
+export interface ExecutionOutputFile {
+    readonly name: string;
+    readonly sha256: string;
+    readonly bytes: number;
+    readonly rows: number;
+    readonly encoding: string;
+}
+export interface ExecutionResult {
+    readonly formatVersion: 1;
+    readonly kind: "EXECUTION_RESULT";
+    readonly contract: "ksql-flow.execution/v1";
+    readonly correlationId: string;
+    readonly attemptId: string;
+    readonly executionId: string;
+    readonly jobId: string;
+    readonly profile: string;
+    readonly status: "SUCCESS" | "FAILED" | "CANCELLED";
+    readonly resultCode: string;
+    readonly executionStarted: boolean;
+    readonly exitCode: number;
+    readonly asOf: string | null;
+    readonly startedAt: string | null;
+    readonly finishedAt: string;
+    readonly durationMs: number;
+    readonly readCount: number;
+    readonly writtenCount: number;
+    readonly deletedCount: number;
+    readonly apiCalls: number;
+    readonly lastSuccessfulChunkNo: number | null;
+    readonly lastWrittenKey: string | null;
+    readonly ksqlFlowVersion: string;
+    readonly engineVersion: string;
+    readonly error: ExecutionError | null;
+    readonly input_files?: readonly ExecutionInputFile[];
+    readonly output_files?: readonly ExecutionOutputFile[];
+}
+export interface ClassificationContext {
+    readonly correlationId: string;
+    readonly attemptId: string;
+    readonly processExitCode: number | null;
+}
+export interface ResultClassification {
+    readonly kind: "VALID_RESULT" | "INVALID_RESULT" | "NO_RESULT";
+    readonly attemptOutcome: AttemptOutcome;
+    readonly resultCode: string | null;
+    readonly details: readonly string[];
+    readonly result: ExecutionResult | null;
+    readonly invocationResultCode: string | null;
+}
+export type ResultFileReader = (path: string) => Promise<string>;
+export declare function readAndClassifyResult(path: string, context: ClassificationContext, reader?: ResultFileReader): Promise<ResultClassification>;
+export declare function classifyResult(value: unknown, context: ClassificationContext): ResultClassification;
+//# sourceMappingURL=result-classifier.d.ts.map

package/dist/executor/result-classifier.js

@@ -0,0 +1,237 @@
+import { readFile } from "node:fs/promises";
+export const NO_EXECUTION_RESULT = "NO_EXECUTION_RESULT";
+const KNOWN_RESULTS = {
+    OK: { status: "SUCCESS", exitCode: 0 },
+    NO_DATA: { status: "SUCCESS", exitCode: 0 },
+    VALIDATION_ERROR: { status: "FAILED", exitCode: 1 },
+    ASSERT_FAILED: { status: "FAILED", exitCode: 2 },
+    SQL_ERROR: { status: "FAILED", exitCode: 1 },
+    API_ERROR: { status: "FAILED", exitCode: 3 },
+    AUTH_ERROR: { status: "FAILED", exitCode: 3 },
+    EXECUTION_TIMEOUT: { status: "FAILED", exitCode: 3 },
+    LOCK_UNAVAILABLE: { status: "FAILED", exitCode: 3 },
+    INTERNAL_ERROR: { status: "FAILED", exitCode: 3 },
+    CANCELLED: { status: "CANCELLED", exitCode: 3 },
+    LOCK_CONFLICT: { status: "FAILED", exitCode: 5 },
+};
+export async function readAndClassifyResult(path, context, reader = (filePath) => readFile(filePath, "utf8")) {
+    let source;
+    try {
+        source = await reader(path);
+    }
+    catch {
+        return noResult("result file does not exist or could not be read");
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        return noResult("result file is not complete JSON");
+    }
+    return classifyResult(value, context);
+}
+export function classifyResult(value, context) {
+    const errors = validateShape(value);
+    if (errors.length > 0 || !isRecord(value))
+        return invalid(errors);
+    if (value.correlationId !== context.correlationId)
+        errors.push("correlationId does not echo the invocation value");
+    if (value.attemptId !== context.attemptId)
+        errors.push("attemptId does not echo the invocation value");
+    if (value.exitCode !== context.processExitCode)
+        errors.push("result exitCode does not match process exit code");
+    const status = value.status;
+    const resultCode = value.resultCode;
+    const exitCode = value.exitCode;
+    const known = KNOWN_RESULTS[resultCode];
+    if (known) {
+        if (known.status !== status || known.exitCode !== exitCode)
+            errors.push("status/resultCode/exitCode combination is inconsistent");
+    }
+    else if (!isStatusExitCompatible(status, exitCode)) {
+        errors.push("unknown resultCode has an inconsistent status/exitCode");
+    }
+    if ((resultCode === "VALIDATION_ERROR" || resultCode === "LOCK_CONFLICT") &&
+        value.executionStarted !== false)
+        errors.push(`${resultCode} requires executionStarted=false`);
+    if (status === "SUCCESS" && value.executionStarted !== true)
+        errors.push("SUCCESS requires executionStarted=true");
+    if (errors.length > 0)
+        return invalid(errors);
+    const result = value;
+    const attemptOutcome = resultCode === "LOCK_CONFLICT"
+        ? "LOCK_CONFLICT"
+        : status === "SUCCESS"
+            ? "SUCCESS"
+            : status === "CANCELLED"
+                ? "CANCELLED"
+                : "FAILED";
+    return {
+        kind: "VALID_RESULT",
+        attemptOutcome,
+        resultCode,
+        details: [],
+        result,
+        invocationResultCode: resultCode === "LOCK_CONFLICT" ? "LOCK_CONFLICT" : null,
+    };
+}
+function validateShape(value) {
+    if (!isRecord(value))
+        return ["result must be a JSON object"];
+    const errors = [];
+    literal(value, "formatVersion", 1, errors);
+    literal(value, "kind", "EXECUTION_RESULT", errors);
+    literal(value, "contract", "ksql-flow.execution/v1", errors);
+    for (const field of [
+        "correlationId",
+        "attemptId",
+        "executionId",
+        "jobId",
+        "profile",
+        "resultCode",
+        "finishedAt",
+        "ksqlFlowVersion",
+        "engineVersion",
+    ])
+        requireString(value, field, errors);
+    if (!["SUCCESS", "FAILED", "CANCELLED"].includes(String(value.status)))
+        errors.push("status must be SUCCESS, FAILED, or CANCELLED");
+    if (typeof value.executionStarted !== "boolean")
+        errors.push("executionStarted must be boolean");
+    if (!Number.isSafeInteger(value.exitCode))
+        errors.push("exitCode must be an integer");
+    if (!(value.asOf === null || isOffsetIso(value.asOf)))
+        errors.push("asOf must be an ISO-8601 timestamp or null");
+    if (!(value.startedAt === null || isUtcIso(value.startedAt)))
+        errors.push("startedAt must be a UTC ISO-8601 timestamp or null");
+    if (!isUtcIso(value.finishedAt))
+        errors.push("finishedAt must be a UTC ISO-8601 timestamp");
+    if (typeof value.durationMs !== "number" ||
+        !Number.isFinite(value.durationMs) ||
+        value.durationMs < 0)
+        errors.push("durationMs must be non-negative");
+    for (const field of ["readCount", "writtenCount", "deletedCount", "apiCalls"])
+        requireNonNegativeInteger(value, field, errors);
+    if (!(value.lastSuccessfulChunkNo === null ||
+        (Number.isSafeInteger(value.lastSuccessfulChunkNo) &&
+            value.lastSuccessfulChunkNo >= 0)))
+        errors.push("lastSuccessfulChunkNo must be a non-negative integer or null");
+    if (!(value.lastWrittenKey === null || typeof value.lastWrittenKey === "string"))
+        errors.push("lastWrittenKey must be string or null");
+    if (!(value.error === null || isExecutionError(value.error)))
+        errors.push("error must be a contract error object or null");
+    if (value.input_files !== undefined &&
+        !isExecutionFileReceipts(value.input_files, false))
+        errors.push("input_files must contain safe input receipt entries");
+    if (value.output_files !== undefined &&
+        !isExecutionFileReceipts(value.output_files, true))
+        errors.push("output_files must contain safe output receipt entries");
+    if (value.status === "SUCCESS" && value.error !== null)
+        errors.push("SUCCESS requires error=null");
+    if (value.status !== "SUCCESS" && value.error === null)
+        errors.push("non-success result requires an error object");
+    return errors;
+}
+function isExecutionFileReceipts(value, output) {
+    if (!Array.isArray(value))
+        return false;
+    const names = new Set();
+    for (const item of value) {
+        if (!isRecord(item) ||
+            (output &&
+                !hasOnlyKeys(item, ["name", "sha256", "bytes", "rows", "encoding"])) ||
+            typeof item.name !== "string" ||
+            !isSafeSourceName(item.name) ||
+            names.has(item.name) ||
+            typeof item.sha256 !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(item.sha256) ||
+            !Number.isSafeInteger(item.bytes) ||
+            item.bytes < 0 ||
+            !Number.isSafeInteger(item.rows) ||
+            item.rows < 0 ||
+            typeof item.encoding !== "string" ||
+            (output
+                ? !["utf8", "sjis"].includes(item.encoding)
+                : !/^[A-Za-z0-9._-]{1,32}$/u.test(item.encoding)))
+            return false;
+        names.add(item.name);
+    }
+    return true;
+}
+function hasOnlyKeys(value, expected) {
+    return (JSON.stringify(Object.keys(value).sort()) ===
+        JSON.stringify([...expected].sort()));
+}
+function isSafeSourceName(value) {
+    return (value.length >= 1 &&
+        value.length <= 128 &&
+        value !== "__net__" &&
+        !value.includes(":") &&
+        !value.includes("=") &&
+        ![...value].some((character) => {
+            const code = character.codePointAt(0);
+            return code <= 0x1f || code === 0x7f;
+        }));
+}
+function isStatusExitCompatible(status, exitCode) {
+    if (status === "SUCCESS")
+        return exitCode === 0;
+    if (status === "CANCELLED")
+        return exitCode === 3;
+    return [1, 2, 3, 5].includes(exitCode);
+}
+function isExecutionError(value) {
+    return (isRecord(value) &&
+        typeof value.category === "string" &&
+        typeof value.code === "string" &&
+        typeof value.message === "string" &&
+        typeof value.retryable === "boolean" &&
+        typeof value.detailsTruncated === "boolean");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isUtcIso(value) {
+    return (typeof value === "string" &&
+        /T.*Z$/.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+function isOffsetIso(value) {
+    return (typeof value === "string" &&
+        /T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value) &&
+        !Number.isNaN(Date.parse(value)));
+}
+function literal(value, field, expected, errors) {
+    if (value[field] !== expected)
+        errors.push(`${field} must be ${String(expected)}`);
+}
+function requireString(value, field, errors) {
+    if (typeof value[field] !== "string" || value[field].length === 0)
+        errors.push(`${field} must be a non-empty string`);
+}
+function requireNonNegativeInteger(value, field, errors) {
+    if (!Number.isSafeInteger(value[field]) || value[field] < 0)
+        errors.push(`${field} must be a non-negative integer`);
+}
+function invalid(details) {
+    return {
+        kind: "INVALID_RESULT",
+        attemptOutcome: "UNKNOWN",
+        resultCode: null,
+        details,
+        result: null,
+        invocationResultCode: "INVALID_EXECUTION_RESULT",
+    };
+}
+function noResult(detail) {
+    return {
+        kind: "NO_RESULT",
+        attemptOutcome: "UNKNOWN",
+        resultCode: null,
+        details: [detail],
+        result: null,
+        invocationResultCode: NO_EXECUTION_RESULT,
+    };
+}
+//# sourceMappingURL=result-classifier.js.map

package/dist/executor/run-subprocess.d.ts

@@ -0,0 +1,64 @@
+export interface RunRequest {
+    readonly sqlPath: string;
+    readonly profile: string;
+    readonly configPath: string;
+    readonly asOf: string;
+    readonly correlationId: string;
+    readonly attemptId: string;
+    readonly expectedJobId: string;
+    readonly imports?: readonly RunImport[];
+    readonly exports?: readonly RunExport[];
+}
+export interface RunImport {
+    readonly name: string;
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+export interface RunExport {
+    readonly name: string;
+    readonly path: string;
+}
+export interface ProcessExit {
+    readonly exitCode: number | null;
+    readonly launchFailureConfirmed?: boolean;
+    readonly launchError?: string;
+}
+export interface SpawnHandle {
+    readonly completion: Promise<ProcessExit>;
+    gracefulStop(): void | Promise<void>;
+    forceStop(): void | Promise<void>;
+}
+export interface SpawnRunRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    onStdout(chunk: string): void;
+    onStderr(chunk: string): void;
+}
+export type RunSpawn = (request: SpawnRunRequest) => SpawnHandle;
+export interface RunSubprocessOptions {
+    readonly command: string;
+    readonly binArgs?: readonly string[];
+    readonly executionDirectory: string;
+    readonly timeoutMs: number | null;
+    readonly gracePeriodMs: number;
+    readonly forcedExitWaitMs?: number;
+    readonly spawn?: RunSpawn;
+}
+export interface SubprocessRunResult {
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly resultJsonPath: string;
+    readonly timedOut: boolean;
+    readonly forced: boolean;
+    readonly launchFailureConfirmed: boolean;
+}
+export declare class RunSubprocess {
+    private readonly options;
+    private readonly spawn;
+    constructor(options: RunSubprocessOptions);
+    run(request: RunRequest): Promise<SubprocessRunResult>;
+}
+export declare const spawnRunProcess: RunSpawn;
+//# sourceMappingURL=run-subprocess.d.ts.map