@reticlehq/server 2.1.0 → 2.2.0

package/dist/journal/deviation-report.js

@@ -0,0 +1,54 @@
+import { compareSegment, MIN_ENVELOPE_SAMPLES, } from './envelope.js';
+function headlineFor(report) {
+    const truncNote = report.truncatedSegments > 0
+        ? ` (${String(report.truncatedSegments)} truncated — counts partial)`
+        : '';
+    if (report.insufficientSamples) {
+        return `envelope too new (need ${String(MIN_ENVELOPE_SAMPLES)} runs) — see causal summary${truncNote}`;
+    }
+    if (report.deviations.length === 0) {
+        const s = report.nominalSegments === 1 ? '' : 's';
+        return `${String(report.nominalSegments)} segment${s} nominal${truncNote}`;
+    }
+    const routes = [...new Set(report.deviations.map((d) => d.route))].join(', ');
+    const n = report.deviations.length;
+    return `${String(n)} deviation${n === 1 ? '' : 's'}: ${routes}${truncNote}`;
+}
+/**
+ * Judge observed segments against their per-route envelopes. Segments without a route, or whose
+ * envelope is too green, are counted as unjudged rather than silently passed.
+ */
+export function buildDeviationReport(envelopes, segments, zThreshold) {
+    const deviations = [];
+    let judged = 0;
+    let nominal = 0;
+    let truncated = 0;
+    for (const segment of segments) {
+        if (segment.route === undefined)
+            continue;
+        // A truncated segment's counts understate reality — judging it could read a false "nominal".
+        if (segment.truncated === true) {
+            truncated += 1;
+            continue;
+        }
+        const envelope = envelopes.get(segment.route);
+        if (envelope === undefined || envelope.samples < MIN_ENVELOPE_SAMPLES)
+            continue;
+        judged += 1;
+        const segDeviations = compareSegment(envelope, segment, zThreshold);
+        if (segDeviations.length === 0)
+            nominal += 1;
+        else
+            deviations.push(...segDeviations);
+    }
+    deviations.sort((a, b) => b.z - a.z);
+    const base = {
+        deviations,
+        nominalSegments: nominal,
+        judgedSegments: judged,
+        truncatedSegments: truncated,
+        insufficientSamples: judged === 0,
+    };
+    return { ...base, headline: headlineFor(base) };
+}
+//# sourceMappingURL=deviation-report.js.map

package/dist/journal/deviation-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviation-report.js","sourceRoot":"","sources":["../../src/journal/deviation-report.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EAGd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAuBvB,SAAS,WAAW,CAAC,MAAyC;IAC5D,MAAM,SAAS,GACb,MAAM,CAAC,iBAAiB,GAAG,CAAC;QAC1B,CAAC,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,8BAA8B;QACrE,CAAC,CAAC,EAAE,CAAC;IACT,IAAI,MAAM,CAAC,mBAAmB,EAAE,CAAC;QAC/B,OAAO,0BAA0B,MAAM,CAAC,oBAAoB,CAAC,8BAA8B,SAAS,EAAE,CAAC;IACzG,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,MAAM,CAAC,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAClD,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,WAAW,SAAS,EAAE,CAAC;IAC7E,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;IACnC,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,MAAM,GAAG,SAAS,EAAE,CAAC;AAC9E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA6C,EAC7C,QAAkC,EAClC,UAAmB;IAEnB,MAAM,UAAU,GAAgB,EAAE,CAAC;IACnC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;YAAE,SAAS;QAC1C,6FAA6F;QAC7F,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC/B,SAAS,IAAI,CAAC,CAAC;YACf,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,OAAO,GAAG,oBAAoB;YAAE,SAAS;QAChF,MAAM,IAAI,CAAC,CAAC;QACZ,MAAM,aAAa,GAAG,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QACpE,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC;;YACxC,UAAU,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IACzC,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG;QACX,UAAU;QACV,eAAe,EAAE,OAAO;QACxB,cAAc,EAAE,MAAM;QACtB,iBAAiB,EAAE,SAAS;QAC5B,mBAAmB,EAAE,MAAM,KAAK,CAAC;KAClC,CAAC;IACF,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;AAClD,CAAC"}

