@playola-radio/slipstream 0.1.0

package/dist/clip-worker-pool.js

@@ -0,0 +1,118 @@
+/**
+ * A single persistent clip-projection worker thread. It exposes the `ClipCompute`
+ * seam the service drives: `run(job)` returns a promise plus a `cancel()` the
+ * service calls on a wall-clock overrun — cancel terminates the stuck worker
+ * (a running diff cannot be interrupted from inside) and spawns a replacement,
+ * so a single pathological change cannot wedge the worker. The service's
+ * admission gate guarantees at most one concurrent `run` call (B1 runs exactly
+ * one worker), so the worker is always free synchronously.
+ */
+import { Worker } from 'node:worker_threads';
+import { siblingModuleUrl } from "./sibling-module.js";
+import { CLIP_PROJECTION_VERSION } from "./clip-projection.js";
+import { emitProjectionPhase, emitProjectionTrace, traceProcessId } from "./projection-trace.js";
+const WORKER_URL = siblingModuleUrl('clip-projection-worker', import.meta.url);
+function workerErrorResult() {
+    return {
+        change_seq: '',
+        projection_version: CLIP_PROJECTION_VERSION,
+        status: 'skipped',
+        fallback_reason: 'worker-error',
+        clips: [],
+    };
+}
+export function createClipWorkerPool(trace) {
+    let current = null;
+    let jobId = 0;
+    let closed = false;
+    // Terminations started by cancel()/error (fire-and-forget from the caller's
+    // point of view) but not yet complete. close() must await these too — the
+    // worker they belong to is no longer `current` by the time close() runs
+    // (cancel() has already spawned and installed its replacement), so awaiting
+    // only the current worker would let shutdown finish while the actual
+    // CPU-heavy worker is still mid-terminate.
+    const pendingTerminations = new Set();
+    const identities = new WeakMap();
+    const trackTermination = (w, traceUnitId) => {
+        const processId = identities.get(w);
+        if (processId !== undefined && traceUnitId !== undefined)
+            emitProjectionTrace(trace, { kind: 'process-retire', processId, unitId: traceUnitId, atNs: process.hrtime.bigint() });
+        const p = w.terminate().catch(() => { });
+        pendingTerminations.add(p);
+        p.finally(() => pendingTerminations.delete(p));
+    };
+    const spawn = () => {
+        const startedAtNs = trace ? process.hrtime.bigint() : undefined;
+        const w = new Worker(WORKER_URL);
+        const processId = trace ? traceProcessId() : undefined;
+        if (processId !== undefined) {
+            identities.set(w, processId);
+            emitProjectionTrace(trace, { kind: 'process-start', processId, process: 'clip-worker', atNs: process.hrtime.bigint() });
+            w.once('online', () => emitProjectionPhase(trace, 'worker-startup', startedAtNs, { scope: 'clip', processId }));
+            w.on('exit', code => emitProjectionTrace(trace, { kind: 'process-exit', processId, code, atNs: process.hrtime.bigint() }));
+        }
+        w.on('message', (resp) => {
+            const cur = current;
+            if (!cur || cur.id !== resp.id)
+                return; // stale message from before a cancel
+            current = null;
+            emitProjectionPhase(trace, 'worker-roundtrip', cur.startedAtNs, { scope: 'clip', unitId: cur.traceUnitId, processId });
+            if (resp.ok && trace && processId !== undefined && resp.traceTimings)
+                for (const timing of resp.traceTimings)
+                    emitProjectionTrace(trace, { kind: 'phase', scope: 'clip', phase: timing.phase, durationNs: timing.durationNs,
+                        atNs: process.hrtime.bigint(), unitId: cur.traceUnitId, processId });
+            cur.resolve(resp.ok ? resp.result : workerErrorResult());
+        });
+        w.on('error', () => {
+            const cur = current;
+            current = null;
+            trackTermination(w, cur?.traceUnitId);
+            if (!closed)
+                worker = spawn();
+            if (cur)
+                cur.resolve(workerErrorResult());
+        });
+        return w;
+    };
+    let worker = spawn();
+    const run = (job, traceUnitId) => {
+        if (closed || current !== null) {
+            // Admission should prevent this; fail safe rather than block.
+            return { promise: Promise.resolve(workerErrorResult()), cancel: () => { } };
+        }
+        let settled = false;
+        const processId = identities.get(worker);
+        if (processId !== undefined && traceUnitId !== undefined)
+            emitProjectionTrace(trace, { kind: 'process-use', processId, unitId: traceUnitId, atNs: process.hrtime.bigint() });
+        const promise = new Promise((resolve) => {
+            const id = ++jobId;
+            current = { id, traceUnitId, startedAtNs: trace ? process.hrtime.bigint() : undefined,
+                resolve: (v) => { if (!settled) {
+                    settled = true;
+                    resolve(v);
+                } } };
+            worker.postMessage({ id, job, ...(trace ? { traceTimings: true } : {}) });
+        });
+        const cancel = () => {
+            if (settled || current === null)
+                return;
+            current.resolve(workerErrorResult());
+            current = null;
+            const stale = worker;
+            trackTermination(stale, traceUnitId);
+            if (!closed)
+                worker = spawn();
+        };
+        return { promise, cancel };
+    };
+    const close = async () => {
+        closed = true;
+        const cur = current;
+        current = null;
+        if (cur)
+            cur.resolve(workerErrorResult());
+        await worker.terminate().catch(() => { });
+        await Promise.all(pendingTerminations);
+    };
+    return { run, close };
+}

