@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workflow/event-bus.js

@@ -0,0 +1,224 @@
+/**
+ * In-process event bus that fans workflow state-change events out to
+ * subscribed SSE sessions. The shape and scope rules live in
+ * `@bevel-software/platform-shared/workflow/events.ts` — this module is the runtime that
+ * makes them deliverable.
+ *
+ * **What this owns**
+ *
+ *   1. **The monotonic event id.** Each `emit` stamps the next id; clients
+ *      reconnecting with `Last-Event-ID: <n>` use it to replay everything
+ *      they missed.
+ *
+ *   2. **A per-process ring buffer** of the last `BUFFER_CAPACITY` events.
+ *      Replay works if the gap is short. Long disconnects fall back to
+ *      `{ kind: 'resync' }` so the client refetches cleanly.
+ *
+ *   3. **A registry of subscribers**, each owning a per-session push
+ *      function. On `emit`, every subscriber that matches the event's scope
+ *      (see `isWorkspaceScoped` / `isUserScoped`) gets the event pushed
+ *      synchronously to its push callback — the route layer translates that
+ *      to an SSE `data:` line.
+ *
+ * **What this does NOT own**
+ *
+ *   - Transport (SSE framing, heartbeats): the route layer.
+ *   - Auth (which user owns a session): the route layer wires
+ *     userId + sessionId in at subscription time, this just stores them.
+ *   - Persistence: in-memory only. A server restart resets the id counter
+ *     and empties the buffer; clients that reconnect after a restart will
+ *     get a `resync` (their stored Last-Event-ID is necessarily older than
+ *     the new buffer can serve), which is exactly the right behavior.
+ *
+ * **Concurrency** — Node is single-threaded for JS, so a synchronous fan-out
+ * inside `emit` is safe. Subscribers must not throw from their push
+ * callback; we wrap every push in try/catch and log so one bad subscriber
+ * never blocks the rest.
+ */
+import { isUserScoped, isWorkspaceScoped, } from '@bevel-software/platform-shared';
+/**
+ * Capacity of the global event ring buffer. A new event evicts the oldest
+ * when full. Sized for "should comfortably catch any client through a brief
+ * network blip" — 500 events at e.g. one edit per second buys ~8 minutes of
+ * coverage, plenty for transient reconnects. Sized down would push more
+ * clients onto the `resync` path; sized up wastes RSS on no-op edits.
+ */
+const BUFFER_CAPACITY = 500;
+/**
+ * Decode-once, idempotent. Both sides of the focus / workspaceId
+ * comparison get fed through this so we don't care whether the caller
+ * sent the URL-encoded form (`razvan-radulescu%2Fsc`) or the canonical
+ * form (`razvan-radulescu/sc`). Catches malformed input by returning the
+ * original string — broken encoding shouldn't crash the dispatcher.
+ */
+function canonicalize(workspaceId) {
+    try {
+        return decodeURIComponent(workspaceId);
+    }
+    catch {
+        return workspaceId;
+    }
+}
+export class WorkflowEventBus {
+    nextId = 1;
+    buffer = [];
+    subscribers = new Map();
+    /**
+     * Stamp `payload` with `id` + `ts`, append to the ring buffer, then fan
+     * out synchronously to every matching subscriber. Returns the stamped
+     * event so callers (e.g. tests, debug logs) can see what was actually
+     * delivered.
+     */
+    emit(payload) {
+        const event = {
+            id: this.nextId++,
+            ts: new Date().toISOString(),
+            ...payload,
+        };
+        this.buffer.push(event);
+        if (this.buffer.length > BUFFER_CAPACITY) {
+            this.buffer.shift();
+        }
+        // Single-line emit log with all the fields most useful for tracing a
+        // failed delivery: which event, which scope it'll filter on, and the
+        // total subscriber pool size before fan-out. Per-subscriber matched/
+        // skipped decisions are logged below at debug level.
+        const scope = 'workspaceId' in event && event.workspaceId
+            ? `ws=${event.workspaceId}`
+            : 'forUserId' in event && event.forUserId
+                ? `user=${event.forUserId}`
+                : 'global';
+        const extra = [];
+        if ('path' in event && event.path)
+            extra.push(`path=${event.path}`);
+        if ('branch' in event && event.branch)
+            extra.push(`branch=${event.branch}`);
+        if ('newSha' in event && event.newSha !== undefined)
+            extra.push(`sha=${event.newSha ?? 'null'}`);
+        if ('holderName' in event && event.holderName)
+            extra.push(`holder=${event.holderName}`);
+        console.log(`[event-bus] EMIT id=${event.id} kind=${event.kind} ${scope}${extra.length ? ' ' + extra.join(' ') : ''} subs=${this.subscribers.size}`);
+        let matched = 0;
+        let skipped = 0;
+        for (const sub of this.subscribers.values()) {
+            // Best-effort per subscriber — one bad subscriber must not block
+            // the rest of the fan-out OR propagate back to the caller. The
+            // try/catch covers both the scope check (`matches` reaches into
+            // `sub.getFocusedWorkspaceId()`, which could throw if a bizarre
+            // subscriber holds buggy state) and the dispatch itself, so
+            // workflow mutations stay successful even if a listener throws.
+            // Callers can rely on `emit` never throwing, so they don't need
+            // to wrap every emit call site in their own try/catch.
+            try {
+                if (!this.matches(event, sub)) {
+                    skipped++;
+                    continue;
+                }
+                sub.push(event);
+                matched++;
+            }
+            catch (err) {
+                console.warn(`[event-bus] dispatch to session ${sub.sessionId} threw:`, err instanceof Error ? err.message : err);
+            }
+        }
+        console.log(`[event-bus] EMIT id=${event.id} kind=${event.kind} → delivered=${matched} skipped=${skipped}`);
+        return event;
+    }
+    /**
+     * Register a subscriber. Returns an `unsubscribe` function the route
+     * layer is expected to call from `res.on('close', …)` — without it a
+     * disconnected client leaks the session entry forever.
+     */
+    subscribe(sub) {
+        this.subscribers.set(sub.sessionId, sub);
+        console.log(`[event-bus] SUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`);
+        return () => {
+            // Only delete if the same Subscriber is still registered — protects
+            // against a stale unsubscribe (e.g. a reconnect replaced the entry
+            // before the old `close` handler fired).
+            if (this.subscribers.get(sub.sessionId) === sub) {
+                this.subscribers.delete(sub.sessionId);
+                console.log(`[event-bus] UNSUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`);
+            }
+        };
+    }
+    /**
+     * Snapshot of every event in the ring buffer strictly newer than
+     * `lastSeenId` that this `sub` would have received if it had been
+     * subscribed at the time. Used by the SSE route on reconnect:
+     *
+     *   - The client sends `Last-Event-ID: <n>` (browser does this
+     *     automatically when an `EventSource` reconnects).
+     *   - The route fetches `replayAfter(n, sub)` and emits each event
+     *     before resuming live delivery.
+     *
+     * Returns `null` when the gap is larger than the buffer — the route
+     * sends a `resync` event in that case and the client refetches everything.
+     * "Gap is larger" is detected by checking whether the buffer's oldest id
+     * is greater than `lastSeenId + 1` (i.e. we evicted events the client
+     * needs to see).
+     */
+    replayAfter(lastSeenId, sub) {
+        // Empty buffer: a client that never saw anything (lastSeenId === 0) has
+        // nothing to replay and the empty array is correct. A client that DID
+        // see events (lastSeenId > 0) but reached an empty buffer means the
+        // process restarted — the id counter reset to 1, so anything the client
+        // saw before is unreachable. Force a `resync` rather than silently
+        // delivering nothing.
+        if (this.buffer.length === 0) {
+            return lastSeenId === 0 ? [] : null;
+        }
+        const oldestBufferedId = this.buffer[0].id;
+        const newestBufferedId = this.buffer[this.buffer.length - 1].id;
+        if (oldestBufferedId > lastSeenId + 1) {
+            return null; // Caller emits a `resync`.
+        }
+        // Process restart can also leave `lastSeenId` ahead of the buffer's
+        // newest id (counter reset → newer events have lower ids than what the
+        // client last saw). Same outcome: client must resync from scratch.
+        if (lastSeenId > newestBufferedId) {
+            return null;
+        }
+        const tail = this.buffer.filter((e) => e.id > lastSeenId);
+        return tail.filter((e) => this.matches(e, sub));
+    }
+    /** Subscriber count — exposed for `/health` and tests. */
+    size() {
+        return this.subscribers.size;
+    }
+    /**
+     * Filter rule that decides whether `event` should reach `sub`:
+     *
+     *   - Workspace-scoped events: only sessions currently focused on the
+     *     same `workspaceId`.
+     *   - User-scoped events: only sessions whose `userId` matches `forUserId`.
+     *   - Global events (heartbeat, resync, change-request-*): everyone.
+     *
+     * The focus check resolves through `getFocusedWorkspaceId()` so a session
+     * that hasn't yet POSTed its focus gets no workspace events (correct —
+     * we don't know what it cares about).
+     */
+    matches(event, sub) {
+        if (isWorkspaceScoped(event)) {
+            const focus = sub.getFocusedWorkspaceId();
+            if (focus === null)
+                return false;
+            // **Normalise URL encoding before comparing.** The frontend stores
+            // `workspace.id` as `encodeURIComponent(branch)` (e.g.
+            // `razvan-radulescu%2Fsc`) and sends that as the focus value via
+            // the POST /focus endpoint. The backend route handlers, however,
+            // extract `req.params.id` which Express auto-decodes — so events
+            // fire with `workspaceId = razvan-radulescu/sc`. Naïve `===` then
+            // rejects every workspace-scoped event for any branch that
+            // contains a `/`, silently dropping all live updates (lock state,
+            // file-changed, fs-tree) on feature branches. Decoding both sides
+            // collapses the two forms into the same canonical key.
+            return canonicalize(focus) === canonicalize(event.workspaceId);
+        }
+        if (isUserScoped(event)) {
+            return sub.userId === event.forUserId;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/modules/workflow/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../../src/modules/workflow/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/events.routes.d.ts

@@ -0,0 +1,80 @@
+/**
+ * SSE event-bus HTTP surface.
+ *
+ *   GET  /api/events?session=<sessionId>     — open the long-lived SSE stream
+ *   POST /api/events/:sessionId/focus        — update which workspace this
+ *                                              session cares about (changes
+ *                                              over the connection's lifetime
+ *                                              as the user / agent switches
+ *                                              branches)
+ *
+ * **Why a per-tab session id, not per-workspace** — the connection must
+ * survive a workspace re-focus (when the user navigates between branches
+ * the URL changes and the workspace bootstrap rebinds `workspaceId`, but
+ * the EventSource stays open). So scope = `(userId, sessionId)`; the
+ * "what workspace events do I want" state is mutable and lives in the
+ * focus endpoint above.
+ *
+ * **Auth** — the SSE route can't read `Authorization: Bearer …` (the
+ * browser's EventSource API can't set headers), so the auth middleware
+ * also accepts the JWT from the `bevel_token` cookie set at login. The
+ * focus POST goes through the regular auth middleware too, and verifies
+ * that the cookie-authed user matches the session's owner.
+ *
+ * **Reconnect** — the browser's EventSource auto-reconnects on close
+ * (~3 s backoff). On reconnect it sends `Last-Event-ID: <n>` and the
+ * route replays anything still in the bus's ring buffer; if the buffer
+ * has evicted past `n`, the route emits `{ kind: 'resync' }` so the
+ * client refetches state from scratch.
+ *
+ * **Heartbeat** — every 25 s the route writes an SSE comment (`:\n\n`).
+ * Keeps proxies (nginx, Coolify's Traefik, Cloudflare) from killing the
+ * connection as idle. Cheap (~15 bytes), eliminates a whole class of bug.
+ */
+import type { Response } from 'express';
+import express from 'express';
+import type { WorkflowEvent } from '@bevel-software/platform-shared';
+import type { WorkflowEventBus } from './event-bus.js';
+import '../auth/auth.middleware.js';
+/**
+ * Per-session bookkeeping the route owns. The bus's `Subscriber` holds a
+ * `getFocusedWorkspaceId()` getter pointing at `session.focusedWorkspaceId`,
+ * so the focus POST mutates this object and the next event fan-out picks
+ * up the new value with no re-subscribe.
+ */
+interface ActiveSession {
+    sessionId: string;
+    userId: string;
+    focusedWorkspaceId: string | null;
+    /** Set when the SSE connection closes. Used by the focus POST so a
+     *  request that arrives after the connection drops 404s cleanly. */
+    closed: boolean;
+    /** The Express response stream backing this session. Stored so a
+     *  same-id reconnect can `end()` the old response and close its TCP
+     *  socket immediately, rather than leaving a dangling connection that
+     *  silently accumulates server-side resources. */
+    res: Response;
+    /** Tear down bus subscription + heartbeat. Stored on the session so a
+     *  same-id reconnect can run cleanup directly rather than relying on
+     *  the old `res.on('close')` path (which short-circuits if we mark the
+     *  session closed before the OS-level close event fires). */
+    cleanup: () => void;
+}
+export declare function createEventsRoutes(bus: WorkflowEventBus, authMiddleware: express.RequestHandler): express.Router;
+/**
+ * Serialise `event` into the SSE wire format. Each frame is:
+ *
+ *   id: <event.id>
+ *   data: <JSON payload>
+ *   \n
+ *
+ * The `id` field is what the browser's EventSource exposes as
+ * `event.lastEventId` and re-sends as `Last-Event-ID` on reconnect.
+ * Data is a single line of JSON — never embedded newlines, which would
+ * break the SSE parser. JSON.stringify guarantees that.
+ */
+declare function writeSseEvent(res: Response, event: WorkflowEvent): void;
+/** Re-exported so tests / future hooks can construct the response shape. */
+export { writeSseEvent as _writeSseEventForTests };
+export type { ActiveSession };
+//# sourceMappingURL=events.routes.d.ts.map

package/dist/modules/workflow/events.routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.routes.d.ts","sourceRoot":"","sources":["../../../src/modules/workflow/events.routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAW,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,4BAA4B,CAAC;AAMpC;;;;;GAKG;AACH,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;wEACoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB;;;sDAGkD;IAClD,GAAG,EAAE,QAAQ,CAAC;IACd;;;iEAG6D;IAC7D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,gBAAgB,EACrB,cAAc,EAAE,OAAO,CAAC,cAAc,GACrC,OAAO,CAAC,MAAM,CA4KhB;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CAGhE;AAED,4EAA4E;AAC5E,OAAO,EAAE,aAAa,IAAI,sBAAsB,EAAE,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/modules/workflow/events.routes.js

@@ -0,0 +1,216 @@
+/**
+ * SSE event-bus HTTP surface.
+ *
+ *   GET  /api/events?session=<sessionId>     — open the long-lived SSE stream
+ *   POST /api/events/:sessionId/focus        — update which workspace this
+ *                                              session cares about (changes
+ *                                              over the connection's lifetime
+ *                                              as the user / agent switches
+ *                                              branches)
+ *
+ * **Why a per-tab session id, not per-workspace** — the connection must
+ * survive a workspace re-focus (when the user navigates between branches
+ * the URL changes and the workspace bootstrap rebinds `workspaceId`, but
+ * the EventSource stays open). So scope = `(userId, sessionId)`; the
+ * "what workspace events do I want" state is mutable and lives in the
+ * focus endpoint above.
+ *
+ * **Auth** — the SSE route can't read `Authorization: Bearer …` (the
+ * browser's EventSource API can't set headers), so the auth middleware
+ * also accepts the JWT from the `bevel_token` cookie set at login. The
+ * focus POST goes through the regular auth middleware too, and verifies
+ * that the cookie-authed user matches the session's owner.
+ *
+ * **Reconnect** — the browser's EventSource auto-reconnects on close
+ * (~3 s backoff). On reconnect it sends `Last-Event-ID: <n>` and the
+ * route replays anything still in the bus's ring buffer; if the buffer
+ * has evicted past `n`, the route emits `{ kind: 'resync' }` so the
+ * client refetches state from scratch.
+ *
+ * **Heartbeat** — every 25 s the route writes an SSE comment (`:\n\n`).
+ * Keeps proxies (nginx, Coolify's Traefik, Cloudflare) from killing the
+ * connection as idle. Cheap (~15 bytes), eliminates a whole class of bug.
+ */
+import express from 'express';
+import '../auth/auth.middleware.js'; // Express Request augmentation
+/** Interval between SSE keep-alive comments (ms). 25 s sits comfortably under
+ * the typical 30–100 s proxy idle timeout. */
+const HEARTBEAT_INTERVAL_MS = 25_000;
+export function createEventsRoutes(bus, authMiddleware) {
+    const router = express.Router();
+    /**
+     * Process-wide session registry. The same map services the SSE open
+     * (creates the entry) and the focus POST (mutates `focusedWorkspaceId`).
+     * Entries clear when the SSE connection closes.
+     */
+    const sessions = new Map();
+    router.get('/events', authMiddleware, (req, res) => {
+        const sessionId = typeof req.query.session === 'string' ? req.query.session : '';
+        if (!sessionId) {
+            res.status(400).json({ error: 'session query parameter is required' });
+            return;
+        }
+        const userId = req.userId;
+        // SSE headers. `X-Accel-Buffering: no` tells nginx not to buffer the
+        // response (would batch events behind a flush boundary, killing
+        // latency). `Cache-Control: no-cache` + omitted `Content-Length`
+        // signal "long-lived stream, don't cache."
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache, no-transform');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no');
+        res.flushHeaders();
+        // If a previous session with the same id is still registered (e.g.
+        // browser refresh that reuses sessionStorage), close it gracefully
+        // before we replace it. Two SSE streams for one session id would
+        // double-fire every event to that browser. We also `end()` the old
+        // response so the underlying TCP socket goes away immediately —
+        // without that, the previous `res` lingers in keep-alive state
+        // until the network times it out (minutes), wasting an FD per
+        // refresh.
+        const existing = sessions.get(sessionId);
+        if (existing && !existing.closed) {
+            // Tear down the bus subscription + heartbeat FIRST, then mark
+            // closed, then end the response. Order matters: marking `closed`
+            // before cleanup would make the OS-close handler's own cleanup
+            // short-circuit (it returns early on `closed`), leaking the
+            // subscriber + heartbeat for this session id forever.
+            try {
+                existing.cleanup();
+            }
+            catch (err) {
+                console.warn(`[events] supersede cleanup threw for session=${sessionId}:`, err instanceof Error ? err.message : err);
+            }
+            existing.closed = true;
+            try {
+                if (!existing.res.writableEnded)
+                    existing.res.end();
+            }
+            catch (err) {
+                console.warn(`[events] failed to end superseded SSE response for session=${sessionId}:`, err instanceof Error ? err.message : err);
+            }
+        }
+        const session = {
+            sessionId,
+            userId,
+            focusedWorkspaceId: null,
+            closed: false,
+            res,
+            // Filled in below once `unsubscribe` + `heartbeat` exist.
+            cleanup: () => { },
+        };
+        sessions.set(sessionId, session);
+        const push = (event) => {
+            if (session.closed)
+                return;
+            writeSseEvent(res, event);
+        };
+        const unsubscribe = bus.subscribe({
+            sessionId,
+            userId,
+            getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+            push,
+        });
+        // Replay anything the client missed since their last seen id. Browsers
+        // auto-send `Last-Event-ID` when EventSource reconnects, so this just
+        // works — no client cooperation needed beyond using the standard API.
+        const lastSeenHeader = req.headers['last-event-id'];
+        const lastSeenId = typeof lastSeenHeader === 'string' ? Number(lastSeenHeader) : NaN;
+        if (Number.isFinite(lastSeenId) && lastSeenId > 0) {
+            const replay = bus.replayAfter(lastSeenId, {
+                userId,
+                getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+            });
+            if (replay === null) {
+                // Buffer evicted past `lastSeenId` — client must refetch from
+                // scratch rather than trust a partial replay.
+                writeSseEvent(res, {
+                    id: 0,
+                    ts: new Date().toISOString(),
+                    kind: 'resync',
+                    reason: 'last-event-id too old; ring buffer evicted',
+                });
+            }
+            else {
+                for (const event of replay)
+                    writeSseEvent(res, event);
+            }
+        }
+        const heartbeat = setInterval(() => {
+            if (session.closed)
+                return;
+            // SSE comments start with `:` and are ignored by the EventSource
+            // parser. Cheapest possible keep-alive payload.
+            res.write(': heartbeat\n\n');
+        }, HEARTBEAT_INTERVAL_MS);
+        const cleanup = () => {
+            if (session.closed)
+                return;
+            session.closed = true;
+            clearInterval(heartbeat);
+            unsubscribe();
+            // Only delete if we're still the registered session — a reconnect
+            // for the same id may have already replaced us.
+            if (sessions.get(sessionId) === session) {
+                sessions.delete(sessionId);
+            }
+        };
+        session.cleanup = cleanup;
+        res.on('close', cleanup);
+        res.on('error', cleanup);
+        console.log(`[events] open session=${sessionId} user=${userId} subscribers=${bus.size()}`);
+    });
+    router.post('/events/:sessionId/focus', authMiddleware, express.json(), (req, res) => {
+        const sessionId = String(req.params.sessionId ?? '');
+        const userId = req.userId;
+        if (!sessionId) {
+            res.status(400).json({ error: 'sessionId is required' });
+            return;
+        }
+        const session = sessions.get(sessionId);
+        if (!session || session.closed) {
+            // 404 is the cleanest signal — the client should open a new SSE
+            // stream and POST focus again on success. (Browser EventSource
+            // auto-reconnects, so this should be rare in practice.)
+            res.status(404).json({ error: 'Session not found' });
+            return;
+        }
+        if (session.userId !== userId) {
+            // Hard 403 — a user must never be able to set focus on another
+            // user's session, which would let them mirror that user's events
+            // into their own connection. Belt-and-braces; cookie auth already
+            // gates which userId reaches this handler.
+            res.status(403).json({ error: 'Session belongs to another user' });
+            return;
+        }
+        const { workspaceId } = (req.body ?? {});
+        if (typeof workspaceId !== 'string' || workspaceId.length === 0) {
+            res.status(400).json({ error: 'workspaceId is required in body' });
+            return;
+        }
+        const previous = session.focusedWorkspaceId;
+        session.focusedWorkspaceId = workspaceId;
+        console.log(`[events] FOCUS session=${sessionId} user=${userId} ${previous ?? '(none)'} → ${workspaceId}`);
+        res.json({ status: 'ok', focusedWorkspaceId: workspaceId });
+    });
+    return router;
+}
+/**
+ * Serialise `event` into the SSE wire format. Each frame is:
+ *
+ *   id: <event.id>
+ *   data: <JSON payload>
+ *   \n
+ *
+ * The `id` field is what the browser's EventSource exposes as
+ * `event.lastEventId` and re-sends as `Last-Event-ID` on reconnect.
+ * Data is a single line of JSON — never embedded newlines, which would
+ * break the SSE parser. JSON.stringify guarantees that.
+ */
+function writeSseEvent(res, event) {
+    res.write(`id: ${event.id}\n`);
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+/** Re-exported so tests / future hooks can construct the response shape. */
+export { writeSseEvent as _writeSseEventForTests };
+//# sourceMappingURL=events.routes.js.map

package/dist/modules/workflow/events.routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.routes.js","sourceRoot":"","sources":["../../../src/modules/workflow/events.routes.ts"],"names":[],"mappings":"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"}

package/dist/modules/workflow/file-change-notifier.d.ts

@@ -0,0 +1,38 @@
+/**
+ * One in-process notification fired AFTER a set of file changes is committed +
+ * pushed (post-lock-release), so backend services can react to KB writes without
+ * the per-file TTL wait. Distinct from the SSE `WorkflowEventBus`, which fans
+ * scoped events to browser sessions; this is an unscoped, server-side domain hook.
+ *
+ * BATCHED by design: a single-file save emits `paths: [p]`, a batch write
+ * (`LockingFilesystem.writeFiles`, e.g. a bulk node upload) emits ONE event with
+ * every path it committed. Subscribers that do expensive per-event work (the
+ * id-repair rebuilds the id index) handle a whole batch off one rebuild instead
+ * of N back-to-back ones.
+ *
+ * Emitted from the two post-commit chokepoints (`WorkflowService.runPendingCommit`
+ * for single-file writes, `LockingFilesystem.writeFiles` for batches).
+ *
+ * Every listener is invoked inside try/catch — a throwing subscriber must never
+ * fail the commit that triggered it (mirrors the SSE bus's per-subscriber
+ * isolation). Firing is fire-and-forget; a listener that needs to write files
+ * (id-repair) does so on its own, after the locks have already been released.
+ */
+import type { AuthUser } from '@bevel-software/platform-shared';
+export interface FilesChange {
+    workspaceId: string;
+    branch: string;
+    /** Workspace-relative paths committed in this change (≥1; sorted for batches). */
+    paths: string[];
+    /** Who the change was committed as — a reacting write (id-repair) acts as the same user. */
+    byUser: AuthUser;
+}
+export type FilesChangedListener = (change: FilesChange) => void;
+export declare class FileChangeNotifier {
+    private readonly listeners;
+    /** Register a listener. Returns an unsubscribe fn. */
+    onFilesChanged(listener: FilesChangedListener): () => void;
+    /** Fan a change out to every listener; isolate + log each so one can't break the commit. */
+    emit(change: FilesChange): void;
+}
+//# sourceMappingURL=file-change-notifier.d.ts.map

package/dist/modules/workflow/file-change-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-change-notifier.d.ts","sourceRoot":"","sources":["../../../src/modules/workflow/file-change-notifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4FAA4F;IAC5F,MAAM,EAAE,QAAQ,CAAC;CAClB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;AAEjE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAE7D,sDAAsD;IACtD,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK1D,4FAA4F;IAC5F,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;CAUhC"}

package/dist/modules/workflow/file-change-notifier.js

@@ -0,0 +1,22 @@
+export class FileChangeNotifier {
+    listeners = new Set();
+    /** Register a listener. Returns an unsubscribe fn. */
+    onFilesChanged(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Fan a change out to every listener; isolate + log each so one can't break the commit. */
+    emit(change) {
+        if (change.paths.length === 0)
+            return;
+        for (const listener of this.listeners) {
+            try {
+                listener(change);
+            }
+            catch (err) {
+                console.error('[file-change] listener threw:', err instanceof Error ? err.message : err);
+            }
+        }
+    }
+}
+//# sourceMappingURL=file-change-notifier.js.map

package/dist/modules/workflow/file-change-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-change-notifier.js","sourceRoot":"","sources":["../../../src/modules/workflow/file-change-notifier.ts"],"names":[],"mappings":"AAiCA,MAAM,OAAO,kBAAkB;IACZ,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE7D,sDAAsD;IACtD,cAAc,CAAC,QAA8B;QAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,4FAA4F;IAC5F,IAAI,CAAC,MAAmB;QACtB,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACtC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,IAAI,CAAC;gBACH,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC3F,CAAC;QACH,CAAC;IACH,CAAC;CACF"}