@proj-airi/trace-kit 0.0.0-stage → 0.15.2

package/dist/clock-hjTPEs21.mjs

@@ -0,0 +1,212 @@
+//#region src/core/clock.ts
+const DEFAULT_OPTIONS = { fitWindow: 16 };
+/** Weight floor in ms, so a sample with zero uncertainty does not take the whole fit. */
+const MIN_UNCERTAINTY_MS = .05;
+/**
+* Converts values of any clock to one trace clock.
+*
+* State model:
+* - Each `clock.snapshot` adds one sample to every clock pair in it, in both directions.
+* - A `clock.discontinuity` starts a new segment for each pair of that clock. Values after it use only later samples.
+*   A segment is found by value, so a clock must only jump forward. A clock that goes back gets a new name.
+* - A conversion walks the shortest path of pairs from the clock to the trace clock, and composes the fits.
+*
+* The graph does not read a clock. It is a pure function of the snapshots that it received.
+*/
+var ClockGraph = class {
+	traceClock;
+	options;
+	/** Units of each clock in one millisecond. A media clock in frames at 48 kHz has 48. */
+	unitsPerMs = /* @__PURE__ */ new Map();
+	pairs = /* @__PURE__ */ new Map();
+	paths = /* @__PURE__ */ new Map();
+	constructor(traceClock, options) {
+		this.traceClock = traceClock;
+		this.options = {
+			...DEFAULT_OPTIONS,
+			...options
+		};
+	}
+	/** Declares the unit of a clock. A clock without a declared unit counts in milliseconds. */
+	setUnitsPerMs(clock, unitsPerMs) {
+		this.unitsPerMs.set(clock, unitsPerMs);
+	}
+	addSnapshot(values, uncertaintyMs, estimated = false) {
+		for (const [index, a] of values.entries()) for (const b of values.slice(index + 1)) {
+			if (a.clock === b.clock) continue;
+			this.addSample(a.clock, b.clock, {
+				from: a.value,
+				to: b.value,
+				uncertaintyMs,
+				estimated
+			});
+			this.addSample(b.clock, a.clock, {
+				from: b.value,
+				to: a.value,
+				uncertaintyMs,
+				estimated
+			});
+		}
+	}
+	/** Starts a new segment for every pair of `clock`. Earlier samples stay for values before the jump. */
+	addDiscontinuity(clock) {
+		for (const [from, targets] of this.pairs) for (const [to, segments] of targets) if (from === clock || to === clock) segments.push({
+			startFrom: Number.POSITIVE_INFINITY,
+			samples: []
+		});
+	}
+	/** Forgets every unit, snapshot, and discontinuity, for example before a reader reads another trace. */
+	clear() {
+		this.unitsPerMs.clear();
+		this.pairs.clear();
+		this.paths.clear();
+	}
+	/** Converts a value of `clock` to the trace clock. Returns `undefined` when no snapshot path exists. */
+	convert(clock, value) {
+		if (clock === this.traceClock) return {
+			value,
+			estimated: false
+		};
+		const path = this.pathTo(clock);
+		if (!path) return void 0;
+		let current = value;
+		let estimated = false;
+		for (let index = 0; index < path.length - 1; index++) {
+			const map = this.fit(path[index], path[index + 1], current);
+			if (!map) return void 0;
+			current = current * map.slope + map.offset;
+			estimated ||= map.estimated;
+		}
+		return {
+			value: current,
+			estimated
+		};
+	}
+	addSample(from, to, sample) {
+		let targets = this.pairs.get(from);
+		if (!targets) {
+			targets = /* @__PURE__ */ new Map();
+			this.pairs.set(from, targets);
+		}
+		let segments = targets.get(to);
+		if (!segments) {
+			segments = [];
+			targets.set(to, segments);
+			this.paths.clear();
+		}
+		let segment = segments.at(-1);
+		if (!segment) {
+			segment = {
+				startFrom: sample.from,
+				samples: []
+			};
+			segments.push(segment);
+		}
+		if (segment.samples.length === 0) segment.startFrom = sample.from;
+		segment.samples.push(sample);
+		if (segment.samples.length > this.options.fitWindow) segment.samples.shift();
+	}
+	/**
+	* Fits `to = from * slope + offset` over the samples of the segment that holds `value`.
+	*
+	* The segment is the latest one that starts at or before `value`. This is correct when a clock only jumps forward.
+	* After a backward reset, a value from before the reset can match the new segment. So a clock that goes back must
+	* get a new name, as the `clock.discontinuity` record type says.
+	*
+	* One sample gives the offset only, with the slope from the declared units. Two or more samples give a weighted
+	* least squares fit, which also measures drift. Each sample weighs `1 / uncertainty²`.
+	*/
+	fit(from, to, value) {
+		const segments = this.pairs.get(from)?.get(to);
+		if (!segments) return void 0;
+		let segment = segments.find((candidate) => candidate.samples.length > 0);
+		for (const candidate of segments) if (candidate.samples.length > 0 && candidate.startFrom <= value) segment = candidate;
+		if (!segment) return void 0;
+		const unitSlope = (this.unitsPerMs.get(to) ?? 1) / (this.unitsPerMs.get(from) ?? 1);
+		const samples = segment.samples;
+		const estimated = samples.some((sample) => sample.estimated);
+		if (samples.length === 1) {
+			const sample = samples[0];
+			return {
+				slope: unitSlope,
+				offset: sample.to - sample.from * unitSlope,
+				estimated: estimated || unitSlope !== 1
+			};
+		}
+		let weightSum = 0;
+		let meanFrom = 0;
+		let meanTo = 0;
+		for (const sample of samples) {
+			const weight = 1 / Math.max(sample.uncertaintyMs, MIN_UNCERTAINTY_MS) ** 2;
+			weightSum += weight;
+			meanFrom += weight * sample.from;
+			meanTo += weight * sample.to;
+		}
+		meanFrom /= weightSum;
+		meanTo /= weightSum;
+		let covariance = 0;
+		let variance = 0;
+		for (const sample of samples) {
+			const weight = 1 / Math.max(sample.uncertaintyMs, MIN_UNCERTAINTY_MS) ** 2;
+			covariance += weight * (sample.from - meanFrom) * (sample.to - meanTo);
+			variance += weight * (sample.from - meanFrom) ** 2;
+		}
+		const slope = variance > 0 ? covariance / variance : unitSlope;
+		return {
+			slope,
+			offset: meanTo - meanFrom * slope,
+			estimated
+		};
+	}
+	/** Breadth-first search from `clock` to the trace clock. The result is cached until a new pair appears. */
+	pathTo(clock) {
+		const cached = this.paths.get(clock);
+		if (cached !== void 0) return cached ?? void 0;
+		const previous = /* @__PURE__ */ new Map([[clock, clock]]);
+		const queue = [clock];
+		while (queue.length > 0) {
+			const current = queue.shift();
+			if (current === this.traceClock) break;
+			for (const next of this.pairs.get(current)?.keys() ?? []) {
+				if (previous.has(next)) continue;
+				previous.set(next, current);
+				queue.push(next);
+			}
+		}
+		if (!previous.has(this.traceClock)) {
+			this.paths.set(clock, null);
+			return;
+		}
+		const path = [this.traceClock];
+		while (path[0] !== clock) path.unshift(previous.get(path[0]));
+		this.paths.set(clock, path);
+		return path;
+	}
+};
+/**
+* Runs a ping exchange with a remote clock and returns the sample with the smallest round trip.
+*
+* Each ping asks the remote side for its clock value. The local value at the middle of the round trip pairs with it.
+* Half the round trip is the uncertainty. A failed ping is skipped. Returns `undefined` when every ping failed.
+*/
+async function measureClockOffset(options) {
+	let best;
+	for (let index = 0; index < (options.count ?? 5); index++) {
+		const sentAt = options.now();
+		let remote;
+		try {
+			remote = await options.ping();
+		} catch {
+			continue;
+		}
+		const uncertaintyMs = (options.now() - sentAt) / 2;
+		if (!best || uncertaintyMs < best.uncertaintyMs) best = {
+			local: sentAt + uncertaintyMs,
+			remote,
+			uncertaintyMs
+		};
+	}
+	return best;
+}
+//#endregion
+export { measureClockOffset as n, ClockGraph as t };