package/dist/config.js

@@ -0,0 +1,154 @@
+/**
+ * The public configuration surface (Fork 4): a JSON daemon config file plus CLI
+ * overrides, resolved into the effective enrichment policy and transcript
+ * discovery settings. Precedence is CLI > file > built-in defaults, applied
+ * field by field so an override never wipes a sibling.
+ *
+ * Configuration is enrichment-only: a bad or missing config warns and falls back
+ * to defaults, never throws — enrichment must never block capture (CLAUDE.md).
+ */
+import { isAbsolute, resolve } from 'node:path';
+import { DEFAULT_ENRICHMENT_POLICY } from "./attribution-producer.js";
+const HARNESSES = ['claude-code', 'codex'];
+const COVERAGE_VALUES = ['unconfigured', 'configured'];
+/** Max transcripts a bounded Codex scan reads before disclosing discovery-limited. */
+export const DEFAULT_CODEX_SCAN_LIMIT = 2000;
+export function defaultConfig(homeDir) {
+    return {
+        policy: {
+            window_ms: DEFAULT_ENRICHMENT_POLICY.window_ms,
+            grace_ms: DEFAULT_ENRICHMENT_POLICY.grace_ms,
+            sources: { ...DEFAULT_ENRICHMENT_POLICY.sources },
+        },
+        transcript: {
+            homes: {
+                'claude-code': resolve(homeDir, '.claude'),
+                codex: resolve(homeDir, '.codex'),
+            },
+            codexScanLimit: DEFAULT_CODEX_SCAN_LIMIT,
+        },
+    };
+}
+function isHarness(v) {
+    return HARNESSES.includes(v);
+}
+function positiveInt(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0 ? v : undefined;
+}
+/** Parse a JSON config file into an override layer. Never throws: malformed JSON
+ * or bad fields produce warnings and are skipped, so capture is never blocked. */
+export function parseConfigFile(raw) {
+    const warnings = [];
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return { overrides: {}, warnings: ['config: file is not valid JSON; using defaults'] };
+    }
+    if (typeof obj !== 'object' || obj === null) {
+        return { overrides: {}, warnings: ['config: top level is not an object; using defaults'] };
+    }
+    const root = obj;
+    const overrides = {};
+    const enrichment = root.enrichment;
+    if (typeof enrichment === 'object' && enrichment !== null) {
+        const e = enrichment;
+        if ('window_ms' in e) {
+            const n = positiveInt(e.window_ms);
+            if (n === undefined)
+                warnings.push('config: enrichment.window_ms must be a positive integer; ignored');
+            else
+                overrides.windowMs = n;
+        }
+        if ('grace_ms' in e) {
+            const n = positiveInt(e.grace_ms);
+            if (n === undefined)
+                warnings.push('config: enrichment.grace_ms must be a positive integer; ignored');
+            else
+                overrides.graceMs = n;
+        }
+        if (typeof e.sources === 'object' && e.sources !== null) {
+            const sources = {};
+            for (const [k, v] of Object.entries(e.sources)) {
+                if (!isHarness(k))
+                    warnings.push(`config: unknown harness "${k}" in enrichment.sources; ignored`);
+                else if (typeof v !== 'string' || !COVERAGE_VALUES.includes(v)) {
+                    warnings.push(`config: enrichment.sources.${k} must be one of ${COVERAGE_VALUES.join('/')}; ignored`);
+                }
+                else
+                    sources[k] = v;
+            }
+            if (Object.keys(sources).length > 0)
+                overrides.sources = sources;
+        }
+    }
+    const transcripts = root.transcripts;
+    if (typeof transcripts === 'object' && transcripts !== null) {
+        const t = transcripts;
+        if (typeof t.homes === 'object' && t.homes !== null) {
+            const homes = {};
+            for (const [k, v] of Object.entries(t.homes)) {
+                if (!isHarness(k))
+                    warnings.push(`config: unknown harness "${k}" in transcripts.homes; ignored`);
+                else if (typeof v !== 'string' || v.length === 0)
+                    warnings.push(`config: transcripts.homes.${k} must be a path; ignored`);
+                else
+                    homes[k] = v;
+            }
+            if (Object.keys(homes).length > 0)
+                overrides.homes = homes;
+        }
+        if ('codex_scan_limit' in t) {
+            const n = positiveInt(t.codex_scan_limit);
+            if (n === undefined)
+                warnings.push('config: transcripts.codex_scan_limit must be a positive integer; ignored');
+            else
+                overrides.codexScanLimit = n;
+        }
+    }
+    return { overrides, warnings };
+}
+function applyLayer(base, o, homeDir) {
+    const homes = { ...base.transcript.homes };
+    if (o.homes) {
+        for (const h of HARNESSES) {
+            const v = o.homes[h];
+            if (v !== undefined)
+                homes[h] = isAbsolute(v) ? v : resolve(homeDir, v);
+        }
+    }
+    return {
+        policy: {
+            window_ms: o.windowMs ?? base.policy.window_ms,
+            grace_ms: o.graceMs ?? base.policy.grace_ms,
+            sources: { ...base.policy.sources, ...(o.sources ?? {}) },
+        },
+        transcript: {
+            homes,
+            codexScanLimit: o.codexScanLimit ?? base.transcript.codexScanLimit,
+        },
+    };
+}
+/** Layer file then CLI overrides onto the defaults; CLI wins field by field. */
+export function resolveConfig(file, cli, homeDir) {
+    const withFile = applyLayer(defaultConfig(homeDir), file, homeDir);
+    return applyLayer(withFile, cli, homeDir);
+}
+export async function loadConfig(opts) {
+    const warnings = [];
+    let fileOverrides = {};
+    if (opts.path !== undefined) {
+        const raw = await opts.io.readFile(opts.path);
+        if (raw === undefined) {
+            warnings.push(`config: file not found at ${opts.path}; using defaults`);
+        }
+        else {
+            const parsed = parseConfigFile(raw);
+            fileOverrides = parsed.overrides;
+            warnings.push(...parsed.warnings);
+        }
+    }
+    const config = resolveConfig(fileOverrides, opts.cli ?? {}, opts.homeDir);
+    return { config, warnings };
+}

