@pristine-ts/observability 2.0.16 → 2.0.17

package/dist/types/serializers/serialized-span.interface.d.ts

@@ -1,14 +0,0 @@
-/**
- * The plain-object shape of a stored span — as produced by `TraceRenderer.serialize`
- * and rehydrated by `SpanDeserializer`.
- */
-export interface SerializedSpan {
-    id?: string;
-    keyname: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    children?: SerializedSpan[];
-}

package/dist/types/serializers/serialized-trace.interface.d.ts

@@ -1,14 +0,0 @@
-import { SerializedSpan } from "./serialized-span.interface";
-/**
- * The plain-object shape of a stored trace — as written to disk by
- * `ObservabilityTracer` and rehydrated by `TraceDeserializer`.
- */
-export interface SerializedTrace {
-    id: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    rootSpan?: SerializedSpan;
-}

package/dist/types/store/log-tailer.d.ts

@@ -1,27 +0,0 @@
-/**
- * Follows a growing `.jsonl` file and emits each newly-appended complete line. The
- * `logs --follow` command and the REPL use this for a `tail -f`-style live view.
- *
- * Watches the file's parent directory (watching a not-yet-created file directly is
- * unreliable across platforms) and reads the byte delta on each change. Partial trailing
- * lines are buffered until their terminating newline arrives.
- *
- * Not a DI service — a plain utility. Instantiate, `follow()`, and `stop()` when done.
- */
-export declare class LogTailer {
-    private readonly filePath;
-    private watcher?;
-    private offset;
-    private buffer;
-    constructor(filePath: string);
-    /**
-     * Starts following. Existing content is skipped — only lines appended after this call
-     * are emitted. Call `stop()` to release the watch.
-     */
-    follow(onLine: (line: string) => void): void;
-    /**
-     * Stops following and releases the filesystem watch.
-     */
-    stop(): void;
-    private drain;
-}

package/dist/types/store/observability-paths.d.ts

@@ -1,30 +0,0 @@
-/**
- * Resolves every path inside the observability store from the configured store directory.
- * Pure and stateless past construction — instantiate once with the configured directory
- * and reuse.
- *
- * Layout:
- * ```
- * <root>/
- *   <instanceId>/logs.jsonl
- *   <instanceId>/requests.jsonl
- *   <instanceId>/traces/<traceId>.json
- * ```
- *
- * Each `<instanceId>` is one pristine process lifetime (= the kernel instantiation id).
- * No metadata sidecars, no `latest.json` pointer — directory `mtime` answers "which is
- * most recent."
- */
-export declare class ObservabilityPaths {
-    /**
-     * The absolute store root. The configured directory is resolved against `process.cwd()`
-     * when it is not already absolute.
-     */
-    readonly root: string;
-    constructor(configuredDirectory: string);
-    instanceDirectory(instanceId: string): string;
-    logsFile(instanceId: string): string;
-    requestsFile(instanceId: string): string;
-    tracesDirectory(instanceId: string): string;
-    traceFile(instanceId: string, traceId: string): string;
-}

package/dist/types/store/observability-run-manager.d.ts

