@lightpath-dev/daemon 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @lightpath-dev/daemon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The local daemon of [Lightpath](https://github.com/Unknown-333/Lightpath#readme). It receives coverage from the browser and backend agents, builds one trace per action, and serves traces to the editor and MCP clients. It listens on `127.0.0.1` only and requires a token.
+
+You don't need this package directly; [`@lightpath-dev/cli`](https://www.npmjs.com/package/@lightpath-dev/cli) starts it.

package/dist/auth.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingMessage } from 'node:http';
+/** 32 random bytes, base64url-encoded (43 characters). */
+export declare function newToken(): string;
+export declare function tokensEqual(expected: string, actual: string | undefined | null): boolean;
+/**
+ * Checks a request against the daemon's rules (ARCHITECTURE section 7.2):
+ * - no `Origin` header, so web pages in the user's browser can't talk to the daemon;
+ * - the token in `Authorization: Bearer <token>` or, for WebSocket upgrades, `?token=`.
+ */
+export declare function authorize(req: IncomingMessage, token: string): 'ok' | 'forbidden' | 'unauthorized';
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/** 32 random bytes, base64url-encoded (43 characters). */
+export function newToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function tokensEqual(expected, actual) {
+    if (!actual)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(actual);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Checks a request against the daemon's rules (ARCHITECTURE section 7.2):
+ * - no `Origin` header, so web pages in the user's browser can't talk to the daemon;
+ * - the token in `Authorization: Bearer <token>` or, for WebSocket upgrades, `?token=`.
+ */
+export function authorize(req, token) {
+    if (req.headers.origin !== undefined)
+        return 'forbidden';
+    const auth = req.headers.authorization;
+    const bearer = auth?.startsWith('Bearer ') ? auth.slice('Bearer '.length) : undefined;
+    const query = new URL(req.url ?? '/', 'http://localhost').searchParams.get('token');
+    return tokensEqual(token, bearer ?? query) ? 'ok' : 'unauthorized';
+}
+//# sourceMappingURL=auth.js.map

package/dist/correlator.d.ts

@@ -0,0 +1,16 @@
+import { type ResolveContext } from '@lightpath-dev/core';
+import type { IngestMessage } from '@lightpath-dev/protocol';
+import type { Store } from './store.js';
+/**
+ * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).
+ * Pure in-memory logic with no I/O, so it's tested without sockets.
+ */
+export declare class Correlator {
+    #private;
+    constructor(store: Store, ctx: ResolveContext);
+    /** Maps URLs served by a dev server (e.g. Vite at http://localhost:5173) onto a directory. */
+    addDevServer(origin: string, root: string): void;
+    get sourceCount(): number;
+    ingest(agentId: string, message: IngestMessage): void;
+}
+//# sourceMappingURL=correlator.d.ts.map

package/dist/correlator.js

@@ -0,0 +1,247 @@
+import { decodeDataUrlSourceMap, mapScript, mergeLineCounts, newTraceId, PeriodicFunctions, resolveFile, } from '@lightpath-dev/core';
+/**
+ * Turns ingest messages into mapped traces (docs/ARCHITECTURE.md sections 3, 4, and 6).
+ * Pure in-memory logic with no I/O, so it's tested without sockets.
+ */
+export class Correlator {
+    #agents = new Map();
+    /** Sources are cached by script hash, shared across agents (ADR 0006). */
+    #sources = new Map();
+    #pending = new Map();
+    #store;
+    #ctx;
+    constructor(store, ctx) {
+        this.#store = store;
+        this.#ctx = ctx;
+    }
+    /** Maps URLs served by a dev server (e.g. Vite at http://localhost:5173) onto a directory. */
+    addDevServer(origin, root) {
+        const others = (this.#ctx.devServers ?? []).filter((s) => s.origin !== origin);
+        this.#ctx = { ...this.#ctx, devServers: [...others, { origin, root }] };
+    }
+    get sourceCount() {
+        return this.#sources.size;
+    }
+    ingest(agentId, message) {
+        switch (message.type) {
+            case 'hello':
+                this.#agents.set(agentId, {
+                    kind: message.kind,
+                    pid: message.pid,
+                    scripts: new Map(),
+                    periodic: new PeriodicFunctions(),
+                });
+                return;
+            case 'scripts': {
+                const agent = this.#agent(agentId);
+                for (const s of message.scripts)
+                    agent.scripts.set(s.scriptId, s);
+                return;
+            }
+            case 'source':
+                this.#sources.set(message.hash, message.source);
+                return;
+            case 'traceStart': {
+                // Merge rather than replace, in case a backend delta with this ID arrived first.
+                const existing = this.#pending.get(message.traceId);
+                if (existing) {
+                    existing.trace.label = message.label;
+                    existing.trace.origin = 'browser';
+                    existing.trace.startedAt = Math.min(existing.trace.startedAt, message.at);
+                }
+                else {
+                    this.#pending.set(message.traceId, this.#newPending(message.traceId, message.label, 'browser', message.at));
+                }
+                return;
+            }
+            case 'traceEnd': {
+                const p = this.#pending.get(message.traceId);
+                if (p) {
+                    p.trace.endedAt = message.at;
+                    this.#publish(p);
+                }
+                return;
+            }
+            case 'delta':
+                this.#onDelta(agentId, message);
+                return;
+            case 'lines':
+                this.#onLines(agentId, message);
+                return;
+        }
+    }
+    #onDelta(agentId, delta) {
+        const agent = this.#agent(agentId);
+        // Background deltas only feed the periodic-function rule (ARCHITECTURE 4.6); never traces.
+        if (delta.phase === 'background') {
+            agent.periodic.observeBackground(delta.coverage, (id) => agent.scripts.get(id)?.hash);
+            return;
+        }
+        const pending = this.#pendingFor(delta.traceId, delta.request ? `${delta.request.method} ${delta.request.path}` : 'action', delta.startedAt);
+        for (const coverage of delta.coverage) {
+            const info = agent.scripts.get(coverage.scriptId);
+            const source = info ? this.#sources.get(info.hash) : undefined;
+            if (source === undefined) {
+                // Without the exact source V8 ran, offsets can't be turned into lines.
+                const r = resolveFile(coverage.url, this.#ctx);
+                this.#drop(pending, r.kind === 'dropped' ? r.reason : 'no-source');
+                continue;
+            }
+            let sourceMap;
+            try {
+                sourceMap = info?.sourceMapURL ? decodeDataUrlSourceMap(info.sourceMapURL) : undefined;
+            }
+            catch {
+                this.#drop(pending, 'no-source-map');
+                continue;
+            }
+            const map = (c) => mapScript({ coverage: c, source, ...(sourceMap ? { sourceMap } : {}) }, this.#ctx);
+            const result = map(coverage);
+            for (const [reason, n] of result.dropped)
+                this.#drop(pending, reason, n);
+            // Lines are never removed. A file whose lit lines all come from periodic code (a timer that
+            // happened to fire during the action) is marked background so clients can tone it down.
+            const fg = info ? agent.periodic.foreground(coverage, info.hash) : coverage;
+            const fgFiles = fg === coverage ? result.files : fg ? map(fg).files : new Map();
+            for (const [path, lines] of result.files) {
+                const fgLines = fgFiles.get(path);
+                const foreground = fgLines !== undefined && [...fgLines.values()].some((c) => c > 0);
+                this.#addFile(pending, path, agent.kind, lines, delta.startedAt, foreground);
+            }
+        }
+        if (delta.request) {
+            pending.trace.requests.push({
+                collector: agent.kind,
+                pid: agent.pid,
+                method: delta.request.method,
+                path: delta.request.path,
+                ...(delta.request.status !== undefined ? { status: delta.request.status } : {}),
+                durationMs: Math.max(0, delta.endedAt - delta.startedAt),
+                overlapped: (delta.overlapped?.length ?? 0) > 0,
+            });
+        }
+        // A browser trace ends only with traceEnd, after the frontend's own delta. Backend deltas
+        // arrive mid-click and must not make the trace look finished to clients.
+        if (pending.trace.origin === 'backend')
+            pending.trace.endedAt = Math.max(pending.trace.endedAt ?? 0, delta.endedAt);
+        this.#publish(pending);
+    }
+    #onLines(agentId, msg) {
+        const agent = this.#agent(agentId);
+        const label = msg.request ? `${msg.request.method} ${msg.request.path}` : 'action';
+        const pending = this.#pendingFor(msg.traceId, label, msg.startedAt);
+        for (const file of msg.files) {
+            const r = resolveFile(file.path, this.#ctx);
+            if (r.kind === 'dropped') {
+                this.#drop(pending, r.reason);
+                continue;
+            }
+            this.#addFile(pending, r.path, 'python', new Map(file.lines.map((l) => [l, 1])), msg.startedAt, true);
+        }
+        if (msg.request) {
+            pending.trace.requests.push({
+                collector: 'python',
+                pid: agent.pid || msg.pid,
+                method: msg.request.method,
+                path: msg.request.path,
+                ...(msg.request.status !== undefined ? { status: msg.request.status } : {}),
+                durationMs: Math.max(0, msg.endedAt - msg.startedAt),
+                overlapped: false,
+            });
+        }
+        if (pending.trace.origin === 'backend')
+            pending.trace.endedAt = Math.max(pending.trace.endedAt ?? 0, msg.endedAt);
+        this.#publish(pending);
+    }
+    #agent(agentId) {
+        let a = this.#agents.get(agentId);
+        if (!a) {
+            // A batch can arrive before (or without) hello, for example after a daemon restart.
+            a = {
+                kind: agentId.startsWith('py-') ? 'python' : 'node',
+                pid: 0,
+                scripts: new Map(),
+                periodic: new PeriodicFunctions(),
+            };
+            this.#agents.set(agentId, a);
+        }
+        return a;
+    }
+    /** Finds the browser-started trace for this ID, or starts a backend-only trace. */
+    #pendingFor(traceId, label, at) {
+        if (traceId) {
+            const existing = this.#pending.get(traceId) ?? this.#fromStore(traceId);
+            if (existing)
+                return existing;
+        }
+        const p = this.#newPending(traceId ?? newTraceId(), label, 'backend', at);
+        this.#pending.set(p.trace.id, p);
+        return p;
+    }
+    #fromStore(traceId) {
+        const trace = this.#store.get(traceId);
+        if (!trace)
+            return undefined;
+        const p = { trace: structuredClone(trace), files: new Map(), dropped: new Map() };
+        for (const f of trace.files) {
+            p.files.set(f.path, {
+                collector: f.collector,
+                lines: new Map(f.lines.map((l) => [l.line, l.count])),
+                firstSeenAt: f.firstSeenAt,
+                foreground: !f.background,
+            });
+        }
+        for (const d of trace.dropped)
+            p.dropped.set(d.reason, d.count);
+        this.#pending.set(traceId, p);
+        return p;
+    }
+    #newPending(id, label, origin, at) {
+        return {
+            trace: { id, label, origin, startedAt: at, files: [], requests: [], dropped: [] },
+            files: new Map(),
+            dropped: new Map(),
+        };
+    }
+    #addFile(p, path, collector, lines, at, foreground) {
+        const existing = p.files.get(path);
+        if (existing) {
+            existing.lines = mergeLineCounts(existing.lines, lines);
+            existing.foreground ||= foreground;
+        }
+        else
+            p.files.set(path, { collector, lines, firstSeenAt: at, foreground });
+    }
+    #drop(p, reason, n = 1) {
+        p.dropped.set(reason, (p.dropped.get(reason) ?? 0) + n);
+    }
+    #publish(p) {
+        const files = [];
+        for (const [path, f] of p.files) {
+            const lines = [...f.lines]
+                .filter(([, c]) => c > 0)
+                .sort((a, b) => a[0] - b[0])
+                .map(([line, count]) => ({ line, count }));
+            if (lines.length === 0)
+                continue;
+            files.push({
+                path,
+                collector: f.collector,
+                lines,
+                firstSeenAt: f.firstSeenAt,
+                ...(f.foreground ? {} : { background: true }),
+            });
+        }
+        files.sort((a, b) => a.firstSeenAt - b.firstSeenAt || a.path.localeCompare(b.path));
+        p.trace.files = files;
+        p.trace.dropped = [...p.dropped].map(([reason, count]) => ({ reason, count }));
+        this.#store.put(structuredClone(p.trace));
+        // Keep at most 50 traces open for late backend deltas; older ones are re-read from the store.
+        if (this.#pending.size > 50) {
+            const oldest = this.#pending.keys().next().value;
+            if (oldest !== undefined)
+                this.#pending.delete(oldest);
+        }
+    }
+}
+//# sourceMappingURL=correlator.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,15 @@
+import { DaemonDiscovery } from '@lightpath-dev/protocol';
+/** Writes `.lightpath/daemon.json` with user-only permissions, plus a .gitignore for the folder. */
+export declare function writeDiscovery(workspaceRoot: string, info: DaemonDiscovery): Promise<string>;
+/** Reads and validates the discovery file, or returns undefined if it's missing or invalid. */
+export declare function readDiscovery(workspaceRoot: string): Promise<DaemonDiscovery | undefined>;
+export declare function removeDiscovery(workspaceRoot: string): Promise<void>;
+/**
+ * The nearest folder at or above `dir` with a valid discovery file, and what it says. This is where
+ * `lightpath mcp` looks too, so `lightpath doctor` in a subfolder reports the daemon MCP would use.
+ */
+export declare function findDiscovery(dir: string): Promise<{
+    root: string;
+    info: DaemonDiscovery;
+} | undefined>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.js

