import { type WorkflowHostServer } from "./host_server.js";
import type { ProgramResult, ProgramRunnerDeps } from "./program_runner.js";
/** Default interpreter, resolved on PATH — the base image bakes one CPython (P5.3). */
export declare const DEFAULT_PYTHON_INTERPRETER = "python3";
/** Where the ratified Python artifact layout keeps the author's SOURCE tree. A stored Python
 *  entry (`main.py`) is relative to THIS dir — Python has no bundle step, so the shipped source
 *  is what runs (`<extractDir>/.bw-src/main.py`), never a root module like the TS `index.mjs`. */
export declare const PYTHON_SOURCE_DIR = ".bw-src";
/** Where the ratified layout keeps the uv-materialized frozen dependency tree (build-time
 *  `uv lock` → `export --frozen` → `pip install --target`; never installed on the hot path). */
export declare const PYTHON_SITE_PACKAGES_DIR: string;
/**
 * The platform-owned `PYTHONPATH` for a Python program run:
 *
 *     <programDir>/.bw-src  <sep>  <programDir>/.bw-machine/site-packages
 *
 * ORDER (deliberate): the author's sources BEFORE the frozen deps, so an author module wins a
 * name collision with a dependency. That mirrors CPython's own convention — the interpreter puts
 * a script's directory ahead of site-packages — extended to the whole tree, which needs an
 * explicit entry because the loader is launched `-m` style (sys.path[0] is the workspace cwd,
 * not `.bw-src`) yet sibling imports (`import helper`) must resolve from the source tree. The
 * file an author can SEE in the Code tab beating an invisible dep is the predictable reading.
 *
 * The value REPLACES any PYTHONPATH inherited from the worker's env: for a Python run the
 * module path is platform-owned (the guest image provides python3 with the `boardwalk` loader
 * package importable at site level; nothing from the worker's own environment may steer author
 * import resolution). A no-dep package ships no site-packages dir at all — Python silently
 * skips a nonexistent sys.path entry, so the value is set unconditionally, never stat-gated.
 */
export declare function pythonModulePath(programDir: string): string;
/** The loader module the guest image's `boardwalk` package provides (`python -m <module> <entry>`). */
export declare const PYTHON_LOADER_MODULE = "boardwalk._loader";
/** How long after SIGTERM an aborted child gets before SIGKILL. */
export declare const DEFAULT_PYTHON_KILL_GRACE_MS = 5000;
/** How many trailing stderr lines are kept for failure curation (the traceback tail). */
export declare const STDERR_TAIL_LINES = 20;
/** The language dispatch decision (P5.5): `.py` takes the subprocess path; everything else
 *  (`.ts`/`.js`/`.mjs`) keeps the in-process TS loader. Case-insensitive on the extension. */
export declare function isPythonEntry(entry: string): boolean;
/** Split a piped stream into complete lines (LF or CRLF). `flush()` emits a trailing partial
 *  line (a crash mid-line must not swallow the last words of the traceback). */
export declare function lineSplitter(onLine: (line: string) => void): {
    push: (chunk: string) => void;
    flush: () => void;
};
/** What the child process ended as, for failure curation. */
export interface PythonExitFacts {
    exitCode: number | null;
    signal: NodeJS.Signals | null;
    /** The last {@link STDERR_TAIL_LINES} stderr lines, oldest first. */
    stderrTail: readonly string[];
}
/**
 * Curate a child that ended WITHOUT completing the loader contract (no `report_return`) into a
 * throwable the runner's failure path understands (`{code, message, hint}`, duck-typed). The
 * caller redacts — nothing here needs to.
 */
export declare function curatePythonFailure(facts: PythonExitFacts): Error;
/** Fail CLOSED on a spawn failure: a missing interpreter gets an UNSUPPORTED-class error naming
 *  the image expectation instead of a bare ENOENT; anything else passes through untouched. */
export declare function curateSpawnFailure(interpreter: string, err: NodeJS.ErrnoException): Error;
/**
 * Run a Python workflow program to completion: spawn the loader subprocess against the already
 * -listening host server, stream its output into the program log capture, and read the terminal
 * state off the server once the child exits. Resolves `completed` when `report_return` landed;
 * THROWS on failure (the caller curates + redacts, same as the TS path).
 */
export declare function invokePythonProgram(entryPath: string, programDir: string, sockPath: string, server: WorkflowHostServer, deps: ProgramRunnerDeps): Promise<ProgramResult>;