@@ -1,96 +0,0 @@
-import { ObservabilityConfiguration } from "../observability-configuration";
-/**
- * Owns the lifecycle of an observability run. A "run" is one `pristine start` lifetime;
- * the run directory is keyed by the kernel instantiation id.
- *
- * The observability writers (`ObservabilityLogger`, `ObservabilityTracer`) stay dormant
- * until `beginRun()` is called — so one-shot CLI commands (`build`, `logs`, `trace`) and
- * the REPL never pollute the store. `StartCommand` is the only caller of `beginRun()`.
- *
- * A singleton so the logger, the tracer, and `StartCommand` all share the same run state.
- */
-export declare class ObservabilityRunManager {
-    private readonly configuration;
-    private readonly runId;
-    /**
-     * Once the reclaimed run exceeds the budget we trim back to this fraction of it, so the
-     * (relatively expensive) reclaim isn't re-triggered on the very next write.
-     */
-    private static readonly LOW_WATER_FRACTION;
-    private readonly paths;
-    private activeRunDirectory?;
-    /**
-     * Approximate running total of bytes written to the active run. Incremented cheaply by
-     * the writers via `recordBytesWritten`; resynced to the real on-disk total after each
-     * reclaim. Used to decide when to enforce the per-run size budget without stat-ing the
-     * whole run directory on every write.
-     */
-    private runBytes;
-    constructor(configuration: ObservabilityConfiguration, runId: string);
-    /**
-     * Begins a run: creates the run directory, writes `run.json`, repoints `latest.json`,
-     * and prunes old runs. No-op when observability is disabled. Safe to call once per
-     * process.
-     */
-    beginRun(command: string): void;
-    /**
-     * Reports bytes just written to the run by a writer. Cheap — an add and a compare. When
-     * the running total crosses the configured `maxRunSizeBytes`, triggers a reclaim that
-     * drops the run's oldest data. No-op when no run is active or the cap is disabled.
-     */
-    recordBytesWritten(bytes: number): void;
-    /**
-     * Ends the active run by stamping `endedAt` into `run.json`. No-op when no run is active.
-     */
-    endRun(): void;
-    /**
-     * Whether a run is currently active. The writers consult this on every write.
-     */
-    isRunActive(): boolean;
-    /**
-     * The absolute logs file for the active run, or undefined when no run is active.
-     */
-    logsFile(): string | undefined;
-    /**
-     * The absolute requests-index file for the active run, or undefined when no run is active.
-     */
-    requestsFile(): string | undefined;
-    /**
-     * The absolute path of the trace file for a given trace id in the active run, or
-     * undefined when no run is active.
-     */
-    traceFile(traceId: string): string | undefined;
-    /**
-     * Lazily begins a run when `autoBegin` is configured and none is active yet — so a
-     * server started outside the `pristine` CLI captures its logs/traces on the first
-     * write, with nothing calling `beginRun()` explicitly.
-     */
-    private ensureAutoBegun;
-    /**
-     * Drops the run's oldest data until it is back under the budget's low-water mark:
-     * oldest trace files first, then the head of `logs.jsonl` (keeping the newest tail).
-     * The `requests.jsonl` index is rewritten to drop entries for deleted traces.
-     *
-     * Best-effort and fully guarded — budget enforcement must never break or lose a write.
-     */
-    private reclaim;
-    /**
-     * Rewrites a file in place keeping only its last `keepBytes` bytes, aligned forward to
-     * the next newline so no partial line survives.
-     */
-    private trimFileHead;
-    /**
-     * Rewrites `requests.jsonl` keeping only entries whose trace file still exists — so the
-     * request index stays consistent after trace files are reclaimed.
-     */
-    private pruneRequestsIndex;
-    /**
-     * Sum of the sizes of every file directly inside `directory`.
-     */
-    private directoryTotalSize;
-    /**
-     * Removes run directories beyond the retained limit, ordered by their
-     * `run.json:startedAt`. Best-effort — a failure to prune never blocks a run.
-     */
-    private pruneOldRuns;
-}

package/dist/types/store/observability-store-reader.d.ts

@@ -1,55 +0,0 @@
-import { ObservabilityConfiguration } from "../observability-configuration";
-import { RunMetadata } from "../models/run-metadata.model";
-import { RequestSummary } from "../models/request-summary.model";
-import { SerializedTrace } from "./trace-deserializer";
-/**
- * Read-only access to the observability store. Used by the `logs`, `trace` and `requests`
- * CLI commands. Pure filesystem reads — no kernel, no running app required; it reads what
- * a separate `pristine start` process wrote.
- */
-export declare class ObservabilityStoreReader {
-    private readonly paths;
-    constructor(configuration: ObservabilityConfiguration);
-    /**
-     * The run id the `latest.json` pointer references, or undefined when the store is empty.
-     */
-    latestRunId(): string | undefined;
-    /**
-     * Resolves an explicit run id, or falls back to the latest run.
-     */
-    resolveRunId(explicit?: string): string | undefined;
-    /**
-     * Every run's metadata, most-recent first.
-     */
-    listRuns(): RunMetadata[];
-    /**
-     * Reads a run's `run.json`, or undefined when absent/corrupt.
-     */
-    readRunMetadata(runId: string): RunMetadata | undefined;
-    /**
-     * The request summaries for a run, most-recent first, optionally capped to `limit`.
-     */
-    readRequests(runId: string, limit?: number): RequestSummary[];
-    /**
-     * The raw log entries for a run, in write order. Each is a parsed `logs.jsonl` line.
-     */
-    readLogs(runId: string): Record<string, any>[];
-    /**
-     * The absolute `logs.jsonl` path for a run — handed to `LogTailer` for `--follow`.
-     */
-    logsFilePath(runId: string): string;
-    /**
-     * Finds and reads a trace by id. Searches the preferred run first (when given), then
-     * every other run most-recent first. Returns the parsed trace and the run it was found
-     * in, or undefined when no run contains it.
-     */
-    findTrace(traceId: string, preferredRunId?: string): {
-        trace: SerializedTrace;
-        runId: string;
-    } | undefined;
-    /**
-     * The most recently seen trace ids across the latest run — used by the REPL completer.
-     */
-    recentTraceIds(limit: number): string[];
-    private readJsonl;
-}