@@ -0,0 +1,42 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DaemonDiscovery, DISCOVERY_FILE } from '@lightpath-dev/protocol';
+/** Writes `.lightpath/daemon.json` with user-only permissions, plus a .gitignore for the folder. */
+export async function writeDiscovery(workspaceRoot, info) {
+    const file = join(workspaceRoot, DISCOVERY_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(join(dirname(file), '.gitignore'), '*\n');
+    // mode applies on POSIX; on Windows the file inherits the user's ACL from the workspace.
+    await writeFile(file, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+    return file;
+}
+/** Reads and validates the discovery file, or returns undefined if it's missing or invalid. */
+export async function readDiscovery(workspaceRoot) {
+    try {
+        const raw = await readFile(join(workspaceRoot, DISCOVERY_FILE), 'utf8');
+        const parsed = DaemonDiscovery.safeParse(JSON.parse(raw));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function removeDiscovery(workspaceRoot) {
+    await rm(join(workspaceRoot, DISCOVERY_FILE), { force: true });
+}
+/**
+ * The nearest folder at or above `dir` with a valid discovery file, and what it says. This is where
+ * `lightpath mcp` looks too, so `lightpath doctor` in a subfolder reports the daemon MCP would use.
+ */
+export async function findDiscovery(dir) {
+    for (let root = resolve(dir);;) {
+        const info = await readDiscovery(root);
+        if (info)
+            return { root, info };
+        const parent = dirname(root);
+        if (parent === root)
+            return undefined;
+        root = parent;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { authorize, newToken, tokensEqual } from './auth.js';
+export { Correlator } from './correlator.js';
+export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';
+export { type DaemonOptions, type RunningDaemon, startDaemon } from './server.js';
+export { MemoryStore, type Store, type TraceQuery } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+export { authorize, newToken, tokensEqual } from './auth.js';
+export { Correlator } from './correlator.js';
+export { findDiscovery, readDiscovery, removeDiscovery, writeDiscovery } from './discovery.js';
+export { startDaemon } from './server.js';
+export { MemoryStore } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,28 @@
+import type { ResolveContext } from '@lightpath-dev/core';
+import { Correlator } from './correlator.js';
+import { type Store } from './store.js';
+export interface DaemonOptions {
+    /** Workspace roots; the first one holds `.lightpath/daemon.json`. */
+    workspaceRoots: string[];
+    devServers?: ResolveContext['devServers'];
+    /** Globs for workspace files to leave out of traces (`ignore` in lightpath.config.json). */
+    ignore?: string[];
+    /** 0 picks a free port. */
+    port?: number;
+    token?: string;
+    store?: Store;
+    writeDiscoveryFile?: boolean;
+    log?: (msg: string) => void;
+}
+export interface RunningDaemon {
+    port: number;
+    url: string;
+    token: string;
+    startedAt: number;
+    store: Store;
+    correlator: Correlator;
+    close(): Promise<void>;
+}
+/** Starts the daemon on 127.0.0.1 (docs/ARCHITECTURE.md section 7). */
+export declare function startDaemon(options: DaemonOptions): Promise<RunningDaemon>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,153 @@
+import http, {} from 'node:http';
+import { ClientMessage, CloseCode, IngestBatch, MAX_MESSAGE_BYTES, PROTOCOL_VERSION, } from '@lightpath-dev/protocol';
+import { WebSocketServer } from 'ws';
+import { authorize, newToken } from './auth.js';
+import { Correlator } from './correlator.js';
+import { removeDiscovery, writeDiscovery } from './discovery.js';
+import { MemoryStore } from './store.js';
+/** Starts the daemon on 127.0.0.1 (docs/ARCHITECTURE.md section 7). */
+export async function startDaemon(options) {
+    const token = options.token ?? newToken();
+    const store = options.store ?? new MemoryStore();
+    const log = options.log ?? (() => { });
+    const startedAt = Date.now();
+    const correlator = new Correlator(store, {
+        workspaceRoots: options.workspaceRoots,
+        ...(options.devServers ? { devServers: options.devServers } : {}),
+        ...(options.ignore?.length ? { ignore: options.ignore } : {}),
+    });
+    const server = http.createServer((req, res) => {
+        void route(req, res).catch((err) => {
+            log(`request error: ${err.stack ?? err}`);
+            if (!res.headersSent)
+                res.writeHead(500).end();
+        });
+    });
+    async function route(req, res) {
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        if (req.method === 'GET' && path === '/v1/health') {
+            return json(res, 200, { ok: true, protocolVersion: PROTOCOL_VERSION });
+        }
+        if (req.method === 'POST' && path === '/v1/ingest') {
+            const auth = authorize(req, token);
+            if (auth !== 'ok')
+                return json(res, auth === 'forbidden' ? 403 : 401, { error: auth });
+            const body = await readBody(req, MAX_MESSAGE_BYTES);
+            if (body === undefined)
+                return json(res, 413, { error: 'body too large' });
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return json(res, 400, { error: 'invalid JSON' });
+            }
+            const batch = IngestBatch.safeParse(parsed);
+            if (!batch.success)
+                return json(res, 400, { error: batch.error.issues.slice(0, 5) });
+            if (batch.data.protocolVersion !== PROTOCOL_VERSION)
+                return json(res, 426, { error: 'protocol version mismatch' });
+            for (const message of batch.data.messages)
+                correlator.ingest(batch.data.agentId, message);
+            res.writeHead(204, { 'x-lightpath-started-at': String(startedAt) }).end();
+            return;
+        }
+        json(res, 404, { error: 'not found' });
+    }
+    // ── Client feed ───────────────────────────────────────────────────────────
+    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE_BYTES });
+    server.on('upgrade', (req, socket, head) => {
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        const auth = authorize(req, token);
+        if (path !== '/v1/client' || auth !== 'ok') {
+            socket.end(`HTTP/1.1 ${auth === 'forbidden' ? '403 Forbidden' : path !== '/v1/client' ? '404 Not Found' : '401 Unauthorized'}\r\n\r\n`);
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => onClient(ws));
+    });
+    function onClient(ws) {
+        const send = (m) => ws.send(JSON.stringify(m));
+        send({ type: 'welcome', protocolVersion: PROTOCOL_VERSION, workspaceRoots: options.workspaceRoots });
+        const unsubscribe = store.subscribe((trace) => send({ type: 'trace', trace }));
+        ws.on('close', unsubscribe);
+        ws.on('message', (data) => {
+            let parsed;
+            try {
+                parsed = ClientMessage.safeParse(JSON.parse(String(data)));
+            }
+            catch {
+                ws.close(CloseCode.BadMessage, 'invalid JSON');
+                return;
+            }
+            if (!parsed.success) {
+                ws.close(CloseCode.BadMessage, 'invalid message');
+                return;
+            }
+            const msg = parsed.data;
+            if (msg.type === 'listTraces') {
+                send({
+                    type: 'traces',
+                    requestId: msg.requestId,
+                    traces: store.list({ limit: msg.limit, label: msg.label }),
+                });
+            }
+            else {
+                send({ type: 'traceResult', requestId: msg.requestId, trace: store.get(msg.traceId) ?? null });
+            }
+        });
+    }
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port ?? 0, '127.0.0.1', () => resolve());
+    });
+    const port = server.address().port;
+    const root = options.workspaceRoots[0];
+    if (options.writeDiscoveryFile !== false && root) {
+        await writeDiscovery(root, {
+            port,
+            token,
+            pid: process.pid,
+            protocolVersion: PROTOCOL_VERSION,
+            startedAt,
+        });
+    }
+    log(`daemon listening on 127.0.0.1:${port}`);
+    return {
+        port,
+        url: `http://127.0.0.1:${port}`,
+        token,
+        startedAt,
+        store,
+        correlator,
+        async close() {
+            for (const client of wss.clients)
+                client.close();
+            wss.close();
+            await new Promise((resolve) => server.close(() => resolve()));
+            if (options.writeDiscoveryFile !== false && root)
+                await removeDiscovery(root);
+        },
+    };
+}
+function json(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
+}
+/** Reads a request body as UTF-8, or returns undefined if it exceeds `limit` bytes. */
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                resolve(undefined);
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/store.d.ts