package/dist/collector/index.d.mts

@@ -0,0 +1,207 @@
+import { n as SeriesRetention, r as SeriesRing, t as DEFAULT_SERIES_RETENTION } from "../series-ring-DCb7czkl.mjs";
+import { V as TraceRecordInput, c as TraceSeriesMessage, d as TraceAttributeDefinition, n as ClockGraph, o as TraceFeedMessage, z as TraceRecord } from "../clock-CewQJzn8.mjs";
+//#region src/collector/types.d.ts
+/** A manual save of a collector. */
+interface CollectorSnapshot {
+  /** The pinned set and the buffer, in the order of a backlog. */
+  records: TraceRecord[];
+  /** The series rings. The buffer does not hold samples. */
+  series: TraceSeriesMessage[];
+}
+interface FlightRecorderDump {
+  /** The records of the window, in buffer order. With `append`, only the records after the previous dump. */
+  records: TraceRecord[];
+  /** Append to the previous dump file. The window overlaps the previous dump. */
+  append: boolean;
+  reason: 'error' | 'overdue';
+  /** The window on the trace clock. */
+  from: number;
+  to: number;
+}
+//#endregion
+//#region src/collector/collector.d.ts
+interface TraceCollectorOptions {
+  /**
+   * The monotonic clock of the collector. It is the trace clock: every value converts to it.
+   * @default 'mono:collector'
+   */
+  clock?: string;
+  /** The value of the collector clock now. */
+  now: () => number;
+  /** @default 30 minutes */
+  maxAgeMs?: number;
+  /** UTF-8 bytes of the JSON of the event buffer. Objects in memory are often 2 to 3 times larger. @default 16 MB */
+  maxBytes?: number;
+  /** Series rings keep the full rate for this time, then the min and max of each second. @default 5 minutes */
+  seriesFullRateMs?: number;
+  /** A record later than this behind the newest record of its source is late. @default 5 seconds */
+  allowedLatenessMs?: number;
+  /** A source without any record or ping for this time is lost. @default 60 seconds */
+  heartbeatTimeoutMs?: number;
+  /** Writes the preceding window of the buffer when a span fails or goes overdue. */
+  flightRecorder?: {
+    /** @default 60 seconds */
+    windowMs?: number;
+    /** A trigger from the same source in this time does not start a new dump. @default 60 seconds */
+    cooldownMs?: number;
+    /** UTF-8 bytes of the flight window that the collector keeps while buffering is off. @default 2 MB */
+    maxBytes?: number;
+    onDump: (dump: FlightRecorderDump) => void;
+  };
+  /** Receives the union of the tracks that viewers show. Producers skip costly series that no reader wants. */
+  onWantedChange?: (tracks: ReadonlySet<string> | '*') => void;
+  /** @default crypto.randomUUID */
+  createEpoch?: () => string;
+}
+/**
+ * Receives the records of every source in one place, keeps recent records, and feeds viewers.
+ *
+ * State model:
+ * - Epochs: one {@link EpochState} for each `source/epoch`. A record with a seen seq is dropped.
+ * - Heartbeats: one lease for each `source/epoch`. Each new record and each `touch` renews it. A live epoch whose
+ *   lease expires is lost.
+ * - Event buffer: every record except series, limited by age and bytes. Eviction records a gap.
+ * - Series rings: one {@link SeriesRing} for each `track` and value key of `sample` and `sample.chunk` records.
+ * - Pinned set: the latest `source.started` of each live epoch, live streams, recent clock snapshots and the
+ *   discontinuities between them, open spans with merged updates, the latest state of each state track, and the latest
+ *   definition of each kind and key. It stays outside the limits, so a late viewer and a dump can describe themselves.
+ * - Clock records: a reader picks the clock segment of a value from the snapshots and discontinuities that it applied
+ *   before. So a backlog or a dump sends a pinned clock record only when it does not also send its buffered copy, and
+ *   the clock history keeps its arrival order.
+ * - The collector is a source too. It writes `source.lost` with its own identity.
+ *
+ * The host calls {@link TraceCollector.tick} about once a second. It compacts series, evicts old records, checks
+ * heartbeats, and checks span deadlines. The collector reads no clock except `now`.
+ */
+declare class TraceCollector {
+  readonly traceClock: string;
+  readonly clocks: ClockGraph;
+  private readonly options;
+  private readonly self;
+  private readonly epochs;
+  /** The live epoch of each source. */
+  private readonly liveEpochBySource;
+  private readonly heartbeats;
+  private readonly buffer;
+  /** The groups that the buffer dropped in the current push or eviction. They become one gap. */
+  private evicted;
+  private gaps;
+  private readonly seriesRings;
+  private readonly pinnedStarts;
+  private readonly pinnedStreams;
+  private readonly pinnedSnapshots;
+  private pinnedDiscontinuities;
+  private arrivals;
+  private readonly pinnedSpans;
+  private readonly pinnedStates;
+  private readonly pinnedDefinitions;
+  private readonly attributeSensitivity;
+  private readonly feed;
+  /** The tracks of each viewer, by subscription ID. */
+  private readonly demand;
+  private nextSubscriptionId;
+  /** The open spans that already triggered an overdue dump. A key goes when its span ends or its epoch ends. */
+  private readonly dumpedSpans;
+  /** The flight recorder cooldown of each source. */
+  private readonly dumpCooldown;
+  private lastDumpEnd;
+  private lateCount;
+  private droppedCount;
+  /** Off: the collector forwards records to viewers but keeps only the pinned set and the flight window. */
+  private buffering;
+  /**
+   * The records of the last flight window while buffering is off, for the flight recorder only. Viewers never read it,
+   * so a view that opens while buffering is off still has no history.
+   */
+  private readonly flightWindow?;
+  constructor(options: TraceCollectorOptions);
+  get stats(): {
+    bufferedRecords: number;
+    bufferedBytes: number;
+    openSpans: number;
+    seriesTracks: number;
+    late: number;
+    dropped: number;
+    maxAgeMs: number;
+    maxBytes: number;
+  };
+  /**
+   * Validates a record from a trust boundary, such as IPC from a window, then ingests it.
+   * Returns false and counts the record as dropped when it is not a valid record.
+   */
+  ingestUntrusted(value: unknown): boolean;
+  /**
+   * Turns the event buffer and the series rings on or off. Off drops what they hold. Viewers still get live records,
+   * and the pinned set stays, so a viewer that opens later still knows the live sources and open spans. With a flight
+   * recorder, off keeps the last flight window of events for dumps only.
+   */
+  setBuffering(enabled: boolean): void;
+  /** Writes a record of the collector itself, for example a discontinuity of its clock after a system resume. */
+  record(input: TraceRecordInput): void;
+  /** Ingests a record of a trusted producer in the same process. */
+  ingest(record: TraceRecord): void;
+  /** Records that a source is alive without a record, for example on a clock ping. */
+  touch(source: string): void;
+  /** The transport of a source closed. Its live epoch is lost unless it stopped first. */
+  closeSource(source: string): void;
+  /**
+   * Adds a viewer. It receives the pinned set, the gaps, the buffer, the series, `caughtUp`, and then each later
+   * record, in that order. Nothing arrives between the backlog and the first live record, because one call does both.
+   */
+  subscribe(listener: (message: TraceFeedMessage) => void, tracks?: Iterable<string> | '*'): {
+    unsubscribe: () => void;
+    setTracks: (tracks: Iterable<string> | '*') => void;
+  };
+  /**
+   * Runs the periodic work: series compaction, buffer eviction, heartbeat checks, and span deadline checks.
+   * The host calls it about once a second.
+   */
+  tick(): void;
+  /**
+   * The current state for a manual save: the pinned set and the buffer as records, and the series rings in the shape
+   * of the backlog. Samples go to the rings, not to the buffer, so the records alone do not hold them. A reader
+   * replays the save with `handleRecords(records)` and then `handle(message)` for each series message.
+   */
+  snapshot(): CollectorSnapshot;
+  /** The sensitivity of an attribute key, from the conventions and the announced definitions. */
+  sensitivityOf: (key: string) => TraceAttributeDefinition["sensitivity"] | undefined;
+  private accept;
+  private createEpoch;
+  /** The last seq of each `source/epoch`. */
+  private cursor;
+  /** The backlog of a new viewer: the pinned set, the gaps, the buffer, and the series. */
+  private backlog;
+  /** One message for each series ring that has points. */
+  private seriesMessages;
+  /** Converts the event time of a record to the trace clock. */
+  private timeOf;
+  private updateClocks;
+  private updateDefinitions;
+  private updatePinned;
+  /**
+   * Moves the links of evicted updates into the pinned copy of their open span. The pinned copy merges the attributes
+   * of each update on arrival. Links append, so they move only when the update leaves the buffer, and a late viewer
+   * does not get a link twice.
+   */
+  private keepLinksOfEvictedUpdates;
+  /** A discontinuity matters only after a pinned snapshot of its clock. A reader has no earlier segment otherwise. */
+  private prunePinnedDiscontinuities;
+  private unpinEpoch;
+  private loseSource;
+  private appendSeries;
+  /** Turns the records that the buffer dropped since the last call into one gap, and tells the viewers. */
+  private reportGap;
+  /**
+   * Starts a flight recorder dump. Limits: an open span triggers one overdue dump, each source has a cooldown, and a
+   * window that overlaps the previous dump appends to it. An error comes from the one end of a span, so it needs no
+   * guard, and the guard does not keep the key of an ended span.
+   */
+  private triggerDump;
+  /**
+   * The pinned set. `sentFrom` is the arrival order of the first buffered record that the caller also sends. A clock
+   * record from that order on is left out, so the reader applies it once, at its place among the buffered records.
+   */
+  private pinnedRecords;
+}
+//#endregion
+export { CollectorSnapshot, DEFAULT_SERIES_RETENTION, FlightRecorderDump, SeriesRetention, SeriesRing, TraceCollector, TraceCollectorOptions };