@untangle-code/observability 0.0.0-stage → 0.1.1

package/dist/logger.js

@@ -0,0 +1,108 @@
+import { redact } from "./redact.js";
+const LEVEL_ORDER = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+};
+function defaultSink(line) {
+    process.stderr.write(`${line}\n`);
+}
+function mergeBindings(base, next) {
+    const merged = { ...base, ...next };
+    const context = { ...base.context, ...next.context };
+    if (Object.keys(context).length > 0) {
+        merged.context = context;
+    }
+    else {
+        delete merged.context;
+    }
+    return merged;
+}
+/** Correlation keys promoted from {@link LoggerBindings} into `context` (see module doc). */
+function correlationContext(bindings) {
+    const extra = {};
+    if (bindings.generationId !== undefined)
+        extra["generationId"] = bindings.generationId;
+    if (bindings.workspaceId !== undefined)
+        extra["workspaceId"] = bindings.workspaceId;
+    if (bindings.repoId !== undefined)
+        extra["repoId"] = bindings.repoId;
+    if (bindings.refId !== undefined)
+        extra["refId"] = bindings.refId;
+    return extra;
+}
+class JsonLinesLogger {
+    clock;
+    minLevel;
+    sink;
+    includeSourceText;
+    bindings;
+    constructor(clock, minLevel, sink, includeSourceText, bindings) {
+        this.clock = clock;
+        this.minLevel = minLevel;
+        this.sink = sink;
+        this.includeSourceText = includeSourceText;
+        this.bindings = bindings;
+    }
+    log(event) {
+        if (LEVEL_ORDER[event.level] < LEVEL_ORDER[this.minLevel]) {
+            return;
+        }
+        const component = event.component || this.bindings.component || "untangle";
+        const requestId = event.requestId ?? this.bindings.requestId;
+        const jobId = event.jobId ?? this.bindings.jobId;
+        const context = {
+            ...correlationContext(this.bindings),
+            ...this.bindings.context,
+            ...event.context,
+        };
+        const line = {
+            timestamp: event.timestamp,
+            level: event.level,
+            component,
+            event: event.event,
+            ...(requestId !== undefined ? { requestId } : {}),
+            ...(jobId !== undefined ? { jobId } : {}),
+            ...(Object.keys(context).length > 0
+                ? {
+                    context: redact(context, { includeSourceText: this.includeSourceText }),
+                }
+                : {}),
+        };
+        this.sink(JSON.stringify(line));
+    }
+    child(bindings) {
+        return new JsonLinesLogger(this.clock, this.minLevel, this.sink, this.includeSourceText, mergeBindings(this.bindings, bindings));
+    }
+    error(event, context) {
+        this.emit("error", event, context);
+    }
+    warn(event, context) {
+        this.emit("warn", event, context);
+    }
+    info(event, context) {
+        this.emit("info", event, context);
+    }
+    debug(event, context) {
+        this.emit("debug", event, context);
+    }
+    trace(event, context) {
+        this.emit("trace", event, context);
+    }
+    emit(level, event, context) {
+        this.log({
+            timestamp: this.clock.nowIso(),
+            level,
+            component: this.bindings.component ?? "untangle",
+            event,
+            ...(context !== undefined ? { context } : {}),
+        });
+    }
+}
+/** Creates a structured, JSON-lines-on-stderr {@link Logger} (architecture.md §24.2). */
+export function createLogger(options) {
+    return new JsonLinesLogger(options.clock, options.level ?? "info", options.sink ?? defaultSink, options.debugIncludeSourceText ?? false, options.bindings ?? {});
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Metrics registry (spec.md §23.3): exactly the internal counters the core
+ * engine SHOULD expose. No external exporter — `snapshot()` returns a plain
+ * object, which callers may print, log, or serve however they like.
+ *
+ * spec.md §23.3 calls all eleven names "Zähler" (counters), but three of
+ * them are not cumulative counts by nature:
+ * - `search_latency_ms` is a distribution of per-search durations, not a
+ *   single number — modeled as a histogram.
+ * - `resolved_import_ratio`/`resolved_call_ratio` are point-in-time ratios
+ *   (resolved / total at last computation), which a monotonic counter
+ *   cannot represent without lying about "cumulative" — modeled as gauges
+ *   the caller sets to the latest computed value.
+ *
+ * The other eight are genuinely cumulative and are modeled as counters.
+ * This is a WP-04-local decision (README "Entscheidungen") — the set of
+ * names is exactly spec.md §23.3's eleven, not open for extension by name.
+ */
+/** Cumulative counters (spec.md §23.3). */
+export declare const COUNTER_NAMES: readonly ["files_scanned", "files_changed", "chunks_created", "embeddings_requested", "embedding_cache_hits", "qdrant_upsert_bytes", "parse_failures", "watcher_reconciliations"];
+export type CounterName = (typeof COUNTER_NAMES)[number];
+/** Latency distributions (spec.md §23.3). */
+export declare const HISTOGRAM_NAMES: readonly ["search_latency_ms"];
+export type HistogramName = (typeof HISTOGRAM_NAMES)[number];
+/** Point-in-time ratios (spec.md §23.3). */
+export declare const RATIO_NAMES: readonly ["resolved_import_ratio", "resolved_call_ratio"];
+export type RatioName = (typeof RATIO_NAMES)[number];
+export interface HistogramSnapshot {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface MetricsSnapshotV1 {
+    counters: Record<CounterName, number>;
+    histograms: Record<HistogramName, HistogramSnapshot>;
+    ratios: Record<RatioName, number | null>;
+}
+/** Summarizes raw samples into a {@link HistogramSnapshot}. Pure, no state. */
+export declare function summarizeHistogram(samples: readonly number[]): HistogramSnapshot;
+/** In-process registry for exactly the eleven counters of spec.md §23.3. */
+export declare class MetricsRegistry {
+    private readonly counters;
+    private readonly samples;
+    private readonly ratios;
+    constructor();
+    /** Increments a counter by `delta` (default 1). `delta` must be finite and >= 0. */
+    incrementCounter(name: CounterName, delta?: number): void;
+    /** Records one observed latency (milliseconds) for a histogram. */
+    observeHistogram(name: HistogramName, valueMs: number): void;
+    /** Sets the latest value of a ratio gauge. `null` clears it back to "unknown". */
+    setRatio(name: RatioName, value: number | null): void;
+    /** Point-in-time snapshot as a plain object — no external exporter. */
+    snapshot(): MetricsSnapshotV1;
+    /** Resets every counter, histogram and ratio back to its initial state. */
+    reset(): void;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,aAAa,mLAShB,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,6CAA6C;AAC7C,eAAO,MAAM,eAAe,gCAAiC,CAAC;AAC9D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,4CAA4C;AAC5C,eAAO,MAAM,WAAW,2DAA4D,CAAC;AACrF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,aAAa,EAAE,iBAAiB,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1C;AAaD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CAgBhF;AAOD,4EAA4E;AAC5E,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;;IAQ1D,oFAAoF;IAC7E,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,SAAI,GAAG,IAAI;IAO3D,mEAAmE;IAC5D,gBAAgB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAOnE,kFAAkF;IAC3E,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAO5D,uEAAuE;IAChE,QAAQ,IAAI,iBAAiB;IAQpC,2EAA2E;IACpE,KAAK,IAAI,IAAI;CAWrB"}

package/dist/metrics.js

@@ -0,0 +1,121 @@
+/**
+ * Metrics registry (spec.md §23.3): exactly the internal counters the core
+ * engine SHOULD expose. No external exporter — `snapshot()` returns a plain
+ * object, which callers may print, log, or serve however they like.
+ *
+ * spec.md §23.3 calls all eleven names "Zähler" (counters), but three of
+ * them are not cumulative counts by nature:
+ * - `search_latency_ms` is a distribution of per-search durations, not a
+ *   single number — modeled as a histogram.
+ * - `resolved_import_ratio`/`resolved_call_ratio` are point-in-time ratios
+ *   (resolved / total at last computation), which a monotonic counter
+ *   cannot represent without lying about "cumulative" — modeled as gauges
+ *   the caller sets to the latest computed value.
+ *
+ * The other eight are genuinely cumulative and are modeled as counters.
+ * This is a WP-04-local decision (README "Entscheidungen") — the set of
+ * names is exactly spec.md §23.3's eleven, not open for extension by name.
+ */
+/** Cumulative counters (spec.md §23.3). */
+export const COUNTER_NAMES = [
+    "files_scanned",
+    "files_changed",
+    "chunks_created",
+    "embeddings_requested",
+    "embedding_cache_hits",
+    "qdrant_upsert_bytes",
+    "parse_failures",
+    "watcher_reconciliations",
+];
+/** Latency distributions (spec.md §23.3). */
+export const HISTOGRAM_NAMES = ["search_latency_ms"];
+/** Point-in-time ratios (spec.md §23.3). */
+export const RATIO_NAMES = ["resolved_import_ratio", "resolved_call_ratio"];
+const EMPTY_HISTOGRAM = {
+    count: 0,
+    sum: 0,
+    min: 0,
+    max: 0,
+    avg: 0,
+    p50: 0,
+    p95: 0,
+    p99: 0,
+};
+/** Summarizes raw samples into a {@link HistogramSnapshot}. Pure, no state. */
+export function summarizeHistogram(samples) {
+    if (samples.length === 0) {
+        return EMPTY_HISTOGRAM;
+    }
+    const sorted = [...samples].sort((a, b) => a - b);
+    const sum = sorted.reduce((total, value) => total + value, 0);
+    return {
+        count: sorted.length,
+        sum,
+        min: sorted[0],
+        max: sorted[sorted.length - 1],
+        avg: sum / sorted.length,
+        p50: percentile(sorted, 0.5),
+        p95: percentile(sorted, 0.95),
+        p99: percentile(sorted, 0.99),
+    };
+}
+function percentile(sorted, fraction) {
+    const index = Math.min(sorted.length - 1, Math.floor(fraction * sorted.length));
+    return sorted[index];
+}
+/** In-process registry for exactly the eleven counters of spec.md §23.3. */
+export class MetricsRegistry {
+    counters;
+    samples;
+    ratios;
+    constructor() {
+        this.counters = fromNames(COUNTER_NAMES, () => 0);
+        this.samples = fromNames(HISTOGRAM_NAMES, () => []);
+        this.ratios = fromNames(RATIO_NAMES, () => null);
+    }
+    /** Increments a counter by `delta` (default 1). `delta` must be finite and >= 0. */
+    incrementCounter(name, delta = 1) {
+        if (!Number.isFinite(delta) || delta < 0) {
+            throw new RangeError(`counter delta must be a finite, non-negative number, got ${delta}`);
+        }
+        this.counters[name] += delta;
+    }
+    /** Records one observed latency (milliseconds) for a histogram. */
+    observeHistogram(name, valueMs) {
+        if (!Number.isFinite(valueMs) || valueMs < 0) {
+            throw new RangeError(`histogram value must be a finite, non-negative number, got ${valueMs}`);
+        }
+        this.samples[name].push(valueMs);
+    }
+    /** Sets the latest value of a ratio gauge. `null` clears it back to "unknown". */
+    setRatio(name, value) {
+        if (value !== null && (!Number.isFinite(value) || value < 0 || value > 1)) {
+            throw new RangeError(`ratio must be null or within [0, 1], got ${value}`);
+        }
+        this.ratios[name] = value;
+    }
+    /** Point-in-time snapshot as a plain object — no external exporter. */
+    snapshot() {
+        return {
+            counters: { ...this.counters },
+            histograms: fromNames(HISTOGRAM_NAMES, (name) => summarizeHistogram(this.samples[name])),
+            ratios: { ...this.ratios },
+        };
+    }
+    /** Resets every counter, histogram and ratio back to its initial state. */
+    reset() {
+        for (const name of COUNTER_NAMES) {
+            this.counters[name] = 0;
+        }
+        for (const name of HISTOGRAM_NAMES) {
+            this.samples[name] = [];
+        }
+        for (const name of RATIO_NAMES) {
+            this.ratios[name] = null;
+        }
+    }
+}
+function fromNames(names, init) {
+    return Object.fromEntries(names.map((name) => [name, init(name)]));
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,sBAAsB;IACtB,sBAAsB;IACtB,qBAAqB;IACrB,gBAAgB;IAChB,yBAAyB;CACjB,CAAC;AAGX,6CAA6C;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,mBAAmB,CAAU,CAAC;AAG9D,4CAA4C;AAC5C,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAU,CAAC;AAoBrF,MAAM,eAAe,GAAsB;IACzC,KAAK,EAAE,CAAC;IACR,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;CACP,CAAC;AAEF,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC3D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;IAC9D,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,GAAG;QACH,GAAG,EAAE,MAAM,CAAC,CAAC,CAAE;QACf,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE;QAC/B,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM;QACxB,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;QAC5B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;QAC7B,GAAG,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC;KAC9B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,MAAyB,EAAE,QAAgB;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,KAAK,CAAE,CAAC;AACxB,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,eAAe;IACT,QAAQ,CAA8B;IACtC,OAAO,CAAkC;IACzC,MAAM,CAAmC;IAE1D;QACE,IAAI,CAAC,QAAQ,GAAG,SAAS,CAAC,aAAa,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC,eAAe,EAAE,GAAG,EAAE,CAAC,EAAc,CAAC,CAAC;QAChE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC;IAED,oFAAoF;IAC7E,gBAAgB,CAAC,IAAiB,EAAE,KAAK,GAAG,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,UAAU,CAAC,4DAA4D,KAAK,EAAE,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;IAC/B,CAAC;IAED,mEAAmE;IAC5D,gBAAgB,CAAC,IAAmB,EAAE,OAAe;QAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAC7C,MAAM,IAAI,UAAU,CAAC,8DAA8D,OAAO,EAAE,CAAC,CAAC;QAChG,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED,kFAAkF;IAC3E,QAAQ,CAAC,IAAe,EAAE,KAAoB;QACnD,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YAC1E,MAAM,IAAI,UAAU,CAAC,4CAA4C,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED,uEAAuE;IAChE,QAAQ;QACb,OAAO;YACL,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE;YAC9B,UAAU,EAAE,SAAS,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACxF,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE;SAC3B,CAAC;IACJ,CAAC;IAED,2EAA2E;IACpE,KAAK;QACV,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC1B,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC3B,CAAC;IACH,CAAC;CACF;AAED,SAAS,SAAS,CAChB,KAAsB,EACtB,IAA2B;IAE3B,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAwB,CAAC;AAC5F,CAAC"}

package/dist/profiling.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Profiling collector for `--profile` (architecture.md §24.3): stage
+ * timings via the injected `Clock`, file counts, cache hit rates, embedding
+ * and Qdrant latency/bytes, a parser/language breakdown, and the process
+ * memory high water mark.
+ *
+ * Stage timing uses `Clock` exclusively (BUILD_PLAN determinism rule).
+ * The memory high water mark is the one place this module reads real
+ * process state (`process.memoryUsage()`), because that is exactly what
+ * architecture.md §24.3 asks for — it is not a timing or randomness
+ * decision, just a resource-usage sample.
+ */
+import type { Clock } from "@untangle-code/domain";
+import { type HistogramSnapshot } from "./metrics.js";
+export interface StageTimingV1 {
+    stage: string;
+    startedAtIso: string;
+    endedAtIso: string;
+    durationMs: number;
+}
+export interface CacheHitRateV1 {
+    hits: number;
+    misses: number;
+    /** `hits / (hits + misses)`, or `null` when there were no accesses at all. */
+    rate: number | null;
+}
+export interface ParserBreakdownEntryV1 {
+    files: number;
+    failures: number;
+}
+export interface ProfileReportV1 {
+    stages: StageTimingV1[];
+    fileCounts: Record<string, number>;
+    cacheHitRates: Record<string, CacheHitRateV1>;
+    embeddingLatencyMs: HistogramSnapshot;
+    qdrantLatencyMs: HistogramSnapshot;
+    qdrantBytes: number;
+    parserBreakdown: Record<string, ParserBreakdownEntryV1>;
+    memoryHighWaterMarkBytes: number;
+}
+export interface StageHandle {
+    /** Ends the stage. Idempotent — a second call is a no-op. */
+    end(): void;
+}
+/** Reads the process's current resident set size. Isolated for testability. */
+export declare function sampleMemoryBytes(): number;
+/** Collects one `--profile` run's worth of measurements. */
+export declare class ProfileCollector {
+    private readonly clock;
+    private readonly readMemoryBytes;
+    private readonly stages;
+    private readonly fileCounts;
+    private readonly cacheCounters;
+    private readonly embeddingLatencies;
+    private readonly qdrantLatencies;
+    private readonly parserBreakdown;
+    private qdrantBytesTotal;
+    private memoryHighWaterMarkBytes;
+    constructor(deps: {
+        clock: Clock;
+        readMemoryBytes?: () => number;
+    });
+    /** Starts timing `stage`. Returns a handle whose `end()` records the duration. */
+    beginStage(stage: string): StageHandle;
+    recordFileCount(category: string, delta?: number): void;
+    recordCacheAccess(name: string, hit: boolean): void;
+    recordEmbeddingLatency(ms: number): void;
+    recordQdrantLatency(ms: number): void;
+    addQdrantBytes(bytes: number): void;
+    recordParserOutcome(language: string, outcome: "success" | "failure"): void;
+    /** Re-samples the memory high water mark on demand (also sampled automatically around stages/latencies). */
+    sampleMemory(): void;
+    snapshot(): ProfileReportV1;
+}
+//# sourceMappingURL=profiling.d.ts.map

package/dist/profiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,KAAK,iBAAiB,EAAsB,MAAM,cAAc,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC9C,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,eAAe,EAAE,iBAAiB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACxD,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,GAAG,IAAI,IAAI,CAAC;CACb;AAOD,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,4DAA4D;AAC5D,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IACzD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqC;IACnE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAgB;IACnD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8C;IAC9E,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,wBAAwB,CAAS;gBAEtB,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE;IAMzE,kFAAkF;IAC3E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAuBtC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,IAAI;IAIlD,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI;IAUnD,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxC,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKrC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAInC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI;IASlF,4GAA4G;IACrG,YAAY,IAAI,IAAI;IAOpB,QAAQ,IAAI,eAAe;CAqBnC"}

package/dist/profiling.js

@@ -0,0 +1,107 @@
+import { summarizeHistogram } from "./metrics.js";
+/** Reads the process's current resident set size. Isolated for testability. */
+export function sampleMemoryBytes() {
+    return process.memoryUsage().rss;
+}
+/** Collects one `--profile` run's worth of measurements. */
+export class ProfileCollector {
+    clock;
+    readMemoryBytes;
+    stages = [];
+    fileCounts = {};
+    cacheCounters = {};
+    embeddingLatencies = [];
+    qdrantLatencies = [];
+    parserBreakdown = {};
+    qdrantBytesTotal = 0;
+    memoryHighWaterMarkBytes;
+    constructor(deps) {
+        this.clock = deps.clock;
+        this.readMemoryBytes = deps.readMemoryBytes ?? sampleMemoryBytes;
+        this.memoryHighWaterMarkBytes = this.readMemoryBytes();
+    }
+    /** Starts timing `stage`. Returns a handle whose `end()` records the duration. */
+    beginStage(stage) {
+        const startedAtIso = this.clock.nowIso();
+        const startedAtMs = this.clock.nowEpochMs();
+        this.sampleMemory();
+        let ended = false;
+        return {
+            end: () => {
+                if (ended) {
+                    return;
+                }
+                ended = true;
+                const endedAtMs = this.clock.nowEpochMs();
+                this.stages.push({
+                    stage,
+                    startedAtIso,
+                    endedAtIso: this.clock.nowIso(),
+                    durationMs: endedAtMs - startedAtMs,
+                });
+                this.sampleMemory();
+            },
+        };
+    }
+    recordFileCount(category, delta = 1) {
+        this.fileCounts[category] = (this.fileCounts[category] ?? 0) + delta;
+    }
+    recordCacheAccess(name, hit) {
+        const counters = this.cacheCounters[name] ?? { hits: 0, misses: 0 };
+        if (hit) {
+            counters.hits += 1;
+        }
+        else {
+            counters.misses += 1;
+        }
+        this.cacheCounters[name] = counters;
+    }
+    recordEmbeddingLatency(ms) {
+        this.embeddingLatencies.push(ms);
+        this.sampleMemory();
+    }
+    recordQdrantLatency(ms) {
+        this.qdrantLatencies.push(ms);
+        this.sampleMemory();
+    }
+    addQdrantBytes(bytes) {
+        this.qdrantBytesTotal += bytes;
+    }
+    recordParserOutcome(language, outcome) {
+        const entry = this.parserBreakdown[language] ?? { files: 0, failures: 0 };
+        entry.files += 1;
+        if (outcome === "failure") {
+            entry.failures += 1;
+        }
+        this.parserBreakdown[language] = entry;
+    }
+    /** Re-samples the memory high water mark on demand (also sampled automatically around stages/latencies). */
+    sampleMemory() {
+        const current = this.readMemoryBytes();
+        if (current > this.memoryHighWaterMarkBytes) {
+            this.memoryHighWaterMarkBytes = current;
+        }
+    }
+    snapshot() {
+        const cacheHitRates = {};
+        for (const [name, counters] of Object.entries(this.cacheCounters)) {
+            const total = counters.hits + counters.misses;
+            cacheHitRates[name] = {
+                hits: counters.hits,
+                misses: counters.misses,
+                rate: total === 0 ? null : counters.hits / total,
+            };
+        }
+        return {
+            stages: [...this.stages],
+            fileCounts: { ...this.fileCounts },
+            cacheHitRates,
+            embeddingLatencyMs: summarizeHistogram(this.embeddingLatencies),
+            qdrantLatencyMs: summarizeHistogram(this.qdrantLatencies),
+            qdrantBytes: this.qdrantBytesTotal,
+            parserBreakdown: { ...this.parserBreakdown },
+            memoryHighWaterMarkBytes: this.memoryHighWaterMarkBytes,
+        };
+    }
+}
+//# sourceMappingURL=profiling.js.map

package/dist/profiling.js.map

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

package/dist/redact.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Redaction (spec.md §24, §23.2): keeps secrets and full source text out of
+ * logs, status output and crash reports by default.
+ *
+ * `redact()` is a pure function — no I/O, no logging decisions of its own.
+ * The logger (`logger.ts`) applies it to every event's `context` before
+ * writing.
+ */
+export interface RedactOptions {
+    /**
+     * Opt-in escape hatch for interactive debugging (spec.md §24: only on
+     * explicit debug opt-in). When `false` (default), values under a
+     * {@link SOURCE_TEXT_KEYS} key are replaced instead of logged verbatim.
+     */
+    includeSourceText?: boolean;
+}
+/**
+ * Recursively redacts `value`: keys that look like secrets are masked
+ * regardless of their value's shape, keys that carry source text are
+ * suppressed unless `includeSourceText` is set, and string values that look
+ * like a secret themselves (bearer tokens, JWTs, common vendor key prefixes)
+ * are masked even under an innocuous key name.
+ *
+ * Never throws: unsupported value kinds (bigint, function, symbol) are
+ * stringified rather than propagating a serialization error into a logging
+ * call.
+ */
+export declare function redact(value: unknown, options?: RedactOptions): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoCH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAE3E"}

package/dist/redact.js

@@ -0,0 +1,123 @@
+/**
+ * Redaction (spec.md §24, §23.2): keeps secrets and full source text out of
+ * logs, status output and crash reports by default.
+ *
+ * `redact()` is a pure function — no I/O, no logging decisions of its own.
+ * The logger (`logger.ts`) applies it to every event's `context` before
+ * writing.
+ */
+const MASK = "[REDACTED]";
+const SOURCE_TEXT_SUPPRESSED = "[SOURCE_TEXT_SUPPRESSED]";
+/**
+ * Key names spec.md §24 calls out by name, plus the common synonyms and
+ * variants ("api_key", "apiKey", "auth", …) adapters realistically use.
+ * Matched case-insensitively against the whole key.
+ */
+const SECRET_KEY_PATTERN = /(api[-_]?key|access[-_]?key|secret[-_]?key|private[-_]?key|token|password|passwd|pwd|secret|authorization|auth|cookie|credential)/i;
+/**
+ * Field names that carry full source text / code (spec.md §23.2: "vollständige
+ * Quelltexte standardmäßig redigieren"). Mirrors the content-bearing fields of
+ * domain's `CodeChunkPayloadV1`/`CodeChunkDraft` plus generic synonyms, so a
+ * logged chunk, diff or search hit does not dump raw code into logs by
+ * default. Matched case-insensitively against the whole key.
+ */
+const SOURCE_TEXT_KEYS = new Set([
+    "content",
+    "text",
+    "sourcetext",
+    "source",
+    "sourcecode",
+    "code",
+    "snippet",
+    "prepareddensetext",
+    "bm25text",
+    "diff",
+    "patch",
+    "raw",
+    "rawtext",
+]);
+/**
+ * Recursively redacts `value`: keys that look like secrets are masked
+ * regardless of their value's shape, keys that carry source text are
+ * suppressed unless `includeSourceText` is set, and string values that look
+ * like a secret themselves (bearer tokens, JWTs, common vendor key prefixes)
+ * are masked even under an innocuous key name.
+ *
+ * Never throws: unsupported value kinds (bigint, function, symbol) are
+ * stringified rather than propagating a serialization error into a logging
+ * call.
+ */
+export function redact(value, options = {}) {
+    return redactValue(value, options, new WeakSet());
+}
+function redactValue(value, options, seen) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return "[CIRCULAR]";
+        }
+        seen.add(value);
+        return value.map((entry) => redactValue(entry, options, seen));
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            return "[CIRCULAR]";
+        }
+        seen.add(value);
+        const out = {};
+        for (const [key, entryValue] of Object.entries(value)) {
+            out[key] = redactEntry(key, entryValue, options, seen);
+        }
+        return out;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (typeof value === "function" || typeof value === "symbol") {
+        return `[${typeof value}]`;
+    }
+    if (typeof value === "string" && looksLikeSecretValue(value)) {
+        return MASK;
+    }
+    return value;
+}
+function redactEntry(key, entryValue, options, seen) {
+    const lowerKey = key.toLowerCase();
+    if (SECRET_KEY_PATTERN.test(lowerKey)) {
+        return MASK;
+    }
+    if (!options.includeSourceText && SOURCE_TEXT_KEYS.has(lowerKey)) {
+        return SOURCE_TEXT_SUPPRESSED;
+    }
+    return redactValue(entryValue, options, seen);
+}
+/**
+ * Heuristic for "a value that looks like a key" (spec.md §24): bearer
+ * headers, JWT-shaped triples, and common vendor secret prefixes
+ * (`sk-`, `ghp_`, `xox…`). Conservative on purpose — false negatives are
+ * expected, false positives on ordinary prose are not.
+ */
+function looksLikeSecretValue(value) {
+    if (/^bearer\s+\S+/i.test(value)) {
+        return true;
+    }
+    if (/^[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}$/.test(value)) {
+        return true;
+    }
+    if (/^(sk|pk|rk)-[A-Za-z0-9_-]{16,}$/i.test(value)) {
+        return true;
+    }
+    if (/^(ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{16,}$/i.test(value)) {
+        return true;
+    }
+    if (/^xox[baprs]-[A-Za-z0-9-]{10,}$/i.test(value)) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=redact.js.map