@@ -0,0 +1,23 @@
+import type { Trace, TraceId, TraceSummary } from '@lightpath-dev/protocol';
+export interface TraceQuery {
+    limit?: number | undefined;
+    /** Case-insensitive substring match on the trace label. */
+    label?: string | undefined;
+}
+export interface Store {
+    put(trace: Trace): void;
+    get(id: TraceId): Trace | undefined;
+    /** Newest first. */
+    list(query?: TraceQuery): TraceSummary[];
+    subscribe(listener: (trace: Trace) => void): () => void;
+}
+/** Keeps the most recent traces in memory (ARCHITECTURE section 7.3). */
+export declare class MemoryStore implements Store {
+    #private;
+    constructor(capacity?: number);
+    put(trace: Trace): void;
+    get(id: TraceId): Trace | undefined;
+    list(query?: TraceQuery): TraceSummary[];
+    subscribe(listener: (trace: Trace) => void): () => void;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.js

@@ -0,0 +1,42 @@
+/** Keeps the most recent traces in memory (ARCHITECTURE section 7.3). */
+export class MemoryStore {
+    #traces = new Map();
+    #listeners = new Set();
+    #capacity;
+    constructor(capacity = 200) {
+        this.#capacity = capacity;
+    }
+    put(trace) {
+        // Re-inserting moves the trace to the newest position.
+        this.#traces.delete(trace.id);
+        this.#traces.set(trace.id, trace);
+        while (this.#traces.size > this.#capacity) {
+            const oldest = this.#traces.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.#traces.delete(oldest);
+        }
+        for (const listener of this.#listeners)
+            listener(trace);
+    }
+    get(id) {
+        return this.#traces.get(id);
+    }
+    list(query = {}) {
+        const needle = query.label?.toLowerCase();
+        const out = [];
+        for (const t of [...this.#traces.values()].reverse()) {
+            if (needle && !t.label.toLowerCase().includes(needle))
+                continue;
+            out.push({ id: t.id, label: t.label, startedAt: t.startedAt, fileCount: t.files.length });
+            if (query.limit && out.length >= query.limit)
+                break;
+        }
+        return out;
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+}
+//# sourceMappingURL=store.js.map

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@lightpath-dev/daemon",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Local Lightpath daemon: receives coverage from agents, maps it to source lines, and serves traces",
+  "keywords": [
+    "coverage",
+    "trace",
+    "daemon",
+    "websocket"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Unknown-333/Lightpath#readme",
+  "bugs": "https://github.com/Unknown-333/Lightpath/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unknown-333/Lightpath.git",
+    "directory": "packages/daemon"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lightpath-dev/core": "0.0.1",
+    "@lightpath-dev/protocol": "0.0.1",
+    "ws": "8.22.0"
+  },
+  "devDependencies": {
+    "@types/ws": "8.18.2"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p test"
+  }
 }