/**
 * Daemon-singleton acquire-or-spawn for the loop-engine UDS daemon.
 *
 * One engine process per host. All opensquid hooks + sessions share
 * the same engine over a Unix domain socket at
 * `~/.opensquid/loop-engine.sock`. This is the keystone for cross-
 * session memory recall — session A writes a memory, session B reads
 * it through the same engine without per-process spawn cost.
 *
 * Flow (per spec T.4 / audit T.1.Y + T.1.Z + T.1.BB + T.1.DD):
 *
 *  1. Windows guard — UDS is Unix-only; named-pipe support is a
 *     follow-up. Windows callers fall back to per-process stdio spawn
 *     by setting `OPENSQUID_ENGINE_SOCKET=disable` upstream.
 *
 *  2. Path-byte guard — macOS limits UDS paths to 104 bytes (Linux
 *     108). `~/.opensquid/loop-engine.sock` ≈ 30 chars on typical
 *     homes, but exotic `$HOME` values can exceed it. Refuse at 100
 *     to leave margin.
 *
 *  3. Fast path — if the socket file exists, try to connect. Success
 *     means an engine is already running; return the socket with
 *     `spawnedByUs: false`. ECONNREFUSED means the file is stale (a
 *     previous engine crashed without unlinking); unlink and fall
 *     through to the spawn path.
 *
 *  4. Slow path (lock + spawn):
 *     a. Touch `~/.opensquid/loop-engine.lock` so `proper-lockfile`
 *        has a stable inode to lock against.
 *     b. Acquire the lock with retry — serializes concurrent spawn
 *        attempts across multiple opensquid processes.
 *     c. RECHECK after the lock: another process may have spawned
 *        the engine while we waited. If yes, connect + return.
 *     d. Resolve the engine binary via existing `resolveEngineBin()`.
 *     e. Spawn detached + `stdio: 'ignore'` so the engine outlives
 *        the parent (true daemon semantics). `'inherit'` would hold
 *        the parent's stdout/stderr pipes open and block parent exit
 *        (per subprocess-lifecycle audit). Engine logs route to
 *        /dev/null in this mode; `RUST_LOG=...` + a redirect-to-file
 *        is the workaround if diagnostics are needed.
 *     f. Write `~/.opensquid/loop-engine.pid` with the spawned pid
 *        BEFORE `proc.unref()` so T.7's `engine kill` command can
 *        find it.
 *     g. `proc.unref()` — let the parent event loop exit without
 *        waiting on the engine.
 *     h. Wait for the socket file to appear (engine binds before
 *        accept; 10s budget covers cold-start HNSW rehydrate of
 *        ~76 memories on typical hardware).
 *     i. Connect; return with `spawnedByUs: true`.
 *
 *  5. Always release the lock in a `finally` block.
 *
 * NOT a singleton class — exported as a plain async function so
 * callers can compose / inject without instance state. Concurrency
 * safety lives in `proper-lockfile`, not in this module.
 */
import { type Socket } from 'node:net';
/** Engine socket path. Override `OPENSQUID_HOME` to relocate. */
export declare function engineSocketPath(): string;
/** Lock file used to serialize concurrent spawn attempts. */
export declare function engineLockPath(): string;
/**
 * Pidfile path used by `engine kill` (T.7). Written after spawn
 * returns, before `unref()`. Note: the engine process itself does
 * NOT manage this file — opensquid owns its lifecycle since opensquid
 * is the one that spawned the engine. T.7 will add a startup-time
 * cleanup hook for the spawned-by-us case.
 */
export declare function enginePidPath(): string;
export interface EngineConnection {
    /** Connected socket to the engine's UDS endpoint. */
    socket: Socket;
    /**
     * `true` when this caller's invocation was the one that spawned the
     * engine process (cold start path). `false` when an existing engine
     * was found and connected to (warm path). Useful for telemetry +
     * test assertions; production callers usually ignore it.
     */
    spawnedByUs: boolean;
}
/**
 * Acquire a connection to the shared loop-engine daemon, spawning
 * one if none is running. Safe to call concurrently from multiple
 * processes — `proper-lockfile` serializes spawn attempts so only
 * one engine starts per `~/.opensquid/loop-engine.sock` lifetime.
 *
 * Throws on:
 *  - Windows (UDS unsupported; use stdio mode upstream)
 *  - socket path exceeds platform byte limit
 *  - engine binary not resolvable
 *  - socket never appears within `SOCKET_WAIT_TIMEOUT_MS`
 *  - underlying spawn / connect / lock errors
 */
export declare function acquireOrSpawnEngine(): Promise<EngineConnection>;
//# sourceMappingURL=singleton.d.ts.map