package/dist/types/store/serializers/serialized-span.interface.d.ts

@@ -1,14 +0,0 @@
-/**
- * The plain-object shape of a stored span — as produced by `TraceRenderer.serialize`
- * and rehydrated by `SpanDeserializer`.
- */
-export interface SerializedSpan {
-    id?: string;
-    keyname: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    children?: SerializedSpan[];
-}

package/dist/types/store/serializers/serialized-trace.interface.d.ts

@@ -1,14 +0,0 @@
-import { SerializedSpan } from "./serialized-span.interface";
-/**
- * The plain-object shape of a stored trace — as written to disk by
- * `ObservabilityTracer` and rehydrated by `TraceDeserializer`.
- */
-export interface SerializedTrace {
-    id: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    rootSpan?: SerializedSpan;
-}

package/dist/types/store/serializers/span-deserializer.d.ts

@@ -1,11 +0,0 @@
-import { Span, Trace } from "@pristine-ts/common";
-import { SerializedSpan } from "./serialized-span.interface";
-/**
- * Rebuilds a `Span` (with its full child tree) from the stored plain object. Used by
- * `TraceDeserializer` for the trace's root span and recursively for every descendant —
- * so `traceRenderer.renderTree`/`renderFlat`, which call instance methods like
- * `getDuration()`, work unchanged on stored traces.
- */
-export declare class SpanDeserializer {
-    static deserialize(serialized: SerializedSpan, trace: Trace): Span;
-}

package/dist/types/store/serializers/trace-deserializer.d.ts

@@ -1,9 +0,0 @@
-import { Trace } from "@pristine-ts/common";
-import { SerializedTrace } from "./serialized-trace.interface";
-/**
- * Rehydrates a stored trace JSON (the shape written by `ObservabilityTracer`) back into
- * a `Trace` instance, with its full span tree rebuilt via `SpanDeserializer`.
- */
-export declare class TraceDeserializer {
-    static deserialize(serialized: SerializedTrace): Trace;
-}

package/dist/types/store/trace-deserializer.d.ts

@@ -1,41 +0,0 @@
-import { Trace } from "@pristine-ts/common";
-/**
- * The plain-object shape of a stored span (as produced by `TraceRenderer.serialize`).
- */
-interface SerializedSpan {
-    id?: string;
-    keyname: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    children?: SerializedSpan[];
-}
-/**
- * The plain-object shape of a stored trace.
- */
-export interface SerializedTrace {
-    id: string;
-    startDate: number;
-    endDate?: number;
-    context?: {
-        [key: string]: string;
-    };
-    rootSpan?: SerializedSpan;
-}
-/**
- * Rehydrates a stored trace JSON (the shape written by `ObservabilityTracer`) back into
- * `Trace`/`Span` instances, so `traceRenderer.renderTree`/`renderFlat` — which call
- * instance methods like `getDuration()` — work unchanged on stored traces.
- *
- * Stateless; instantiate once and reuse, or use the static `deserialize`.
- */
-export declare class TraceDeserializer {
-    /**
-     * Rebuilds a `Trace` (with its full span tree) from the stored plain object.
-     */
-    static deserialize(serialized: SerializedTrace): Trace;
-    private static deserializeSpan;
-}
-export {};