package/dist/control-client.js

@@ -0,0 +1,98 @@
+import { connect } from 'node:net';
+import { createLineDecoder, encodeMessage, } from "./control-protocol.js";
+const DEFAULT_CONNECT_TIMEOUT_MS = 2000;
+const DEFAULT_RESPONSE_TIMEOUT_MS = 15000;
+/** The request reached the wire but its outcome is unknowable — the mutation may
+ * or may not have committed. The caller must not retry blindly. */
+export class OutcomeUnknownError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OutcomeUnknownError';
+    }
+}
+function daemonUnavailable(message) {
+    return { v: 1, ok: false, code: 'DAEMON_UNAVAILABLE', message };
+}
+/** A reply is only usable if it is a well-formed response envelope. Anything else
+ * on the wire (a bare `null`, a success object missing `ok`, a wrong protocol
+ * version) means we cannot read the daemon's answer — ambiguous after send, never
+ * a silent success. */
+function isResponseEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v.v !== 1 || typeof v.ok !== 'boolean')
+        return false;
+    if (v.ok === false)
+        return typeof v.code === 'string' && typeof v.message === 'string';
+    return true;
+}
+export function sendControlRequest(opts) {
+    const connectTimeoutMs = opts.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    const responseTimeoutMs = opts.responseTimeoutMs ?? DEFAULT_RESPONSE_TIMEOUT_MS;
+    if (opts.deadlineAtMs !== undefined && opts.deadlineAtMs <= Date.now()) {
+        return Promise.resolve(daemonUnavailable('daemon request deadline elapsed before connecting'));
+    }
+    const remaining = (phaseTimeoutMs) => opts.deadlineAtMs === undefined
+        ? phaseTimeoutMs : Math.min(phaseTimeoutMs, Math.max(0, opts.deadlineAtMs - Date.now()));
+    return new Promise((resolve, reject) => {
+        const decoder = createLineDecoder();
+        let sent = false;
+        let settled = false;
+        let timer;
+        const sock = connect(opts.socketPath);
+        const finish = (act) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            sock.removeAllListeners();
+            sock.destroy();
+            act();
+        };
+        // Before the request is on the wire, a fault means the daemon is unreachable;
+        // after, the outcome is unknowable. `sent` is the sole switch between them.
+        const failTransport = (message) => sent
+            ? finish(() => reject(new OutcomeUnknownError(message)))
+            : finish(() => resolve(daemonUnavailable(message)));
+        timer = setTimeout(() => failTransport('daemon did not respond before the deadline'), remaining(connectTimeoutMs));
+        sock.on('connect', () => {
+            // The connection is up: from here on, bytes may reach the daemon, so any
+            // later fault is ambiguous, not proof of nothing sent. Flip `sent` before
+            // the write starts and re-arm the timer as a response deadline.
+            clearTimeout(timer);
+            if (opts.deadlineAtMs !== undefined && opts.deadlineAtMs <= Date.now()) {
+                failTransport('daemon request deadline elapsed before transmission');
+                return;
+            }
+            sent = true;
+            timer = setTimeout(() => failTransport('no response before the deadline; the request may have committed'), remaining(responseTimeoutMs));
+            sock.write(encodeMessage(opts.request), (err) => {
+                if (err)
+                    failTransport(`control write failed: ${err.message}`);
+            });
+        });
+        sock.on('data', (chunk) => {
+            let messages;
+            try {
+                messages = decoder.push(chunk);
+            }
+            catch (err) {
+                // A malformed reply after send: the daemon acted but we cannot read its
+                // answer — ambiguous, not "unavailable".
+                finish(() => reject(new OutcomeUnknownError(`unreadable control response: ${err.message}`)));
+                return;
+            }
+            if (messages.length === 0)
+                return; // response not yet complete
+            const reply = messages[0];
+            if (!isResponseEnvelope(reply)) {
+                finish(() => reject(new OutcomeUnknownError('daemon reply was not a valid control response')));
+                return;
+            }
+            finish(() => resolve(reply));
+        });
+        sock.on('error', (err) => failTransport(err.message));
+        sock.on('close', () => failTransport('connection closed before a response arrived'));
+    });
+}

