kibi-cli 2.1.0 → 2.3.0

package/dist/prolog/swipl-resolver.d.ts

@@ -0,0 +1,88 @@
+export type SwiplSource = "env" | "bundled" | "path";
+export type ResolvedSwipl = {
+    /** Absolute path to the executable. */
+    bin: string;
+    /** SWI_HOME_DIR for a bundled build. */
+    home?: string;
+    /** Upstream SWI-Prolog version, e.g. "10.0.2". */
+    version: string;
+    source: SwiplSource;
+};
+export declare const MINIMUM_SWIPL_MAJOR = 9;
+export type SwiplResolutionErrorCode = "swipl_not_found" | "swipl_env_invalid" | "swipl_bundle_corrupt";
+/** Structured failure; `message` is the complete operator-facing guidance. */
+export declare class SwiplResolutionError extends Error {
+    readonly code: SwiplResolutionErrorCode;
+    /** Detected host, e.g. "linux-x64 (glibc)". */
+    readonly platform: string;
+    /** Platform package that would have covered this host, when one exists. */
+    readonly packageName: string | undefined;
+    constructor(code: SwiplResolutionErrorCode, message: string, platform: string, packageName: string | undefined);
+}
+export type SwiplResolverDeps = {
+    platform: string;
+    arch: string;
+    /** True on glibc Linux, false on musl, undefined off Linux. */
+    glibc: boolean | undefined;
+    /** Directory of an installed platform package, or undefined. */
+    locatePackage: (packageName: string) => string | undefined;
+    /** Output of `<bin> --version`; throws when the executable cannot run. */
+    runVersion: (bin: string) => string;
+};
+/** Parse `SWI-Prolog version 10.0.2 for x86_64-linux` into its version. */
+export declare function parseSwiplVersion(output: string): {
+    version: string;
+    major: number;
+} | undefined;
+/** Uncached resolution with injectable host facts; the test seam. */
+export declare function resolveSwiplWith(env: NodeJS.ProcessEnv, deps: SwiplResolverDeps): ResolvedSwipl;
+/**
+ * Resolve the SWI-Prolog executable for this process. The result is cached for
+ * the lifetime of the process, keyed by the inputs that select it.
+ */
+export declare function resolveSwipl(env?: NodeJS.ProcessEnv): ResolvedSwipl;
+/** Test seam: forget every cached resolution. */
+export declare function resetSwiplResolverCache(): void;
+/** Stable identity of a resolved runtime, compared across engine processes. */
+export declare function swiplIdentity(resolved: ResolvedSwipl): string;
+/** Environment additions a child needs to run the resolved SWI-Prolog. */
+export declare function swiplChildEnv(resolved: Pick<ResolvedSwipl, "home">): Record<string, string>;
+export type BundleStatus = {
+    state: "unsupported";
+} | {
+    state: "missing" | "empty";
+    packageName: string;
+} | {
+    state: "corrupt";
+    packageName: string;
+    reason: string;
+} | {
+    state: "installed";
+    packageName: string;
+};
+/** Report the bundled package's state without resolving a runtime. */
+export declare function inspectSwiplBundle(deps?: SwiplResolverDeps): BundleStatus;
+/** Libraries Kibi loads at runtime; a SWI-Prolog lacking one cannot serve it. */
+export declare const REQUIRED_SWIPL_LIBRARIES: readonly ["semweb/rdf_db", "semweb/rdf_persistency", "semweb/sparql_client", "pcre", "crypto", "sha", "http/json", "http/json_convert", "chr", "clpfd", "thread", "persistency", "filesex", "readutil", "date", "aggregate", "solution_sequences"];
+export type SwiplGoalRunner = (bin: string, args: readonly string[], env: NodeJS.ProcessEnv) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+export type LibraryProbe = {
+    kind: "ok";
+} | {
+    kind: "missing";
+    libraries: string[];
+} | {
+    kind: "failed";
+    detail: string;
+};
+/**
+ * Load every required library in one throwaway SWI-Prolog process and report
+ * the ones that fail. A probe that cannot run is reported as such, never as a
+ * pass.
+ */
+export declare function probeRequiredLibraries(resolved: ResolvedSwipl, run?: SwiplGoalRunner, env?: NodeJS.ProcessEnv): LibraryProbe;
+//# sourceMappingURL=swipl-resolver.d.ts.map