package/dist/journal/deviation-service.d.ts

@@ -0,0 +1,12 @@
+import type { EnvelopeStore } from './envelope-store.js';
+import { type DeviationReport } from './deviation-report.js';
+import type { SegmentRollup } from './rollups.js';
+/**
+ * The accumulate-and-compare loop behind the push default. Given the segments a drive/replay produced:
+ * judge them against the envelopes learned from PAST runs, then fold them in so the baseline sharpens
+ * over time. Order matters — compare first, learn second — so a run never grades itself against a
+ * baseline it just polluted. Below MIN_ENVELOPE_SAMPLES the report says insufficientSamples and the
+ * caller shows the causal summary instead.
+ */
+export declare function reportAndAccumulate(store: EnvelopeStore, segments: readonly SegmentRollup[], zThreshold?: number): Promise<DeviationReport>;
+//# sourceMappingURL=deviation-service.d.ts.map

package/dist/journal/deviation-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviation-service.d.ts","sourceRoot":"","sources":["../../src/journal/deviation-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CAkB1B"}

package/dist/journal/deviation-service.js

@@ -0,0 +1,32 @@
+import { addSegmentToEnvelope, emptyEnvelope } from './envelope.js';
+import { buildDeviationReport } from './deviation-report.js';
+import { withFileLock } from '../project/file-lock.js';
+/**
+ * The accumulate-and-compare loop behind the push default. Given the segments a drive/replay produced:
+ * judge them against the envelopes learned from PAST runs, then fold them in so the baseline sharpens
+ * over time. Order matters — compare first, learn second — so a run never grades itself against a
+ * baseline it just polluted. Below MIN_ENVELOPE_SAMPLES the report says insufficientSamples and the
+ * caller shows the causal summary instead.
+ */
+export async function reportAndAccumulate(store, segments, zThreshold) {
+    // Serialized per file: the compare-then-learn read-modify-write runs concurrently under parallel
+    // flow_verify. Without the lock, two runs load the same baseline and the later save drops the other's
+    // learned segments (and could grade against a half-updated baseline). "Compare first, learn second"
+    // only holds within one holder of the lock.
+    return withFileLock(store.path, async () => {
+        const envelopes = await store.load();
+        const report = buildDeviationReport(envelopes, segments, zThreshold);
+        for (const segment of segments) {
+            if (segment.route === undefined)
+                continue;
+            // Never learn from a truncated sample — its understated counts would poison the baseline.
+            if (segment.truncated === true)
+                continue;
+            const current = envelopes.get(segment.route) ?? emptyEnvelope(segment.route);
+            envelopes.set(segment.route, addSegmentToEnvelope(current, segment));
+        }
+        await store.save(envelopes);
+        return report;
+    });
+}
+//# sourceMappingURL=deviation-service.js.map

package/dist/journal/deviation-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviation-service.js","sourceRoot":"","sources":["../../src/journal/deviation-service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAwB,MAAM,uBAAuB,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAoB,EACpB,QAAkC,EAClC,UAAmB;IAEnB,iGAAiG;IACjG,sGAAsG;IACtG,oGAAoG;IACpG,4CAA4C;IAC5C,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;QACzC,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACrE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;gBAAE,SAAS;YAC1C,0FAA0F;YAC1F,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI;gBAAE,SAAS;YACzC,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YAC7E,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,oBAAoB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/journal/envelope-store.d.ts