package/dist/control-protocol.js

@@ -0,0 +1,72 @@
+/**
+ * The Slipstream daemon control protocol: newline-delimited JSON over an
+ * owner-only `node:net` unix socket. This is a PRIVATE CONTROL channel — its
+ * verbs (attach / detach / status / begin_task / delete_session / gc) WRITE
+ * public events or maintain the store and never read or serve the feed. Readers
+ * keep serving the public HTTP/disk view; there is no privileged back channel
+ * for reading.
+ *
+ * Framing is one JSON object per line. A length prefix would buy nothing here:
+ * the real hazards are unbounded buffering of an unterminated line, a UTF-8
+ * character split across socket chunks, and several frames arriving in one
+ * chunk. The decoder below closes all three, and refuses a line past a byte cap
+ * before it can accumulate.
+ */
+/** A framing/parse fault at the transport layer. The server answers a
+ * best-effort `PROTOCOL` error then closes; the client surfaces it as-is. */
+export class ProtocolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProtocolError';
+    }
+}
+/** One control line (the JSON object, excluding its trailing newline) must fit
+ * in this many bytes. Generous for a title but far short of anything that could
+ * exhaust memory. */
+export const MAX_MESSAGE_BYTES = 1024 * 1024;
+const NEWLINE = 0x0a;
+export function encodeMessage(value) {
+    return Buffer.from(JSON.stringify(value) + '\n', 'utf8');
+}
+export function createLineDecoder(maxBytes = MAX_MESSAGE_BYTES) {
+    let buf = Buffer.alloc(0);
+    return {
+        push(chunk) {
+            // Keep raw bytes until a line is complete: a multibyte character split
+            // across chunks is only decoded once all its bytes have arrived.
+            buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
+            const out = [];
+            let start = 0;
+            for (;;) {
+                const nl = buf.indexOf(NEWLINE, start);
+                if (nl === -1)
+                    break;
+                const line = buf.subarray(start, nl);
+                start = nl + 1;
+                if (line.length === 0)
+                    continue; // tolerate blank separators
+                if (line.length > maxBytes)
+                    throw new ProtocolError('control line exceeds byte cap');
+                const text = line.toString('utf8');
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    throw new ProtocolError('control line is not valid JSON');
+                }
+                out.push(parsed);
+            }
+            buf = start === 0 ? buf : buf.subarray(start);
+            // Refuse an unterminated line that has already outgrown the cap, before it
+            // can accumulate without bound across future chunks.
+            if (buf.length > maxBytes)
+                throw new ProtocolError('control line exceeds byte cap');
+            return out;
+        },
+        end() {
+            if (buf.length > 0)
+                throw new ProtocolError('stream ended mid-line');
+        },
+    };
+}

package/dist/daemon-location.js

@@ -0,0 +1,33 @@
+/**
+ * Where the forwarder finds the daemon's control socket.
+ *
+ * The forwarder is a control client, not the daemon: it never creates the
+ * store, it only needs to know which store the shared daemon owns so it can
+ * connect to `<store>/control.sock`. That store defaults to `~/.slipstream`
+ * (matching the CLI) and may be overridden with an explicit `--store <dir>`
+ * shared with the CLI, so both point at the same daemon.
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const CONTROL_SOCKET_NAME = 'control.sock';
+export function defaultDaemonStore(home = homedir()) {
+    return join(home, '.slipstream');
+}
+export function controlSocketPath(storeDir) {
+    return join(storeDir, CONTROL_SOCKET_NAME);
+}
+/** Resolve the store dir the forwarder should talk to from its argv: an
+ * explicit `--store <dir>` (resolved to an absolute path), else the default
+ * home store. Fails fast when `--store` is given without a value. */
+export function resolveStoreDir(argv, home = homedir()) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--store') {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error('--store requires a directory argument');
+            }
+            return resolve(value);
+        }
+    }
+    return defaultDaemonStore(home);
+}