package/dist/prolog/swipl-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swipl-resolver.d.ts","sourceRoot":"","sources":["../../src/prolog/swipl-resolver.ts"],"names":[],"mappings":"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"}

package/dist/prolog/swipl-resolver.js

@@ -0,0 +1,446 @@
+/*
+ * Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ * Copyright (C) 2026 Piotr Franczyk
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ */
+/**
+ * Resolves the SWI-Prolog executable Kibi runs, in this order:
+ *
+ * 1. `KIBI_SWIPL=<absolute path>` (an explicit operator choice always wins).
+ * 2. The bundled platform package (`kibi-swipl-<platform>`), after its build
+ *    manifest and binary checksum verify. `KIBI_SWIPL=system` skips this step.
+ * 3. `swipl` on `PATH`, subject to the SWI-Prolog 9.0 minimum.
+ * 4. Otherwise an error naming the platform, the platform package that would
+ *    have covered it, and the OS install command.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { constants, accessSync, existsSync, readFileSync, statSync, } from "node:fs";
+import path from "node:path";
+import { BUNDLED_BINARY_PATH, MANIFEST_FILE, PLATFORM_PACKAGES, locatePlatformPackage, platformKey, sha256File, validateBuildManifest, } from "kibi-swipl";
+export const MINIMUM_SWIPL_MAJOR = 9;
+/** Structured failure; `message` is the complete operator-facing guidance. */
+export class SwiplResolutionError extends Error {
+    code;
+    /** Detected host, e.g. "linux-x64 (glibc)". */
+    platform;
+    /** Platform package that would have covered this host, when one exists. */
+    packageName;
+    constructor(code, message, platform, packageName) {
+        super(message);
+        this.name = "SwiplResolutionError";
+        this.code = code;
+        this.platform = platform;
+        this.packageName = packageName;
+    }
+}
+function detectGlibc() {
+    if (process.platform !== "linux")
+        return undefined;
+    try {
+        const report = process.report?.getReport?.();
+        if (report !== undefined) {
+            return typeof report.header?.glibcVersionRuntime === "string";
+        }
+    }
+    catch {
+        // Fall back to the musl loader probe below.
+    }
+    return !["/lib/ld-musl-x86_64.so.1", "/lib/ld-musl-aarch64.so.1"].some((loader) => existsSync(loader));
+}
+function defaultRunVersion(bin) {
+    return execFileSync(bin, ["--version"], {
+        encoding: "utf8",
+        timeout: 10_000,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function defaultDeps() {
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        glibc: detectGlibc(),
+        locatePackage: (name) => locatePlatformPackage(name),
+        runVersion: defaultRunVersion,
+    };
+}
+/** Parse `SWI-Prolog version 10.0.2 for x86_64-linux` into its version. */
+export function parseSwiplVersion(output) {
+    const match = /version\s+(\d+)\.(\d+)(?:\.(\d+))?/i.exec(output);
+    if (match === null)
+        return undefined;
+    const [, major, minor, patch] = match;
+    return {
+        version: `${major}.${minor}${patch === undefined ? "" : `.${patch}`}`,
+        major: Number.parseInt(major ?? "0", 10),
+    };
+}
+function installCommand(platform) {
+    if (platform === "linux") {
+        return "sudo apt-add-repository ppa:swi-prolog/stable && sudo apt-get update && sudo apt-get install swi-prolog";
+    }
+    if (platform === "darwin")
+        return "brew install swi-prolog";
+    return "download the installer from https://www.swi-prolog.org/download/stable and add swipl to PATH";
+}
+function hostLabel(deps) {
+    const libc = deps.platform === "linux" && deps.glibc !== undefined
+        ? ` (${deps.glibc ? "glibc" : "musl"})`
+        : "";
+    return `${deps.platform}-${deps.arch}${libc}`;
+}
+function isExecutableFile(candidate) {
+    try {
+        if (!statSync(candidate).isFile())
+            return false;
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function inspectBundle(deps) {
+    const key = platformKey({
+        platform: deps.platform,
+        arch: deps.arch,
+        glibc: deps.glibc,
+    });
+    if (key === undefined)
+        return { kind: "unsupported" };
+    const packageName = PLATFORM_PACKAGES[key].package;
+    const packageDir = deps.locatePackage(packageName);
+    if (packageDir === undefined)
+        return { kind: "missing", key, packageName };
+    const manifestPath = path.join(packageDir, MANIFEST_FILE);
+    const binary = path.join(packageDir, BUNDLED_BINARY_PATH);
+    if (!existsSync(manifestPath)) {
+        // A workspace checkout links the package without the pipeline payload.
+        // A binary without a manifest is a damaged install, not a placeholder.
+        if (!existsSync(binary))
+            return { kind: "empty", key, packageName };
+        return {
+            kind: "corrupt",
+            key,
+            packageName,
+            reason: `${MANIFEST_FILE} is missing next to ${BUNDLED_BINARY_PATH}`,
+        };
+    }
+    const corrupt = (reason) => ({
+        kind: "corrupt",
+        key,
+        packageName,
+        reason,
+    });
+    let manifest;
+    let packageJson;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return corrupt(`${MANIFEST_FILE} is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    try {
+        packageJson = JSON.parse(readFileSync(path.join(packageDir, "package.json"), "utf8"));
+    }
+    catch (error) {
+        return corrupt(`package.json is unreadable (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const packageVersion = packageJson.kibi?.swiplVersion;
+    const checked = validateBuildManifest(manifest, {
+        target: key,
+        swiplVersion: typeof packageVersion === "string" ? packageVersion : undefined,
+    });
+    if (!checked.ok)
+        return corrupt(checked.reason);
+    if (!isExecutableFile(binary)) {
+        return corrupt(`${BUNDLED_BINARY_PATH} is missing or not executable`);
+    }
+    let actual;
+    try {
+        actual = sha256File(binary);
+    }
+    catch (error) {
+        return corrupt(`${BUNDLED_BINARY_PATH} is unreadable (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (actual !== checked.binarySha256) {
+        return corrupt(`${BUNDLED_BINARY_PATH} SHA-256 ${actual} does not match the manifest (${checked.binarySha256})`);
+    }
+    const home = path.join(packageDir, checked.home);
+    let homeIsDirectory = false;
+    try {
+        homeIsDirectory = statSync(home).isDirectory();
+    }
+    catch {
+        // reported below
+    }
+    if (!homeIsDirectory)
+        return corrupt(`${checked.home} is missing`);
+    return {
+        kind: "ok",
+        key,
+        packageName,
+        resolved: {
+            bin: binary,
+            home,
+            version: checked.swiplVersion,
+            source: "bundled",
+        },
+    };
+}
+function probeVersion(bin, deps) {
+    let output;
+    try {
+        output = deps.runVersion(bin);
+    }
+    catch (error) {
+        return {
+            kind: "unusable",
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const parsed = parseSwiplVersion(output);
+    if (parsed === undefined) {
+        return {
+            kind: "unusable",
+            detail: `unrecognized --version output ${JSON.stringify(output.trim().slice(0, 80))}`,
+        };
+    }
+    if (parsed.major < MINIMUM_SWIPL_MAJOR) {
+        return { kind: "too-old", version: parsed.version };
+    }
+    return { kind: "ok", version: parsed.version };
+}
+function findOnPath(env, deps) {
+    for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+        if (directory === "" || !path.isAbsolute(directory))
+            continue;
+        const candidate = path.join(directory, "swipl");
+        if (!isExecutableFile(candidate))
+            continue;
+        const probe = probeVersion(candidate, deps);
+        if (probe.kind === "ok") {
+            return {
+                kind: "ok",
+                resolved: { bin: candidate, version: probe.version, source: "path" },
+            };
+        }
+        return probe.kind === "too-old"
+            ? { kind: "too-old", bin: candidate, version: probe.version }
+            : { kind: "unusable", bin: candidate, detail: probe.detail };
+    }
+    return { kind: "absent" };
+}
+function resolveFromEnv(override, deps) {
+    const platform = hostLabel(deps);
+    const key = platformKey({
+        platform: deps.platform,
+        arch: deps.arch,
+        glibc: deps.glibc,
+    });
+    const packageName = key === undefined ? undefined : PLATFORM_PACKAGES[key].package;
+    const invalid = (detail) => new SwiplResolutionError("swipl_env_invalid", `KIBI_SWIPL=${override} ${detail}. Set KIBI_SWIPL to the absolute path of a SWI-Prolog ${MINIMUM_SWIPL_MAJOR}.0+ executable, to "system" to use swipl from PATH, or unset it to use the bundled runtime.`, platform, packageName);
+    if (!path.isAbsolute(override))
+        return fail(invalid("is not an absolute path"));
+    if (!isExecutableFile(override)) {
+        return fail(invalid("is not an executable file"));
+    }
+    const probe = probeVersion(override, deps);
+    if (probe.kind === "unusable") {
+        return fail(invalid(`could not report its version (${probe.detail})`));
+    }
+    if (probe.kind === "too-old") {
+        return fail(invalid(`is SWI-Prolog ${probe.version}, but ${MINIMUM_SWIPL_MAJOR}.0 or newer is required`));
+    }
+    return { bin: override, version: probe.version, source: "env" };
+}
+function fail(error) {
+    throw error;
+}
+function notFoundError(deps, bundle, lookup) {
+    const platform = hostLabel(deps);
+    const command = installCommand(deps.platform);
+    const lines = [
+        `Kibi could not find a usable SWI-Prolog (${MINIMUM_SWIPL_MAJOR}.0 or newer is required).`,
+        `Detected platform: ${platform}.`,
+    ];
+    let packageName;
+    if (bundle === "skipped") {
+        lines.push("Bundled SWI-Prolog: skipped because KIBI_SWIPL=system.");
+        const key = platformKey({
+            platform: deps.platform,
+            arch: deps.arch,
+            glibc: deps.glibc,
+        });
+        if (key !== undefined)
+            packageName = PLATFORM_PACKAGES[key].package;
+    }
+    else if (bundle.kind === "unsupported") {
+        lines.push(`Bundled SWI-Prolog: no bundled build exists for ${platform} (supported: ${Object.keys(PLATFORM_PACKAGES).join(", ")}).`);
+    }
+    else {
+        packageName = bundle.packageName;
+        if (bundle.kind === "empty") {
+            lines.push(`Bundled SWI-Prolog: package ${bundle.packageName} is installed but carries no runtime (a source checkout that was not populated from a release build).`);
+        }
+        else {
+            lines.push(`Bundled SWI-Prolog: package ${bundle.packageName} would cover this platform but is not installed. It is skipped by installs that omit optional dependencies (npm --omit=optional, --no-optional) and by pnpm supportedArchitectures settings that exclude this platform.`);
+            lines.push(`  Add it with: npm install --save-dev ${bundle.packageName}`);
+        }
+    }
+    if (bundle === "skipped" && packageName !== undefined) {
+        lines.push(`  To use it, unset KIBI_SWIPL and install ${packageName}.`);
+    }
+    switch (lookup.kind) {
+        case "absent":
+            lines.push("System SWI-Prolog: swipl was not found on PATH.");
+            break;
+        case "too-old":
+            lines.push(`System SWI-Prolog: swipl on PATH (${lookup.bin}) is version ${lookup.version}, older than ${MINIMUM_SWIPL_MAJOR}.0.`);
+            break;
+        case "unusable":
+            lines.push(`System SWI-Prolog: swipl on PATH (${lookup.bin}) could not report its version (${lookup.detail}).`);
+            break;
+        case "ok":
+            break;
+    }
+    lines.push(`  Install it with: ${command}`);
+    lines.push(`Or set KIBI_SWIPL to the absolute path of a SWI-Prolog ${MINIMUM_SWIPL_MAJOR}.0+ executable.`);
+    return new SwiplResolutionError("swipl_not_found", lines.join("\n"), platform, packageName);
+}
+/** Uncached resolution with injectable host facts; the test seam. */
+export function resolveSwiplWith(env, deps) {
+    const override = env.KIBI_SWIPL?.trim() ?? "";
+    if (override !== "" && override !== "system") {
+        return resolveFromEnv(override, deps);
+    }
+    let bundle = "skipped";
+    if (override === "") {
+        bundle = inspectBundle(deps);
+        if (bundle.kind === "ok")
+            return bundle.resolved;
+        if (bundle.kind === "corrupt") {
+            throw new SwiplResolutionError("swipl_bundle_corrupt", [
+                `The bundled SWI-Prolog package ${bundle.packageName} is damaged: ${bundle.reason}.`,
+                `Detected platform: ${hostLabel(deps)}.`,
+                `Reinstall it (for example: npm install --save-dev ${bundle.packageName}), or set KIBI_SWIPL=system to use swipl from PATH instead.`,
+            ].join("\n"), hostLabel(deps), bundle.packageName);
+        }
+    }
+    const lookup = findOnPath(env, deps);
+    if (lookup.kind === "ok")
+        return lookup.resolved;
+    throw notFoundError(deps, bundle, lookup);
+}
+const cache = new Map();
+/**
+ * Resolve the SWI-Prolog executable for this process. The result is cached for
+ * the lifetime of the process, keyed by the inputs that select it.
+ */
+export function resolveSwipl(env = process.env) {
+    const key = `${env.KIBI_SWIPL ?? ""}\0${env.PATH ?? ""}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const resolved = resolveSwiplWith(env, defaultDeps());
+    cache.set(key, resolved);
+    return resolved;
+}
+/** Test seam: forget every cached resolution. */
+export function resetSwiplResolverCache() {
+    cache.clear();
+}
+/** Stable identity of a resolved runtime, compared across engine processes. */
+export function swiplIdentity(resolved) {
+    return `${resolved.bin}@${resolved.version}`;
+}
+/** Environment additions a child needs to run the resolved SWI-Prolog. */
+export function swiplChildEnv(resolved) {
+    return resolved.home === undefined ? {} : { SWI_HOME_DIR: resolved.home };
+}
+/** Report the bundled package's state without resolving a runtime. */
+export function inspectSwiplBundle(deps = defaultDeps()) {
+    const bundle = inspectBundle(deps);
+    switch (bundle.kind) {
+        case "unsupported":
+            return { state: "unsupported" };
+        case "missing":
+        case "empty":
+            return { state: bundle.kind, packageName: bundle.packageName };
+        case "corrupt":
+            return {
+                state: "corrupt",
+                packageName: bundle.packageName,
+                reason: bundle.reason,
+            };
+        case "ok":
+            return { state: "installed", packageName: bundle.packageName };
+    }
+}
+/** Libraries Kibi loads at runtime; a SWI-Prolog lacking one cannot serve it. */
+export const REQUIRED_SWIPL_LIBRARIES = [
+    "semweb/rdf_db",
+    "semweb/rdf_persistency",
+    "semweb/sparql_client",
+    "pcre",
+    "crypto",
+    "sha",
+    "http/json",
+    "http/json_convert",
+    "chr",
+    "clpfd",
+    "thread",
+    "persistency",
+    "filesex",
+    "readutil",
+    "date",
+    "aggregate",
+    "solution_sequences",
+];
+const MISSING_LIBRARY_MARKER = "__KIBI_MISSING_LIBRARY__:";
+function defaultGoalRunner(bin, args, env) {
+    const result = spawnSync(bin, [...args], {
+        encoding: "utf8",
+        timeout: 60_000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env,
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        ...(result.error === undefined ? {} : { error: result.error }),
+    };
+}
+/**
+ * Load every required library in one throwaway SWI-Prolog process and report
+ * the ones that fail. A probe that cannot run is reported as such, never as a
+ * pass.
+ */
+export function probeRequiredLibraries(resolved, run = defaultGoalRunner, env = process.env) {
+    const goal = `forall(member(L, [${REQUIRED_SWIPL_LIBRARIES.join(", ")}]), (catch(use_module(library(L)), _, fail) -> true ; format("${MISSING_LIBRARY_MARKER}~w~n", [L])))`;
+    const result = run(resolved.bin, ["-q", "-g", goal, "-t", "halt"], {
+        ...env,
+        ...swiplChildEnv(resolved),
+    });
+    if (result.error !== undefined) {
+        return { kind: "failed", detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim().split("\n")[0] ?? "";
+        return {
+            kind: "failed",
+            detail: `exit status ${result.status ?? "none"}${detail === "" ? "" : `: ${detail}`}`,
+        };
+    }
+    const libraries = result.stdout
+        .split("\n")
+        .filter((line) => line.startsWith(MISSING_LIBRARY_MARKER))
+        .map((line) => line.slice(MISSING_LIBRARY_MARKER.length).trim());
+    return libraries.length === 0
+        ? { kind: "ok" }
+        : { kind: "missing", libraries };
+}

package/dist/prolog.d.ts

@@ -1,7 +1,14 @@
 import { type PrologErrorRecord } from "./prolog/error-terms.js";
+import { type ResolvedSwipl } from "./prolog/swipl-resolver.js";
 export declare function resolveKbPlPath(): string;
 export interface PrologOptions {
+    /**
+     * Explicit SWI-Prolog executable. When omitted, the executable comes from
+     * the resolver (KIBI_SWIPL, the bundled platform package, then PATH).
+     */
     swiplPath?: string;
+    /** Resolver seam for tests; defaults to the per-process SWI-Prolog resolver. */
+    swiplResolver?: () => ResolvedSwipl;
     timeout?: number;
     /**
      * Force one-shot SWI execution. Production callers are Node-only and keep
@@ -9,6 +16,23 @@ export interface PrologOptions {
      * repository tests that still run under Bun.
      */
     oneShot?: boolean;
+    /**
+     * Bounded stdout/stderr capacity per query. Defaults to 8 MiB; tests inject
+     * a small cap to exercise the overflow path deterministically.
+     */
+    maxOutputBytes?: number;
+}
+/**
+ * Raised when a query reaches an interactive process that was started and
+ * later terminated (output overflow, timeout, crash, or explicit terminate).
+ * Such a port must be restarted by its owner (the engine daemon recycles it);
+ * it never degrades into isolated one-shot SWI processes, which would lose
+ * the attached KB and every module loaded into the interactive session.
+ */
+export declare class PrologProcessTerminatedError extends Error {
+    readonly code = "prolog_process_terminated";
+    readonly reason: string;
+    constructor(reason: string);
 }
 export interface QueryResult {
     success: boolean;
@@ -20,7 +44,8 @@ export declare function registerProcessExitOnce(current: (() => void) | null, ha
 export declare function bindProcessExitHandler(current: (() => void) | null, terminate: () => void | Promise<void>, on?: (event: "exit", listener: () => void) => void): () => void;
 export declare class PrologProcess {
     private process;
-    private swiplPath;
+    private explicitSwiplPath;
+    private readonly swiplResolver;
     private timeout;
     private outputBuffer;
     private outputBufferBytes;
@@ -34,8 +59,32 @@ export declare class PrologProcess {
     private useOneShotMode;
     private attachedKbPath;
     private onProcessExit;
+    private readonly maxOutputBytes;
+    /**
+     * Set once start() spawned an interactive process. From then on the
+     * isolated one-shot fallback is unreachable: a lost interactive process
+     * must fail loudly instead of silently changing execution semantics.
+     */
+    private interactiveStarted;
+    private terminationReason;
     constructor(options?: PrologOptions);
     attachProcessExitHandler(on?: (event: "exit", listener: () => void) => void): void;
+    /**
+     * True when every query runs in its own isolated SWI process, so callers
+     * must not rely on state (loaded modules) carried between queries.
+     */
+    get oneShotMode(): boolean;
+    /**
+     * True once a started interactive process has been lost. The owner must
+     * restart it (and re-establish its session state) before querying again.
+     */
+    needsRestart(): boolean;
+    /**
+     * The executable and SWI home to launch. An explicit `swiplPath` is used
+     * verbatim; otherwise the per-process resolver decides, so a missing or
+     * damaged runtime fails with its complete remediation text.
+     */
+    private launchTarget;
     start(): Promise<void>;
     private waitForReady;
     query(goal: string | string[]): Promise<QueryResult>;
@@ -63,6 +112,7 @@ export declare class PrologProcess {
     private translateError;
     isRunning(): boolean;
     getPid(): number;
+    private lostProcessError;
     terminate(): Promise<void>;
 }
 //# sourceMappingURL=prolog.d.ts.map

package/dist/prolog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"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"}