@reticlehq/server 2.0.1 → 2.2.0

package/dist/journal/journal-recorder.js

@@ -0,0 +1,81 @@
+import { EventAttribution, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
+const DEFAULT_FLUSH_AT = 64;
+/**
+ * Owns action-window attribution and batched, order-preserving journaling — the durable half of the
+ * causal spine, kept out of Session so neither file bloats. Every stamped event is `observe`d: if an
+ * action is active (dispatch→settle), the event is attributed to it (`attribution:"window"` — a time
+ * heuristic, never presented as dataflow truth) and its seq folds into the action's range. Writes are
+ * serialized on one chain so `events.jsonl` never interleaves and an action is always persisted after
+ * the events it closed. Sink writes are best-effort: a failed local journal write must never break the
+ * live session, so errors are swallowed.
+ */
+export class JournalRecorder {
+    #sink;
+    #now;
+    #flushAt;
+    #pending = [];
+    #active;
+    #chain = Promise.resolve();
+    constructor(sink, options) {
+        this.#sink = sink;
+        this.#now = options.now;
+        this.#flushAt = options.flushAt ?? DEFAULT_FLUSH_AT;
+    }
+    /** Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event. */
+    observe(event) {
+        let out = event;
+        const active = this.#active;
+        if (active !== undefined) {
+            out = { ...event, actionId: active.actionId, attribution: EventAttribution.WINDOW };
+            if (typeof event.seq === 'number') {
+                active.seqFrom =
+                    active.seqFrom === undefined ? event.seq : Math.min(active.seqFrom, event.seq);
+                active.seqTo = active.seqTo === undefined ? event.seq : Math.max(active.seqTo, event.seq);
+            }
+        }
+        this.#pending.push(out);
+        if (this.#pending.length >= this.#flushAt)
+            this.#enqueueFlush();
+        return out;
+    }
+    /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
+    beginAction(actionId, tool, args) {
+        this.#active = { actionId, tool, args, tStart: this.#now() };
+    }
+    /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
+    finishAction(effect, settled, settledInMs) {
+        const active = this.#active;
+        if (active === undefined)
+            return;
+        this.#active = undefined;
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId: active.actionId,
+            tool: active.tool,
+            args: active.args,
+            effect,
+            settled,
+            settledInMs,
+            seqRange: active.seqFrom === undefined || active.seqTo === undefined
+                ? undefined
+                : { from: active.seqFrom, to: active.seqTo },
+            tRange: { from: active.tStart, to: this.#now() },
+            at: active.tStart,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain.then(() => this.#sink.appendAction(action)).catch(() => undefined);
+    }
+    /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
+    async flush() {
+        this.#enqueueFlush();
+        await this.#chain;
+    }
+    #enqueueFlush() {
+        if (this.#pending.length === 0)
+            return;
+        const batch = this.#pending;
+        this.#pending = [];
+        this.#chain = this.#chain.then(() => this.#sink.appendEvents(batch)).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=journal-recorder.js.map

package/dist/journal/journal-recorder.js.map

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

package/dist/journal/retention.d.ts

@@ -0,0 +1,21 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+/** Keep at most this many session journals on disk; older ones are pruned by recency. */
+export declare const DEFAULT_SESSION_RETENTION = 20;
+interface DatedDir {
+    name: string;
+    mtimeMs: number;
+}
+/**
+ * Pure: given session dirs with their mtimes, the names to remove so only the `retention` most-recent
+ * remain. Oldest-first. Exported for testing (no IO).
+ */
+export declare function selectPrunable(dirs: readonly DatedDir[], retention: number): string[];
+/**
+ * Bound the journal on disk: keep the `retention` most-recent session directories under
+ * `.reticle/sessions/`, remove the rest by mtime. Never throws — retention is best-effort maintenance,
+ * so a stat/rm failure on one dir (or a missing sessions/ dir) is swallowed, never crashing a session.
+ * Mirrors RunStore's amortized pruning; run on daemon start.
+ */
+export declare function pruneSessions(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
+export {};
+//# sourceMappingURL=retention.d.ts.map

package/dist/journal/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../../src/journal/retention.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAMrF;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,EAAE,EAAE,cAAc,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAkC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/journal/retention.js

@@ -0,0 +1,50 @@
+import { reticleDirPaths, sessionDirPath } from '../project/reticle-dir.js';
+/** Keep at most this many session journals on disk; older ones are pruned by recency. */
+export const DEFAULT_SESSION_RETENTION = 20;
+/**
+ * Pure: given session dirs with their mtimes, the names to remove so only the `retention` most-recent
+ * remain. Oldest-first. Exported for testing (no IO).
+ */
+export function selectPrunable(dirs, retention) {
+    if (dirs.length <= retention)
+        return [];
+    return [...dirs]
+        .sort((a, b) => a.mtimeMs - b.mtimeMs)
+        .slice(0, dirs.length - retention)
+        .map((d) => d.name);
+}
+/**
+ * Bound the journal on disk: keep the `retention` most-recent session directories under
+ * `.reticle/sessions/`, remove the rest by mtime. Never throws — retention is best-effort maintenance,
+ * so a stat/rm failure on one dir (or a missing sessions/ dir) is swallowed, never crashing a session.
+ * Mirrors RunStore's amortized pruning; run on daemon start.
+ */
+export async function pruneSessions(fs, root, retention = DEFAULT_SESSION_RETENTION) {
+    const sessionsDir = reticleDirPaths(root).sessions;
+    let names;
+    try {
+        names = await fs.readdir(sessionsDir);
+    }
+    catch {
+        return; // no sessions dir yet
+    }
+    const dated = [];
+    for (const name of names) {
+        try {
+            const { mtimeMs } = await fs.stat(sessionDirPath(root, name));
+            dated.push({ name, mtimeMs });
+        }
+        catch {
+            /* unstattable entry — skip */
+        }
+    }
+    for (const name of selectPrunable(dated, retention)) {
+        try {
+            await fs.rm(sessionDirPath(root, name));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+//# sourceMappingURL=retention.js.map

package/dist/journal/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/journal/retention.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE5E,yFAAyF;AACzF,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAO5C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAyB,EAAE,SAAiB;IACzE,IAAI,IAAI,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,CAAC,GAAG,IAAI,CAAC;SACb,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;SACrC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACxB,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAkB,EAClB,IAAY,EACZ,YAAoB,yBAAyB;IAE7C,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IACnD,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,sBAAsB;IAChC,CAAC;IACD,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/journal/rollups.d.ts

@@ -0,0 +1,49 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * A route-segment rollup: what happened between two ROUTE_CHANGE events. Aggregated, not raw — the
+ * unit the deviation report compares against an expected envelope. Computed by folding the
+ * journal's events; per the plan's risk note this runs lazily on query rather than threading a
+ * stateful accumulator through the hot write path.
+ */
+export interface SegmentRollup {
+    /** The route (pathname) this segment is on, from its opening ROUTE_CHANGE. Absent for the first. */
+    route?: string;
+    /** Elapsed-ms of the first and last event in the segment. */
+    from: number;
+    to: number;
+    /** Wall span of the segment (to - from). */
+    durationMs: number;
+    /** Distinct attributed actions observed in the segment. */
+    actions: number;
+    /** Network request totals and error count (status >= 400 or ok === false). */
+    net: {
+        total: number;
+        errors: number;
+    };
+    /** console.error + uncaught errors/rejections. */
+    consoleErrors: number;
+    /** Unique state-change paths touched, in first-seen order. */
+    statePathsChanged: string[];
+    /**
+     * WS/SSE frame activity in the segment — on a stream-first app the network story IS the stream story.
+     * Directions: opens (connections), in (server→client), out (client→server). Absent when no streams.
+     */
+    streams?: {
+        frames: number;
+        opened: number;
+        in: number;
+        out: number;
+    };
+    /**
+     * True when a cap dropped events in this segment (a TRUNCATED or transport-overflow event landed in
+     * it). The segment's counts UNDERSTATE reality — the deviation judge must not read a nominal count as
+     * proof, and the envelope should not learn from a truncated sample.
+     */
+    truncated?: boolean;
+}
+/**
+ * Fold an ordered event list into route segments split at each ROUTE_CHANGE. Pure: no clock, no IO —
+ * the events carry their own `t`. The events must be in journal order (seq/t ascending).
+ */
+export declare function computeSegments(events: readonly ReticleEvent[]): SegmentRollup[];
+//# sourceMappingURL=rollups.d.ts.map

package/dist/journal/rollups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollups.d.ts","sourceRoot":"","sources":["../../src/journal/rollups.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,oGAAoG;IACpG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,GAAG,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,kDAAkD;IAClD,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA0CD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,aAAa,EAAE,CAmDhF"}

package/dist/journal/rollups.js

@@ -0,0 +1,83 @@
+import { EventType } from '@reticlehq/core';
+function finalize(acc) {
+    return {
+        ...(acc.route === undefined ? {} : { route: acc.route }),
+        from: acc.from,
+        to: acc.to,
+        durationMs: acc.to - acc.from,
+        actions: acc.actionIds.size,
+        net: { total: acc.netTotal, errors: acc.netErrors },
+        consoleErrors: acc.consoleErrors,
+        statePathsChanged: acc.statePaths,
+        ...(acc.streams.frames === 0 ? {} : { streams: acc.streams }),
+        ...(acc.truncated ? { truncated: true } : {}),
+    };
+}
+function isNetError(event) {
+    const status = event.data['status'];
+    return event.data['ok'] === false || (typeof status === 'number' && status >= 400);
+}
+/**
+ * Fold an ordered event list into route segments split at each ROUTE_CHANGE. Pure: no clock, no IO —
+ * the events carry their own `t`. The events must be in journal order (seq/t ascending).
+ */
+export function computeSegments(events) {
+    const segments = [];
+    let acc;
+    const open = (route, t) => ({
+        ...(route === undefined ? {} : { route }),
+        from: t,
+        to: t,
+        actionIds: new Set(),
+        netTotal: 0,
+        netErrors: 0,
+        consoleErrors: 0,
+        statePaths: [],
+        streams: { frames: 0, opened: 0, in: 0, out: 0 },
+        truncated: false,
+    });
+    for (const event of events) {
+        if (event.type === EventType.ROUTE_CHANGE) {
+            if (acc !== undefined)
+                segments.push(finalize(acc));
+            const pathname = event.data['pathname'];
+            acc = open(typeof pathname === 'string' ? pathname : undefined, event.t);
+            continue;
+        }
+        if (acc === undefined)
+            acc = open(undefined, event.t);
+        acc.to = event.t;
+        if (typeof event.actionId === 'string')
+            acc.actionIds.add(event.actionId);
+        if (event.type === EventType.NET_REQUEST) {
+            acc.netTotal += 1;
+            if (isNetError(event))
+                acc.netErrors += 1;
+        }
+        if (event.type === EventType.CONSOLE_ERROR || event.type === EventType.ERROR_UNCAUGHT) {
+            acc.consoleErrors += 1;
+        }
+        if (event.type === EventType.STATE_CHANGE) {
+            const name = event.data['name'];
+            if (typeof name === 'string' && !acc.statePaths.includes(name))
+                acc.statePaths.push(name);
+        }
+        if (event.type === EventType.NET_STREAM) {
+            acc.streams.frames += 1;
+            const direction = event.data['direction'];
+            if (direction === 'open')
+                acc.streams.opened += 1;
+            else if (direction === 'in')
+                acc.streams.in += 1;
+            else if (direction === 'out')
+                acc.streams.out += 1;
+        }
+        if (event.type === EventType.TRUNCATED || event.type === EventType.TRANSPORT_OVERFLOW) {
+            acc.truncated = true;
+        }
+    }
+    if (acc !== undefined)
+        segments.push(finalize(acc));
+    return segments;
+}
+//# sourceMappingURL=rollups.js.map

package/dist/journal/rollups.js.map

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

package/dist/journal/session-end.d.ts

@@ -0,0 +1,32 @@
+import type { AmbientCounts } from './ambient.js';
+import type { FileSystemPort } from '../project/fs-port.js';
+/**
+ * Session teardown: the durable half of ending a session. Two things must happen when a tab disconnects,
+ * and neither did before — the journal batches events and only writes at its flush threshold, so the tail
+ * of every session (< one batch) was silently lost from disk, and the learned ambient map was never
+ * persisted at all, so every session re-learned the page's churn from zero.
+ *
+ * Both are best-effort: a teardown failure must never surface as a session error (the tab is already gone).
+ */
+/** The minimal Session surface teardown needs (Session satisfies it structurally). */
+export interface SessionEndTarget {
+    readonly id: string;
+    /** Write any batched journal events to disk. */
+    flushJournal(): Promise<void>;
+    /** The ambient-churn counts learned during this session. */
+    ambientCounts(): AmbientCounts;
+    ownAmbientCounts(): AmbientCounts;
+}
+export interface SessionEndDeps {
+    fs: FileSystemPort;
+    reticleRoot: string;
+    /** Journaling/persistence off (opt-out) → teardown is a no-op. */
+    enabled: boolean;
+}
+/**
+ * Build the teardown handler the bridge fires when a session is removed. Flushes the journal first (so no
+ * evidence is lost), then folds this session's ambient counts into the persisted map so the NEXT session
+ * starts already knowing which regions churn.
+ */
+export declare function makeSessionEnd(deps: SessionEndDeps): (session: SessionEndTarget) => Promise<void>;
+//# sourceMappingURL=session-end.d.ts.map

package/dist/journal/session-end.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-end.d.ts","sourceRoot":"","sources":["../../src/journal/session-end.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG5D;;;;;;;GAOG;AAEH,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,4DAA4D;IAC5D,aAAa,IAAI,aAAa,CAAC;IAC/B,gBAAgB,IAAI,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,cAAc,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAuCjG"}

package/dist/journal/session-end.js

@@ -0,0 +1,52 @@
+import { AmbientStore } from './ambient-store.js';
+import { pruneSessions } from './retention.js';
+/**
+ * Build the teardown handler the bridge fires when a session is removed. Flushes the journal first (so no
+ * evidence is lost), then folds this session's ambient counts into the persisted map so the NEXT session
+ * starts already knowing which regions churn.
+ */
+export function makeSessionEnd(deps) {
+    return async (session) => {
+        if (!deps.enabled)
+            return;
+        try {
+            await session.flushJournal();
+        }
+        catch {
+            // a failed flush must not block ambient persistence, and must never throw at teardown
+        }
+        try {
+            const store = new AmbientStore(deps.fs, deps.reticleRoot);
+            const persisted = await store.load();
+            // Accumulate history + what is NEW. `ownAmbientCounts` excludes the map this session was
+            // seeded from at startup; `ambientCounts` includes it, and adding that onto `persisted` wrote
+            // `2 x persisted + own` on every teardown — a doubling per session that had driven the
+            // committed map to ~9.1e23.
+            const merged = { ...persisted };
+            for (const [ref, count] of Object.entries(session.ownAmbientCounts())) {
+                merged[ref] = (merged[ref] ?? 0) + count;
+            }
+            await store.save(merged);
+        }
+        catch {
+            // ambient learning is an optimization; a disk failure never breaks teardown
+        }
+        try {
+            // Bound the journal on disk HERE, not only at daemon start.
+            //
+            // Pruning ran exactly once, during wiring. A daemon that stays up — which is the normal case for
+            // a dev session, and the whole point of the pool — therefore never pruned again, so session
+            // directories accumulated without bound for as long as it lived. Session end is the right moment
+            // because it is precisely when a new directory has just been created, which makes this amortized
+            // rather than periodic (no timer to leak) and mirrors what RunStore already does.
+            //
+            // Safe against deleting the session that just ended: pruning selects the OLDEST by mtime, and the
+            // directory written moments ago is the newest.
+            await pruneSessions(deps.fs, deps.reticleRoot);
+        }
+        catch {
+            // retention is best-effort maintenance; never surface at teardown
+        }
+    };
+}
+//# sourceMappingURL=session-end.js.map

package/dist/journal/session-end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-end.js","sourceRoot":"","sources":["../../src/journal/session-end.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AA4B/C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAoB;IACjD,OAAO,KAAK,EAAE,OAAO,EAAE,EAAE;QACvB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,sFAAsF;QACxF,CAAC;QACD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YAC1D,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;YACrC,yFAAyF;YACzF,8FAA8F;YAC9F,uFAAuF;YACvF,4BAA4B;YAC5B,MAAM,MAAM,GAAkB,EAAE,GAAG,SAAS,EAAE,CAAC;YAC/C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,EAAE,CAAC;gBACtE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;YAC3C,CAAC;YACD,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,4EAA4E;QAC9E,CAAC;QACD,IAAI,CAAC;YACH,4DAA4D;YAC5D,EAAE;YACF,iGAAiG;YACjG,4FAA4F;YAC5F,iGAAiG;YACjG,iGAAiG;YACjG,kFAAkF;YAClF,EAAE;YACF,kGAAkG;YAClG,+CAA+C;YAC/C,MAAM,aAAa,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;QACpE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/journal/session-journal.d.ts

@@ -0,0 +1,25 @@
+import { type JournalAction, type ReticleEvent } from '@reticlehq/core';
+import type { FileSystemPort } from '../project/fs-port.js';
+/**
+ * The durable per-session journal: append-only JSONL for events and actions, the ledger the ring
+ * buffer becomes a hot cache over. Writes are batched (the caller flushes ring-buffer windows), so a
+ * batch is one syscall — not one per event. Reads never throw: a missing file is `[]`, a malformed or
+ * schema-invalid line is skipped, matching the never-throw discipline of the run store.
+ *
+ * Events are already browser-edge-redacted (network/storage/DOM) before they reach the wire, so the
+ * journal stores redacted payloads; the ledger is local-only. A server-side second-pass event redactor
+ * is defense-in-depth for a later commit, not a correctness gate here.
+ *
+ * ponytail: append-per-batch, no retention yet. Bounded-disk pruning (cap session dirs / file size,
+ * "pruned like runs/") is a dedicated follow-up — see the build ledger. Perf ceiling: if the <3%
+ * main-thread overhead budget is threatened at high event rates, coalesce batches behind a flush timer.
+ */
+export declare class SessionJournal {
+    #private;
+    constructor(fs: FileSystemPort, root: string, sessionId: string);
+    appendEvents(events: readonly ReticleEvent[]): Promise<void>;
+    appendAction(action: JournalAction): Promise<void>;
+    readEvents(): Promise<ReticleEvent[]>;
+    readActions(): Promise<JournalAction[]>;
+}
+//# sourceMappingURL=session-journal.d.ts.map

package/dist/journal/session-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-journal.d.ts","sourceRoot":"","sources":["../../src/journal/session-journal.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAQ5D;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;;gBAeb,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IASzD,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlD,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IA0ErC,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;CAiC9C"}

package/dist/journal/session-journal.js

@@ -0,0 +1,168 @@
+import { JournalActionSchema, ReticleEventSchema, } from '@reticlehq/core';
+import { isValidSessionId, journalActionsPath, journalEventsPath, sessionDirPath, } from '../project/reticle-dir.js';
+/**
+ * The durable per-session journal: append-only JSONL for events and actions, the ledger the ring
+ * buffer becomes a hot cache over. Writes are batched (the caller flushes ring-buffer windows), so a
+ * batch is one syscall — not one per event. Reads never throw: a missing file is `[]`, a malformed or
+ * schema-invalid line is skipped, matching the never-throw discipline of the run store.
+ *
+ * Events are already browser-edge-redacted (network/storage/DOM) before they reach the wire, so the
+ * journal stores redacted payloads; the ledger is local-only. A server-side second-pass event redactor
+ * is defense-in-depth for a later commit, not a correctness gate here.
+ *
+ * ponytail: append-per-batch, no retention yet. Bounded-disk pruning (cap session dirs / file size,
+ * "pruned like runs/") is a dedicated follow-up — see the build ledger. Perf ceiling: if the <3%
+ * main-thread overhead budget is threatened at high event rates, coalesce batches behind a flush timer.
+ */
+export class SessionJournal {
+    #fs;
+    #root;
+    #sessionId;
+    #dirEnsured = false;
+    // Parse-cache for the append-only EVENTS journal. queryEvents falls through to readEvents on every
+    // observe/network/console call once the ring buffer has evicted (permanent ~60s into any session), so
+    // a naive readEvents re-read + re-JSON.parse + re-zod-validated the WHOLE file each time — measured at
+    // a 1-hour 100 ev/s session as ~1.5s CPU + ~300MB transient heap PER tool call, growing with age. The
+    // journal only ever grows and is always a run of complete '\n'-terminated lines, so we keep the parsed
+    // events and the char count already consumed, and parse only the tail written since the last read.
+    #eventCache;
+    #eventCharsConsumed = 0; // fallback (whole-file) path: UTF-16 code units consumed
+    #eventBytesConsumed = 0; // fast (bounded-read) path: UTF-8 bytes consumed, always at a '\n' boundary
+    constructor(fs, root, sessionId) {
+        if (!isValidSessionId(sessionId)) {
+            throw new Error(`refusing to journal an unsafe session id: ${sessionId}`);
+        }
+        this.#fs = fs;
+        this.#root = root;
+        this.#sessionId = sessionId;
+    }
+    async appendEvents(events) {
+        if (events.length === 0)
+            return;
+        await this.#ensureDir();
+        const text = `${events.map((e) => JSON.stringify(e)).join('\n')}\n`;
+        await this.#fs.appendFile(journalEventsPath(this.#root, this.#sessionId), text);
+    }
+    async appendAction(action) {
+        await this.#ensureDir();
+        await this.#fs.appendFile(journalActionsPath(this.#root, this.#sessionId), `${JSON.stringify(action)}\n`);
+    }
+    async readEvents() {
+        const path = journalEventsPath(this.#root, this.#sessionId);
+        if (this.#eventCache === undefined)
+            this.#eventCache = [];
+        // Fast path: read only the BYTES appended since the last read, so cost tracks the tail, not the
+        // whole (unboundedly growing) file. Falls back to a whole-file read for a FileSystemPort that omits
+        // readFileFrom (test stubs).
+        const readFrom = this.#fs.readFileFrom?.bind(this.#fs);
+        if (readFrom !== undefined) {
+            let chunk;
+            try {
+                chunk = await readFrom(path, this.#eventBytesConsumed);
+            }
+            catch (error) {
+                if (this.#fs.isNotFound(error))
+                    return this.#eventCache.slice();
+                throw error;
+            }
+            // Shrink/rotation guard (not done today): if the file is smaller than what we consumed, the offset
+            // is meaningless — reset and re-read from 0.
+            if (chunk.size < this.#eventBytesConsumed) {
+                this.#eventCache = [];
+                this.#eventBytesConsumed = 0;
+                chunk = await readFrom(path, 0);
+            }
+            this.#eventBytesConsumed += this.#ingestTail(chunk.text);
+            return this.#eventCache.slice();
+        }
+        let text;
+        try {
+            text = await this.#fs.readFile(path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return this.#eventCache.slice();
+            throw error;
+        }
+        // Fallback (whole-file) path: #eventCharsConsumed is a UTF-16 offset into the whole text. Shrink
+        // guard, then ingest the un-consumed tail up to its last newline (see #ingestTail for the
+        // partial-line rationale).
+        if (text.length < this.#eventCharsConsumed) {
+            this.#eventCache = [];
+            this.#eventCharsConsumed = 0;
+        }
+        const end = text.lastIndexOf('\n') + 1;
+        if (end > this.#eventCharsConsumed) {
+            this.#ingestTail(text.slice(this.#eventCharsConsumed, end));
+            this.#eventCharsConsumed = end;
+        }
+        return this.#eventCache.slice();
+    }
+    /**
+     * Parse complete ('\n'-terminated) JSON event lines from `tail` into #eventCache, stopping at the LAST
+     * newline. A concurrent append can be observed mid-record (reads and writes run on separate libuv
+     * threads), and consuming a partial trailing line would splice its tail onto the next read's head, fail
+     * to parse, and drop that event forever — so the partial tail is left for the next read. Returns the
+     * UTF-8 BYTES consumed, which the bounded-read path uses to advance its byte offset.
+     */
+    #ingestTail(tail) {
+        const cache = this.#eventCache ?? (this.#eventCache = []);
+        const end = tail.lastIndexOf('\n') + 1;
+        if (end === 0)
+            return 0; // no complete line yet
+        const complete = tail.slice(0, end);
+        for (const line of complete.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const result = ReticleEventSchema.safeParse(parsed);
+            if (result.success)
+                cache.push(result.data);
+        }
+        return Buffer.byteLength(complete, 'utf8');
+    }
+    async readActions() {
+        return this.#readLines(journalActionsPath(this.#root, this.#sessionId), JournalActionSchema);
+    }
+    async #ensureDir() {
+        if (this.#dirEnsured)
+            return;
+        await this.#fs.mkdir(sessionDirPath(this.#root, this.#sessionId));
+        this.#dirEnsured = true;
+    }
+    async #readLines(path, schema) {
+        let text;
+        try {
+            text = await this.#fs.readFile(path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return [];
+            throw error;
+        }
+        const out = [];
+        for (const line of text.split('\n')) {
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const result = schema.safeParse(parsed);
+            // Validated at this boundary; ZodTypeAny widens `.data` to any, so re-narrow to the schema output.
+            if (result.success)
+                out.push(result.data);
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=session-journal.js.map

package/dist/journal/session-journal.js.map

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

package/dist/license/license.d.ts

@@ -1,6 +1,6 @@
 /**
  * Enterprise license-key verification + the assertEnterprise gate. ENTERPRISE CODE (Reticle Enterprise
- * License — see ./LICENSE), not the FSL that covers the rest of the server.
+ * License — see./LICENSE), not the FSL that covers the rest of the server.
  *
  * Offline + no phone-home (preserves the no-telemetry brand): a key is a signed payload Reticle issues
  * with its private key; this verifies it against the issuer's PUBLIC key with Ed25519. Dev/eval is a
@@ -100,8 +100,13 @@ interface LicenseReport {
  */
 export declare function describeLicense(now: number, env?: NodeJS.ProcessEnv, baked?: string): LicenseReport;
 /**
- * Gate an enterprise feature using env-resolved activation. Enforcement is ON only when the issuer
- * public key is configured (i.e. a real release); without it (dev/repo) features run free in eval mode.
+ * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key
+ * is configured (a real release). Without it, behaviour splits on runtime:
+ *  - dev/eval (NODE_ENV ≠ production): features run FREE — never blocks a contributor or CI.
+ *  - production (NODE_ENV = production): FAIL CLOSED — a release that reaches production with no
+ *    resolvable issuer key was mis-built (the baked key wasn't stamped in, BAKED_ISSUER_PUBLIC_KEY_PEM
+ *    is still ''), and silently unlocking every ee feature with no key and no warning is the worst
+ *    outcome. Deny instead, with a distinct reason so the misconfiguration is obvious.
  */
 export declare function assertEnterpriseFromEnv(feature: string, now: number, env?: NodeJS.ProcessEnv, baked?: string): void;
 export {};