@@ -0,0 +1,19 @@
+import type { FileSystemPort } from '../project/fs-port.js';
+import { type RouteEnvelope } from './envelope.js';
+/** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
+export declare const ENVELOPE_FILE_VERSION = 1;
+/**
+ * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
+ * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
+ * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
+ * report just falls back to the causal summary until the envelope rebuilds.
+ */
+export declare class EnvelopeStore {
+    #private;
+    constructor(fs: FileSystemPort, root: string);
+    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
+    get path(): string;
+    load(): Promise<Map<string, RouteEnvelope>>;
+    save(envelopes: ReadonlyMap<string, RouteEnvelope>): Promise<void>;
+}
+//# sourceMappingURL=envelope-store.d.ts.map

package/dist/journal/envelope-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-store.d.ts","sourceRoot":"","sources":["../../src/journal/envelope-store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAExE,4GAA4G;AAC5G,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAOvC;;;;;GAKG;AACH,qBAAa,aAAa;;gBAIZ,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM;IAK5C,oGAAoG;IACpG,IAAI,IAAI,IAAI,MAAM,CAEjB;IAEK,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAmB3C,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAUzE"}

package/dist/journal/envelope-store.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { dirname } from 'node:path';
+import { reticleDirPaths } from '../project/reticle-dir.js';
+import { RouteEnvelopeSchema } from './envelope.js';
+/** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
+export const ENVELOPE_FILE_VERSION = 1;
+const EnvelopeFileSchema = z.object({
+    version: z.literal(ENVELOPE_FILE_VERSION),
+    routes: z.record(RouteEnvelopeSchema),
+});
+/**
+ * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
+ * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
+ * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
+ * report just falls back to the causal summary until the envelope rebuilds.
+ */
+export class EnvelopeStore {
+    #fs;
+    #path;
+    constructor(fs, root) {
+        this.#fs = fs;
+        this.#path = reticleDirPaths(root).envelopes;
+    }
+    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
+    get path() {
+        return this.#path;
+    }
+    async load() {
+        let text;
+        try {
+            text = await this.#fs.readFile(this.#path);
+        }
+        catch (error) {
+            if (this.#fs.isNotFound(error))
+                return new Map();
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return new Map();
+        }
+        const result = EnvelopeFileSchema.safeParse(parsed);
+        if (!result.success)
+            return new Map();
+        return new Map(Object.entries(result.data.routes));
+    }
+    async save(envelopes) {
+        await this.#fs.mkdir(dirname(this.#path));
+        const routes = {};
+        for (const [route, envelope] of envelopes)
+            routes[route] = envelope;
+        const body = `${JSON.stringify({ version: ENVELOPE_FILE_VERSION, routes }, null, 2)}\n`;
+        // Atomic publish: write a temp sibling then rename, so a crash never leaves a half-written baseline.
+        const tmp = `${this.#path}.tmp`;
+        await this.#fs.writeFile(tmp, body);
+        await this.#fs.rename(tmp, this.#path);
+    }
+}
+//# sourceMappingURL=envelope-store.js.map

package/dist/journal/envelope-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-store.js","sourceRoot":"","sources":["../../src/journal/envelope-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAsB,MAAM,eAAe,CAAC;AAExE,4GAA4G;AAC5G,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC;CACtC,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IACf,GAAG,CAAiB;IACpB,KAAK,CAAS;IAEvB,YAAY,EAAkB,EAAE,IAAY;QAC1C,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC;IAC/C,CAAC;IAED,oGAAoG;IACpG,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,GAAG,EAAE,CAAC;YACjD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,IAAI,GAAG,EAAE,CAAC;QACtC,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,SAA6C;QACtD,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAkC,EAAE,CAAC;QACjD,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,SAAS;YAAE,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,CAAC;QACpE,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;QACxF,qGAAqG;QACrG,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,MAAM,CAAC;QAChC,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACpC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/journal/envelope.d.ts

@@ -0,0 +1,232 @@
+import { z } from 'zod';
+import type { SegmentRollup } from './rollups.js';
+/**
+ * The expected-envelope model — the OSS statistical engine behind the deviation report. Per-metric
+ * running stats (Welford, so we never store every sample) accumulate across runs of the same route;
+ * a new segment is compared against them and flagged when a metric runs high. The *math* is open; the
+ * fleet-calibrated thresholds are the paid layer (see OSS-VS-SERVER). We only flag INCREASES
+ * (slower, more errors, more requests) — a segment doing less than expected is not a regression.
+ */
+/** Online mean/variance/max for one metric (Welford's algorithm). Immutable: addStat returns a copy. */
+export interface MetricStats {
+    count: number;
+    mean: number;
+    /** Sum of squared deviations (Welford M2); variance = m2/(count-1). */
+    m2: number;
+    max: number;
+}
+export declare function emptyStats(): MetricStats;
+export declare function addStat(stats: MetricStats, x: number): MetricStats;
+export declare function stddev(stats: MetricStats): number;
+/** How many stddevs above the mean `x` sits (0 when there's no spread yet). */
+export declare function zScore(stats: MetricStats, x: number): number;
+/** The metrics an envelope tracks per route. */
+export declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
+export type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
+export interface RouteEnvelope {
+    route: string;
+    /** Runs that contributed a sample — below MIN_ENVELOPE_SAMPLES the envelope is too green to judge. */
+    samples: number;
+    stats: Record<EnvelopeMetric, MetricStats>;
+}
+/** Below this, an envelope is noise — the deviation report falls back to the causal summary. */
+export declare const MIN_ENVELOPE_SAMPLES = 3;
+/** Default flag threshold in stddevs. The number is a placeholder for fleet-calibrated priors. */
+export declare const DEFAULT_Z_THRESHOLD = 3;
+/** Persisted shape of a route envelope. Validated on load; a bad file degrades to no envelope. */
+export declare const RouteEnvelopeSchema: z.ZodObject<{
+    route: z.ZodString;
+    samples: z.ZodNumber;
+    stats: z.ZodObject<{
+        durationMs: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        net: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        netErrors: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        consoleErrors: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    }, {
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    route: string;
+    samples: number;
+    stats: {
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    };
+}, {
+    route: string;
+    samples: number;
+    stats: {
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    };
+}>;
+export declare function emptyEnvelope(route: string): RouteEnvelope;
+/** Fold one observed segment into the envelope as a new sample. */
+export declare function addSegmentToEnvelope(envelope: RouteEnvelope, segment: SegmentRollup): RouteEnvelope;
+/** One metric of one segment running abnormally high against its envelope. */
+export interface Deviation {
+    route: string;
+    metric: EnvelopeMetric;
+    observed: number;
+    expectedMean: number;
+    z: number;
+}
+/**
+ * Compare a segment against its envelope. Returns the metrics running high (z above threshold),
+ * ranked most-severe first. Empty when the envelope is too green (< MIN_ENVELOPE_SAMPLES) — the caller
+ * falls back to the causal summary in that case.
+ */
+export declare function compareSegment(envelope: RouteEnvelope, segment: SegmentRollup, zThreshold?: number): Deviation[];
+//# sourceMappingURL=envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/journal/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;GAMG;AAEH,wGAAwG;AACxG,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,UAAU,IAAI,WAAW,CAExC;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW,CAMlE;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAEjD;AAED,+EAA+E;AAC/E,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED,gDAAgD;AAChD,eAAO,MAAM,gBAAgB,8DAA+D,CAAC;AAC7F,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;CAC5C;AAED,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,kGAAkG;AAClG,eAAO,MAAM,mBAAmB,IAAI,CAAC;AASrC,kGAAkG;AAClG,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS9B,CAAC;AAEH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAW1D;AAeD,mEAAmE;AACnE,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,aAAa,GACrB,aAAa,CAMf;AAED,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,aAAa,EACtB,UAAU,GAAE,MAA4B,GACvC,SAAS,EAAE,CAYb"}

package/dist/journal/envelope.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+export function emptyStats() {
+    return { count: 0, mean: 0, m2: 0, max: 0 };
+}
+export function addStat(stats, x) {
+    const count = stats.count + 1;
+    const delta = x - stats.mean;
+    const mean = stats.mean + delta / count;
+    const m2 = stats.m2 + delta * (x - mean);
+    return { count, mean, m2, max: Math.max(stats.max, x) };
+}
+export function stddev(stats) {
+    return stats.count < 2 ? 0 : Math.sqrt(stats.m2 / (stats.count - 1));
+}
+/** How many stddevs above the mean `x` sits (0 when there's no spread yet). */
+export function zScore(stats, x) {
+    const sd = stddev(stats);
+    return sd === 0 ? 0 : (x - stats.mean) / sd;
+}
+/** The metrics an envelope tracks per route. */
+export const ENVELOPE_METRICS = ['durationMs', 'net', 'netErrors', 'consoleErrors'];
+/** Below this, an envelope is noise — the deviation report falls back to the causal summary. */
+export const MIN_ENVELOPE_SAMPLES = 3;
+/** Default flag threshold in stddevs. The number is a placeholder for fleet-calibrated priors. */
+export const DEFAULT_Z_THRESHOLD = 3;
+const MetricStatsSchema = z.object({
+    count: z.number(),
+    mean: z.number(),
+    m2: z.number(),
+    max: z.number(),
+});
+/** Persisted shape of a route envelope. Validated on load; a bad file degrades to no envelope. */
+export const RouteEnvelopeSchema = z.object({
+    route: z.string(),
+    samples: z.number().int().min(0),
+    stats: z.object({
+        durationMs: MetricStatsSchema,
+        net: MetricStatsSchema,
+        netErrors: MetricStatsSchema,
+        consoleErrors: MetricStatsSchema,
+    }),
+});
+export function emptyEnvelope(route) {
+    return {
+        route,
+        samples: 0,
+        stats: {
+            durationMs: emptyStats(),
+            net: emptyStats(),
+            netErrors: emptyStats(),
+            consoleErrors: emptyStats(),
+        },
+    };
+}
+function metricValue(segment, metric) {
+    switch (metric) {
+        case 'durationMs':
+            return segment.durationMs;
+        case 'net':
+            return segment.net.total;
+        case 'netErrors':
+            return segment.net.errors;
+        case 'consoleErrors':
+            return segment.consoleErrors;
+    }
+}
+/** Fold one observed segment into the envelope as a new sample. */
+export function addSegmentToEnvelope(envelope, segment) {
+    const stats = { ...envelope.stats };
+    for (const metric of ENVELOPE_METRICS) {
+        stats[metric] = addStat(stats[metric], metricValue(segment, metric));
+    }
+    return { route: envelope.route, samples: envelope.samples + 1, stats };
+}
+/**
+ * Compare a segment against its envelope. Returns the metrics running high (z above threshold),
+ * ranked most-severe first. Empty when the envelope is too green (< MIN_ENVELOPE_SAMPLES) — the caller
+ * falls back to the causal summary in that case.
+ */
+export function compareSegment(envelope, segment, zThreshold = DEFAULT_Z_THRESHOLD) {
+    if (envelope.samples < MIN_ENVELOPE_SAMPLES)
+        return [];
+    const deviations = [];
+    for (const metric of ENVELOPE_METRICS) {
+        const stats = envelope.stats[metric];
+        const observed = metricValue(segment, metric);
+        const z = zScore(stats, observed);
+        if (z > zThreshold) {
+            deviations.push({ route: envelope.route, metric, observed, expectedMean: stats.mean, z });
+        }
+    }
+    return deviations.sort((a, b) => b.z - a.z);
+}
+//# sourceMappingURL=envelope.js.map

package/dist/journal/envelope.js.map

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

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

@@ -0,0 +1,20 @@
+import type { ReticleEvent } from '@reticlehq/core';
+/** Filter bounds for a journal-backed event query. All optional; omitted = unbounded on that axis. */
+export interface EventQueryOptions {
+    /** Lower time bound (inclusive), elapsed ms — the act cursor semantics of `eventsSince`. */
+    since?: number | undefined;
+    /** Upper time bound (inclusive), elapsed ms — the new `until` param. */
+    until?: number | undefined;
+    /** Keep only events attributed to this action id — answers "what did action N cause". */
+    actionId?: string | undefined;
+}
+/**
+ * Merge the durable journal's events with the ring buffer's, de-duplicated by `seq` (unique per
+ * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
+ * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
+ * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ */
+export declare function mergeEventsBySeq(journal: readonly ReticleEvent[], buffer: readonly ReticleEvent[]): ReticleEvent[];
+/** Apply since/until/actionId bounds to an event list. */
+export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];
+//# sourceMappingURL=journal-query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"journal-query.d.ts","sourceRoot":"","sources":["../../src/journal/journal-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,YAAY,EAAE,CAWhB;AAED,0DAA0D;AAC1D,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,EAAE,iBAAiB,GACzB,YAAY,EAAE,CAOhB"}

package/dist/journal/journal-query.js

@@ -0,0 +1,28 @@
+/**
+ * Merge the durable journal's events with the ring buffer's, de-duplicated by `seq` (unique per
+ * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
+ * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
+ * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ */
+export function mergeEventsBySeq(journal, buffer) {
+    const bySeq = new Map();
+    const noSeq = [];
+    for (const event of [...journal, ...buffer]) {
+        if (typeof event.seq === 'number')
+            bySeq.set(event.seq, event);
+        else
+            noSeq.push(event);
+    }
+    return [...bySeq.values(), ...noSeq].sort((a, b) => {
+        if (a.seq !== undefined && b.seq !== undefined)
+            return a.seq - b.seq;
+        return a.t - b.t;
+    });
+}
+/** Apply since/until/actionId bounds to an event list. */
+export function filterEvents(events, options) {
+    return events.filter((event) => (options.since === undefined || event.t >= options.since) &&
+        (options.until === undefined || event.t <= options.until) &&
+        (options.actionId === undefined || event.actionId === options.actionId));
+}
+//# sourceMappingURL=journal-query.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"journal-query.js","sourceRoot":"","sources":["../../src/journal/journal-query.ts"],"names":[],"mappings":"AAYA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgC,EAChC,MAA+B;IAE/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwB,CAAC;IAC9C,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,OAAO,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ;YAAE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;;YAC1D,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACjD,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS,IAAI,CAAC,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;QACrE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAC1B,MAA+B,EAC/B,OAA0B;IAE1B,OAAO,MAAM,CAAC,MAAM,CAClB,CAAC,KAAK,EAAE,EAAE,CACR,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC;QACzD,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAC1E,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,38 @@
+import { type JournalAction, type ReticleEvent } from '@reticlehq/core';
+/** Where a recorder persists. `SessionJournal` satisfies this structurally. */
+export interface JournalSink {
+    appendEvents(events: readonly ReticleEvent[]): Promise<void>;
+    appendAction(action: JournalAction): Promise<void>;
+}
+/** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
+export interface JournalReader {
+    readEvents(): Promise<ReticleEvent[]>;
+}
+export interface JournalRecorderOptions {
+    /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
+    now: () => number;
+    /** Flush the pending-event batch once this many accumulate. */
+    flushAt?: number;
+}
+/**
+ * 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 declare class JournalRecorder {
+    #private;
+    constructor(sink: JournalSink, options: JournalRecorderOptions);
+    /** Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event. */
+    observe(event: ReticleEvent): ReticleEvent;
+    /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
+    beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;
+    /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
+    finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=journal-recorder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"journal-recorder.d.ts","sourceRoot":"","sources":["../../src/journal/journal-recorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAEzB,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,UAAU,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,sBAAsB;IACrC,wFAAwF;IACxF,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;GAQG;AACH,qBAAa,eAAe;;gBAQd,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB;IAM9D,yGAAyG;IACzG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY;IAgB1C,kGAAkG;IAClG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhF,0GAA0G;IAC1G,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAuB7E,+FAA+F;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B"}