appduct 0.9.0

package/dist/daemon/log-rotation.js

@@ -0,0 +1,136 @@
+/**
+ * `daemon.log` rotation (ARCHITECTURE.md §3/§4, issue #32). The daemon's stdout/stderr is appended
+ * to `daemon.log` for the whole life of the process, so nothing inside a running daemon can safely
+ * truncate it — the only safe moment is just before a *new* daemon is spawned, while no writer
+ * holds the file open. {@link rotateDaemonLogIfNeeded} is therefore called from the spawn path
+ * (`rpc/client.ts`'s `defaultSpawn`, which is also what `appduct daemon start` spawns through),
+ * never from the daemon itself.
+ *
+ * "Nothing answered the socket" is not by itself proof that nothing is writing the log: a daemon
+ * that is still booting, wedged, or mid-shutdown holds its log fd while its socket is unreachable,
+ * and the spawn lock is released as soon as the child is spawned rather than when it is ready. A
+ * rename under such a process would send its output to `daemon.log.1`, and the *next* rotation
+ * would then unlink the inode it is still writing to — output lost, with nothing on disk to show
+ * for it. So rotation asks twice, as late as it can, and declines on either answer:
+ *
+ * - the pidfile must not name a live process (the same probe the pidfile takeover and the
+ *   stale-socket unlink use); and
+ * - `daemon.sock` must not accept a connection, re-checked immediately before the rename.
+ *
+ * **This narrows the window; it does not close it.** A daemon spawned microseconds ago holds its
+ * log fd before it has written `daemon.pid` or bound its socket, and no check performed before the
+ * rename can see it — the file it is writing to is simply not distinguishable, from the outside,
+ * from one nobody holds. What is left is a race measured in the milliseconds between a child being
+ * spawned and it writing its pidfile, entered only by a *second* spawner that also finds the log
+ * over its cap. The consequence is bounded (that daemon's output continues into `daemon.log.1`,
+ * and is lost if a later rotation replaces that backup), and a just-spawned daemon's log is far
+ * below any sane cap, so in practice the second spawner does not rotate at all. Closing it
+ * properly needs an advisory lock held across spawn-and-ready rather than released at spawn.
+ *
+ * One backup is enough (`daemon.log.1`): the point is a bounded footprint, not a full history. A
+ * rotation failure is warned and swallowed — a daemon that cannot rotate its log must still start.
+ */
+import { chmod, rename, stat } from "node:fs/promises";
+import { DEFAULT_DAEMON_LOG_MAX_BYTES, loadConfig } from "./config.js";
+import { isProcessAlive, readPidFromFile } from "./pidfile.js";
+import { isSocketConnectable } from "./socket-probe.js";
+import { getStateDirPaths } from "./state-dir.js";
+/** Mode every file under the state dir is held at (ARCHITECTURE.md §3). */
+const STATE_FILE_MODE = 0o600;
+export const daemonLogBackupPath = (logFilePath) => `${logFilePath}.1`;
+/** True when `pidFilePath` names a process that is still around. A missing/garbage pidfile, or an
+ * unreadable one, reads as "nothing is running" — the same conclusion the pidfile takeover and the
+ * stale-socket unlink draw from it. */
+const isDaemonHoldingLog = async (pidFilePath) => {
+    try {
+        const pid = await readPidFromFile(pidFilePath);
+        return pid !== undefined && isProcessAlive(pid);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Moves `daemon.log` to `daemon.log.1` when it exceeds `maxBytes`, replacing any previous backup.
+ * A missing log, a log within the cap, a log a live daemon still holds, or any failure is a no-op
+ * — never throws.
+ */
+export const rotateDaemonLogIfNeeded = async (options) => {
+    const warn = options.warn ??
+        ((message) => {
+            process.stderr.write(`${message}\n`);
+        });
+    try {
+        const stats = await stat(options.logFilePath);
+        if (!stats.isFile() || stats.size <= options.maxBytes) {
+            return { rotated: false };
+        }
+        // Both checks run only once rotation is actually on the table, so the overwhelmingly common
+        // within-cap spawn stays two syscalls — and as late as possible, to keep the window in which
+        // a daemon can appear between the check and the rename as small as it can be made.
+        const held = (options.pidFilePath !== undefined && (await isDaemonHoldingLog(options.pidFilePath))) ||
+            (options.socketPath !== undefined && (await isSocketConnectable(options.socketPath)));
+        if (held) {
+            warn(`appduct: "${options.logFilePath}" is over its size cap but a daemon still holds it; leaving it in place.`);
+            return { rotated: false, skipped: "daemon_running" };
+        }
+        const backupPath = daemonLogBackupPath(options.logFilePath);
+        // `rename` is atomic within the state dir, so a concurrent spawner either sees the old log or
+        // the rotated one — never a half-copied file.
+        await rename(options.logFilePath, backupPath);
+        // Deliberately its own try/catch, *after* the rename has already succeeded. `rename` preserves
+        // the log's mode, so this only ever repairs a backup that predates this code (or an operator's
+        // `cp`) — and a filesystem that refuses the chmod must not make a completed rotation report
+        // itself as "not rotated" under a warning naming the wrong step.
+        try {
+            await chmod(backupPath, STATE_FILE_MODE);
+        }
+        catch (error) {
+            warn(`appduct: rotated "${options.logFilePath}" but could not set 0600 on "${backupPath}": ${error.message}`);
+        }
+        return { rotated: true, rotatedBytes: stats.size };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { rotated: false };
+        }
+        warn(`appduct: failed to rotate "${options.logFilePath}": ${error.message}`);
+        return { rotated: false };
+    }
+};
+/**
+ * Best-effort enforcement of `daemon.log`'s ARCHITECTURE.md §3 mode. `open(path, "a", 0o600)`
+ * already creates it at `0600` (the umask can only remove bits), so this exists for the file that
+ * was *not* created by us — an operator's `touch`, a `cp` from elsewhere — and is a no-op
+ * otherwise.
+ *
+ * Never throws. It sits directly on the auto-spawn path, where every CLI and MCP command that
+ * needs a daemon passes through: a filesystem that answers `chmod` with EPERM or ENOTSUP (a
+ * drvfs/NFS/SMB-backed state dir, a root-owned log under a non-root user) would otherwise brick
+ * every one of those commands over a permission bit. A daemon that cannot tighten its log mode
+ * must still start — loudly, but it must start.
+ */
+export const ensureDaemonLogMode = async (logFilePath, warn = (message) => process.stderr.write(`${message}\n`)) => {
+    try {
+        await chmod(logFilePath, STATE_FILE_MODE);
+        return true;
+    }
+    catch (error) {
+        warn(`appduct: could not set 0600 on "${logFilePath}": ${error.message}`);
+        return false;
+    }
+};
+/**
+ * `config.daemonLogMaxBytes` for a state dir, falling back to the default when `config.json` is
+ * missing or unreadable. Deliberately forgiving: this runs on the spawn path, where a bad config
+ * is the daemon's problem to report properly once it starts — not a reason to fail rotation (and
+ * with it the spawn) with a duplicate error.
+ */
+export const resolveDaemonLogMaxBytes = async (stateDir) => {
+    try {
+        return (await loadConfig(getStateDirPaths(stateDir))).daemonLogMaxBytes;
+    }
+    catch {
+        return DEFAULT_DAEMON_LOG_MAX_BYTES;
+    }
+};

package/dist/daemon/pidfile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pidfile single-instancing (ARCHITECTURE.md §4). Acquired with `O_EXCL`; on conflict, liveness
+ * is checked with `process.kill(pid, 0)` and the pidfile is only taken over if the owning
+ * process is dead.
+ */
+export declare class DaemonAlreadyRunningError extends Error {
+    readonly pid: number;
+    constructor(pid: number);
+}
+export type PidfileHandle = {
+    readonly pid: number;
+    /** Idempotent: safe to call more than once. */
+    release: () => Promise<void>;
+};
+/**
+ * Liveness probe for a pid this process does not own (ARCHITECTURE.md §4's `process.kill(pid, 0)`
+ * check). Exported because every "is a daemon still there?" decision in the codebase must answer
+ * it the same way — pidfile takeover, the auto-spawn path's stale-socket unlink, and log rotation
+ * all hinge on it, and a second implementation that disagreed about `EPERM` would mean one of
+ * them quietly clobbering a live daemon's state.
+ */
+export declare const isProcessAlive: (pid: number) => boolean;
+export declare const readPidFromFile: (pidFilePath: string) => Promise<number | undefined>;
+export type AcquirePidfileOptions = {
+    pid?: number;
+    /**
+     * Invoked once, after a stale (dead-owner) pidfile is detected and removed, before the pidfile
+     * is re-acquired. Lets the caller clean up other stale state (e.g. `daemon.sock`) tied to the
+     * dead process.
+     */
+    onStaleTakeover?: () => Promise<void>;
+};
+/**
+ * Acquires the daemon pidfile, taking over a stale one (owner process is dead or the file is
+ * unparseable) but throwing {@link DaemonAlreadyRunningError} when a live daemon holds it.
+ */
+export declare const acquirePidfile: (pidFilePath: string, options?: AcquirePidfileOptions) => Promise<PidfileHandle>;
+//# sourceMappingURL=pidfile.d.ts.map

package/dist/daemon/pidfile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pidfile.d.ts","sourceRoot":"","sources":["../../src/daemon/pidfile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,qBAAa,yBAA0B,SAAQ,KAAK;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CAIjC;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,OAQ5C,CAAC;AAEF,eAAO,MAAM,eAAe,GAAU,aAAa,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAgBrF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,aAAa,MAAM,EACnB,UAAS,qBAA0B,KAClC,OAAO,CAAC,aAAa,CA+CvB,CAAC"}

package/dist/daemon/pidfile.js

@@ -0,0 +1,90 @@
+/**
+ * Pidfile single-instancing (ARCHITECTURE.md §4). Acquired with `O_EXCL`; on conflict, liveness
+ * is checked with `process.kill(pid, 0)` and the pidfile is only taken over if the owning
+ * process is dead.
+ */
+import { open, readFile, rm } from "node:fs/promises";
+export class DaemonAlreadyRunningError extends Error {
+    pid;
+    constructor(pid) {
+        super(`Appduct daemon is already running (pid ${pid}).`);
+        this.pid = pid;
+        this.name = "DaemonAlreadyRunningError";
+    }
+}
+/**
+ * Liveness probe for a pid this process does not own (ARCHITECTURE.md §4's `process.kill(pid, 0)`
+ * check). Exported because every "is a daemon still there?" decision in the codebase must answer
+ * it the same way — pidfile takeover, the auto-spawn path's stale-socket unlink, and log rotation
+ * all hinge on it, and a second implementation that disagreed about `EPERM` would mean one of
+ * them quietly clobbering a live daemon's state.
+ */
+export const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but we lack permission to signal it — still alive.
+        return error.code === "EPERM";
+    }
+};
+export const readPidFromFile = async (pidFilePath) => {
+    let contents;
+    try {
+        contents = await readFile(pidFilePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    const pid = Number.parseInt(contents.trim(), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+};
+/**
+ * Acquires the daemon pidfile, taking over a stale one (owner process is dead or the file is
+ * unparseable) but throwing {@link DaemonAlreadyRunningError} when a live daemon holds it.
+ */
+export const acquirePidfile = async (pidFilePath, options = {}) => {
+    const pid = options.pid ?? process.pid;
+    // Bounded retry: another process could win the takeover race between our stale-check and our
+    // write attempt. A handful of retries is enough to make forward progress deterministic in tests
+    // without looping forever on a persistently-contended pidfile.
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+        try {
+            const handle = await open(pidFilePath, "wx", 0o600);
+            try {
+                await handle.writeFile(String(pid), "utf8");
+            }
+            finally {
+                await handle.close();
+            }
+            let released = false;
+            return {
+                pid,
+                release: async () => {
+                    if (released) {
+                        return;
+                    }
+                    released = true;
+                    await rm(pidFilePath, { force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            const existingPid = await readPidFromFile(pidFilePath);
+            if (existingPid !== undefined && isProcessAlive(existingPid)) {
+                throw new DaemonAlreadyRunningError(existingPid);
+            }
+            // Stale pidfile (dead owner, or unparseable contents): remove and retry.
+            await rm(pidFilePath, { force: true });
+            await options.onStaleTakeover?.();
+        }
+    }
+    throw new Error(`Failed to acquire the Appduct daemon pidfile at "${pidFilePath}".`);
+};

package/dist/daemon/policy.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tool-call policy evaluation (ARCHITECTURE.md §12). Every `tools.call` — CLI and MCP alike —
+ * passes through {@link evaluate} before the daemon sends anything to the app. Precedence:
+ *
+ * 1. a per-tool override, `policy.tools["<alias>/<name>"]`, wins outright;
+ * 2. else `policy.destructive` applies to tools whose descriptor sets
+ *    `annotations.destructiveHint === true`;
+ * 3. else `policy.default`.
+ *
+ * This module is pure and synchronous — it knows nothing about sockets, audit, or the RPC layer;
+ * the daemon composition root (`daemon.ts`) is the single seam that calls it and reacts to the
+ * decision (deny → `policy_denied`, no frame to the app, per ARCHITECTURE.md §5/§12).
+ */
+import type { ToolDescriptor } from "@appduct/shared";
+import type { AppductPolicyConfig, PolicyDecision } from "./config.js";
+/** The pieces of a resolved session {@link evaluate} needs to key a per-tool override. */
+export type PolicySession = {
+    alias: string;
+};
+export declare const policyOverrideKey: (alias: string, toolName: string) => string;
+export declare const evaluate: (descriptor: ToolDescriptor, session: PolicySession, policy: AppductPolicyConfig) => PolicyDecision;
+//# sourceMappingURL=policy.d.ts.map

package/dist/daemon/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/daemon/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE,0FAA0F;AAC1F,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAAgC,CAAC;AAErG,eAAO,MAAM,QAAQ,GACnB,YAAY,cAAc,EAC1B,SAAS,aAAa,EACtB,QAAQ,mBAAmB,KAC1B,cAYF,CAAC"}

package/dist/daemon/policy.js

@@ -0,0 +1,24 @@
+/**
+ * Tool-call policy evaluation (ARCHITECTURE.md §12). Every `tools.call` — CLI and MCP alike —
+ * passes through {@link evaluate} before the daemon sends anything to the app. Precedence:
+ *
+ * 1. a per-tool override, `policy.tools["<alias>/<name>"]`, wins outright;
+ * 2. else `policy.destructive` applies to tools whose descriptor sets
+ *    `annotations.destructiveHint === true`;
+ * 3. else `policy.default`.
+ *
+ * This module is pure and synchronous — it knows nothing about sockets, audit, or the RPC layer;
+ * the daemon composition root (`daemon.ts`) is the single seam that calls it and reacts to the
+ * decision (deny → `policy_denied`, no frame to the app, per ARCHITECTURE.md §5/§12).
+ */
+export const policyOverrideKey = (alias, toolName) => `${alias}/${toolName}`;
+export const evaluate = (descriptor, session, policy) => {
+    const override = policy.tools?.[policyOverrideKey(session.alias, descriptor.name)];
+    if (override !== undefined) {
+        return override;
+    }
+    if (descriptor.annotations?.destructiveHint === true) {
+        return policy.destructive;
+    }
+    return policy.default;
+};

package/dist/daemon/registry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-session tool registry (ARCHITECTURE.md §7). Callers (sessions.ts/listener.ts) must validate
+ * incoming `tool_registry_snapshot`/`tool_registry_delta` wire messages with the shared guards
+ * *before* calling into this module — v1 crashed by indexing into an unvalidated `tools: [null]`
+ * snapshot; this module only ever stores already-validated {@link ToolDescriptor}s.
+ */
+import type { ToolDescriptor } from "@appduct/shared";
+export type ToolRegistry = {
+    /** Authoritative replace: used for the initial snapshot and every post-resume re-sync. */
+    snapshot: (tools: ToolDescriptor[]) => void;
+    upsert: (tool: ToolDescriptor) => void;
+    remove: (name: string) => void;
+    list: () => ToolDescriptor[];
+    get: (name: string) => ToolDescriptor | undefined;
+    count: () => number;
+};
+/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`. */
+export declare const createToolRegistry: (onChange?: () => void) => ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/daemon/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/daemon/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,MAAM,YAAY,GAAG;IACzB,0FAA0F;IAC1F,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACvC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,cAAc,EAAE,CAAC;IAC7B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IAClD,KAAK,EAAE,MAAM,MAAM,CAAC;CACrB,CAAC;AAEF,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,IAAI,KAAG,YAyB1D,CAAC"}

package/dist/daemon/registry.js

@@ -0,0 +1,31 @@
+/**
+ * Per-session tool registry (ARCHITECTURE.md §7). Callers (sessions.ts/listener.ts) must validate
+ * incoming `tool_registry_snapshot`/`tool_registry_delta` wire messages with the shared guards
+ * *before* calling into this module — v1 crashed by indexing into an unvalidated `tools: [null]`
+ * snapshot; this module only ever stores already-validated {@link ToolDescriptor}s.
+ */
+/** `onChange` fires after every mutation (snapshot/upsert/remove) — used to emit `tools_changed`. */
+export const createToolRegistry = (onChange) => {
+    let tools = new Map();
+    const notify = () => {
+        onChange?.();
+    };
+    return {
+        snapshot: (incoming) => {
+            tools = new Map(incoming.map((tool) => [tool.name, tool]));
+            notify();
+        },
+        upsert: (tool) => {
+            tools.set(tool.name, tool);
+            notify();
+        },
+        remove: (name) => {
+            if (tools.delete(name)) {
+                notify();
+            }
+        },
+        list: () => Array.from(tools.values()),
+        get: (name) => tools.get(name),
+        count: () => tools.size,
+    };
+};

package/dist/daemon/rpc-server.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The control-plane UDS JSON-RPC server (ARCHITECTURE.md §5). Framing: one JSON-RPC 2.0 message
+ * per line (`\n`-delimited). Server→client notifications use method `"event"` and are pushed via
+ * {@link notify} on a targeted connection — this module only exposes the primitive.
+ */
+import { type Server, type Socket } from "node:net";
+import type { ErrorType } from "@appduct/shared";
+/** 1 MiB — lines beyond this are dropped by destroying the connection (ARCHITECTURE.md task notes). */
+export declare const MAX_LINE_BYTES: number;
+/** 4 MiB — a subscriber connection (`events.subscribe`) whose outbound buffer grows past this
+ * (slow/dead reader) is dropped outright rather than left to back up the daemon indefinitely. */
+export declare const MAX_NOTIFY_BUFFERED_BYTES: number;
+export declare class RpcApplicationError extends Error {
+    readonly type: ErrorType;
+    /** JSON-RPC error code; defaults to the shared "server error" range. */
+    readonly code: number;
+    readonly details?: unknown | undefined;
+    constructor(type: ErrorType, message: string, 
+    /** JSON-RPC error code; defaults to the shared "server error" range. */
+    code?: number, details?: unknown | undefined);
+}
+export type RpcConnection = {
+    readonly id: number;
+    readonly socket: Socket;
+    /** Extensibility bag for future wiring (e.g. `events.subscribe` state). */
+    readonly state: Record<string, unknown>;
+};
+export type RpcHandlerContext = {
+    connection: RpcConnection;
+    /** Registers a callback to run once the in-flight response has been flushed to the socket. */
+    afterSend: (callback: () => void) => void;
+    /** Registers a callback to run once this connection closes — e.g. auto-cancelling a `tools.call`
+     * still in flight when the connection that issued it drops. Callbacks run at most once. Returns
+     * an unregister function — callers whose call already settled must use it, or the callback (and
+     * whatever it closed over) leaks for the lifetime of a long-lived connection (e.g. the MCP
+     * server's persistent stream, which issues many `tools.call`s over one connection). */
+    onClose: (callback: () => void) => () => void;
+};
+export type RpcHandler = (params: unknown, context: RpcHandlerContext) => unknown | Promise<unknown>;
+export type RpcDispatchTable = Record<string, RpcHandler>;
+export type RpcServerOptions = {
+    socketPath: string;
+    dispatch: RpcDispatchTable;
+    maxLineBytes?: number;
+};
+export type RpcServer = {
+    server: Server;
+    /** Pushes a server→client `"event"` notification (no `id`) on the given connection. */
+    notify: (connection: RpcConnection, payload: unknown) => void;
+    connections: () => RpcConnection[];
+    close: () => Promise<void>;
+};
+export declare const startRpcServer: (options: RpcServerOptions) => Promise<RpcServer>;
+//# sourceMappingURL=rpc-server.d.ts.map

package/dist/daemon/rpc-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-server.d.ts","sourceRoot":"","sources":["../../src/daemon/rpc-server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,uGAAuG;AACvG,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C;iGACiG;AACjG,eAAO,MAAM,yBAAyB,QAAkB,CAAC;AAEzD,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,IAAI,EAAE,SAAS;IAExB,wEAAwE;IACxE,QAAQ,CAAC,IAAI;IACb,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO;gBAJjB,IAAI,EAAE,SAAS,EACxB,OAAO,EAAE,MAAM;IACf,wEAAwE;IAC/D,IAAI,SAAS,EACb,OAAO,CAAC,EAAE,OAAO,YAAA;CAK7B;AAED,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,EAAE,aAAa,CAAC;IAC1B,8FAA8F;IAC9F,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC1C;;;;2FAIuF;IACvF,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErG,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AA2C1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,MAAM,EAAE,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9D,WAAW,EAAE,MAAM,aAAa,EAAE,CAAC;IACnC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAsEF,eAAO,MAAM,cAAc,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,SAAS,CAiIjF,CAAC"}

package/dist/daemon/rpc-server.js

@@ -0,0 +1,203 @@
+/**
+ * The control-plane UDS JSON-RPC server (ARCHITECTURE.md §5). Framing: one JSON-RPC 2.0 message
+ * per line (`\n`-delimited). Server→client notifications use method `"event"` and are pushed via
+ * {@link notify} on a targeted connection — this module only exposes the primitive.
+ */
+import { createServer } from "node:net";
+import { chmod, rm } from "node:fs/promises";
+/** 1 MiB — lines beyond this are dropped by destroying the connection (ARCHITECTURE.md task notes). */
+export const MAX_LINE_BYTES = 1024 * 1024;
+/** 4 MiB — a subscriber connection (`events.subscribe`) whose outbound buffer grows past this
+ * (slow/dead reader) is dropped outright rather than left to back up the daemon indefinitely. */
+export const MAX_NOTIFY_BUFFERED_BYTES = 4 * 1024 * 1024;
+export class RpcApplicationError extends Error {
+    type;
+    code;
+    details;
+    constructor(type, message, 
+    /** JSON-RPC error code; defaults to the shared "server error" range. */
+    code = -32000, details) {
+        super(message);
+        this.type = type;
+        this.code = code;
+        this.details = details;
+        this.name = "RpcApplicationError";
+    }
+}
+const isPlainObject = (value) => {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+const hasRequestId = (value) => {
+    return "id" in value;
+};
+const writeErrorLine = (socket, id, code, message, data) => {
+    writeLine(socket, {
+        jsonrpc: "2.0",
+        id,
+        error: { code, message, ...(data ? { data } : {}) },
+    });
+};
+const writeLine = (socket, payload, onFlushed) => {
+    if (socket.destroyed) {
+        return;
+    }
+    socket.write(`${JSON.stringify(payload)}\n`, (error) => {
+        if (!error) {
+            onFlushed?.();
+        }
+    });
+};
+const handleLine = async (line, connection, dispatch, registerOnClose) => {
+    const { socket } = connection;
+    let request;
+    try {
+        const parsed = JSON.parse(line);
+        if (!isPlainObject(parsed)) {
+            writeErrorLine(socket, null, -32600, "Invalid Request: expected a JSON object.");
+            return;
+        }
+        request = parsed;
+    }
+    catch {
+        writeErrorLine(socket, null, -32700, "Parse error: invalid JSON.");
+        return;
+    }
+    const id = hasRequestId(request) ? request.id : null;
+    if (typeof request.method !== "string" || request.method.length === 0) {
+        writeErrorLine(socket, id, -32600, 'Invalid Request: "method" must be a non-empty string.');
+        return;
+    }
+    const handler = dispatch[request.method];
+    if (!handler) {
+        writeErrorLine(socket, id, -32601, `Method not found: "${request.method}".`);
+        return;
+    }
+    const afterSendCallbacks = [];
+    const context = {
+        connection,
+        afterSend: (callback) => {
+            afterSendCallbacks.push(callback);
+        },
+        onClose: registerOnClose,
+    };
+    try {
+        const result = await handler(request.params, context);
+        writeLine(socket, { jsonrpc: "2.0", id, result: result ?? null }, () => {
+            for (const callback of afterSendCallbacks) {
+                callback();
+            }
+        });
+    }
+    catch (error) {
+        if (error instanceof RpcApplicationError) {
+            writeErrorLine(socket, id, error.code, error.message, {
+                type: error.type,
+                ...(error.details !== undefined ? { details: error.details } : {}),
+            });
+            return;
+        }
+        const message = error instanceof Error ? error.message : "Internal error.";
+        writeErrorLine(socket, id, -32603, message, { type: "invalid_request" });
+    }
+};
+export const startRpcServer = async (options) => {
+    const maxLineBytes = options.maxLineBytes ?? MAX_LINE_BYTES;
+    const connections = new Map();
+    let nextConnectionId = 1;
+    await rm(options.socketPath, { force: true });
+    const server = createServer((socket) => {
+        socket.on("error", () => {
+            // A dropped/reset client connection must never crash the daemon.
+        });
+        const id = nextConnectionId;
+        nextConnectionId += 1;
+        const connection = { id, socket, state: {} };
+        connections.set(id, connection);
+        const closeCallbacks = new Set();
+        const registerOnClose = (callback) => {
+            closeCallbacks.add(callback);
+            return () => {
+                closeCallbacks.delete(callback);
+            };
+        };
+        let buffer = "";
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            if (Buffer.byteLength(buffer, "utf8") > maxLineBytes && !buffer.includes("\n")) {
+                socket.destroy();
+                return;
+            }
+            let newlineIndex = buffer.indexOf("\n");
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex).replace(/\r$/u, "");
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line.length > 0) {
+                    if (Buffer.byteLength(line, "utf8") > maxLineBytes) {
+                        // ARCHITECTURE.md task notes: cap line length at 1 MiB, dropping the connection beyond.
+                        writeErrorLine(socket, null, -32600, `Invalid Request: line exceeds the ${maxLineBytes}-byte limit.`);
+                        socket.destroy();
+                        return;
+                    }
+                    void handleLine(line, connection, options.dispatch, registerOnClose);
+                }
+                newlineIndex = buffer.indexOf("\n");
+            }
+        });
+        socket.on("close", () => {
+            connections.delete(id);
+            const callbacks = Array.from(closeCallbacks);
+            closeCallbacks.clear();
+            for (const callback of callbacks) {
+                try {
+                    callback();
+                }
+                catch {
+                    // A close callback must never crash the daemon.
+                }
+            }
+        });
+    });
+    server.on("error", () => {
+        // Never let a listener-level error (e.g. EMFILE after startup) crash the process. Startup
+        // failures are additionally surfaced via the one-shot listener below, which rejects `listen()`.
+        // Surfacing post-startup errors would require a caller-supplied sink; the daemon composition
+        // root owns observability wiring in a later task.
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(options.socketPath);
+    });
+    await chmod(options.socketPath, 0o600);
+    return {
+        server,
+        notify: (connection, payload) => {
+            if (connection.socket.destroyed) {
+                return;
+            }
+            // Backpressure guard: a slow/dead subscriber must never block the daemon or other
+            // connections. `writableLength` reflects bytes already queued but not yet flushed to the
+            // kernel; once it crosses the cap the connection is beyond saving and gets dropped.
+            if (connection.socket.writableLength > MAX_NOTIFY_BUFFERED_BYTES) {
+                connection.socket.destroy();
+                return;
+            }
+            writeLine(connection.socket, { jsonrpc: "2.0", method: "event", params: payload });
+        },
+        connections: () => Array.from(connections.values()),
+        close: () => new Promise((resolve) => {
+            for (const connection of connections.values()) {
+                connection.socket.destroy();
+            }
+            server.close(() => resolve());
+        }),
+    };
+};