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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-PRESENT Neko Ayaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @proj-airi/trace-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Trace records, clocks, collection, and projections for AIRI agent and pipeline activity.
+
+The package depends only on `@proj-airi/stream-kit`, `es-toolkit`, and `valibot`. Then `core-agent`, `pipelines-audio`, and `plugin-protocol` can depend on it without a cycle.
+
+## Use it for
+
+- Writing what a module does as an ordered stream of records: span begin and end, instants, states, samples, and logs.
+- Joining work across windows, processes, and plugins by domain IDs and typed links, not by parent spans only.
+- Converting times of several clocks, such as windows, the main process, and audio streams, to one trace clock.
+- Keeping recent records in one collector, and feeding live views, files, and tests from it.
+- Turning records into view state with pure projections: timeline, event log, and metrics.
+
+## Do not use it for
+
+- Product UI. Product UI reads domain projections of eventa events, not traces.
+- Remote telemetry. Upload to a telemetry service is out of scope. A service that sends OpenTelemetry data can still import the names from `@proj-airi/trace-kit/semconv`.
+- Logs that a person reads in a terminal. Use `@guiiai/logg`.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@proj-airi/trace-kit/semconv` | Only the OpenTelemetry GenAI names: attribute keys, enum values, and metric names. It imports no other module, so a server can use it without the trace runtime. |
+| `@proj-airi/trace-kit` | Record types, the Valibot schema, the `define*` functions, `ClockGraph`, `TraceSource`, `TraceSpan`, `SeriesWriter` for frequent series such as audio levels, and the conventions |
+| `@proj-airi/trace-kit/collector` | `TraceCollector`: buffer, pinned set, series rings, watermarks, source lifecycle, and the flight recorder |
+| `@proj-airi/trace-kit/projections` | `TraceReader`, the timeline, the event log, and attribute metrics |
+| `@proj-airi/trace-kit/voice` | The voice profile: tracks, ID keys, names, attributes, metrics, and the floor transfer projection |
+| `@proj-airi/trace-kit/agent` | The agent profile: chat turns, model requests, tools, control, and background work |
+| `@proj-airi/trace-kit/views` | Pure view models of a trace: item lookups, related spans, track summaries, pipeline nodes, and `createTraceViewReader`. They return data, not display text. |
+
+The root entry does not import a profile.
+
+## Write records
+
+A producer writes to a `TraceSink`. A module without a sink uses `noopTraceSink`.
+
+```ts
+import { beginSpan, trackPath } from '@proj-airi/trace-kit'
+import { AgentNames, AgentTracks } from '@proj-airi/trace-kit/agent'
+
+const span = beginSpan(sink, {
+  track: trackPath(AgentTracks.LLM, { agent: 'agent' }),
+  name: AgentNames.ModelRequest,
+  ids: { conversation: sessionId, turn: turnId },
+})
+span.instant('llm.first_chunk')
+span.end({ attrs: { 'llm.ttft_ms': 412 } })
+```
+
+- `span.begin` is sent at once, so views show open work.
+- Carry the domain IDs that the producer already has. Do not look up an ID from another module.
+- Use a link for a relation that is not nesting, for example `caused-by` to the span that started the work.
+- Give `ts` as the time of the event. A record can be backdated.
+
+`TraceSource` stamps `source`, `epoch`, and `seq`, and announces the definitions of its profiles when it starts.
+
+## Attribute names
+
+Attribute names are constants in the style of `@opentelemetry/semantic-conventions`: `ATTR_<NAME>`.
+
+```ts
+import { ATTR_AIRI_TOPIC_ID, ATTR_GEN_AI_REQUEST_MODEL } from '@proj-airi/trace-kit'
+
+span.update({ [ATTR_GEN_AI_REQUEST_MODEL]: model, [ATTR_AIRI_TOPIC_ID]: topicId })
+```
+
+- The `gen_ai.*` names come from `src/conventions/semconv.ts`. It is generated from a pinned commit of [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai). `SEMCONV_GENAI_COMMIT` is that commit.
+- That repository has no release and no npm package. The GenAI exports of `@opentelemetry/semantic-conventions` are deprecated and use the old names.
+- Do not edit `src/conventions/semconv.ts` by hand. To upgrade, change `COMMIT` in `scripts/semconv/generate.ts` and run `pnpm -F @proj-airi/trace-kit generate:semconv`. The script needs network access.
+- Read the diff of the generated file. A removed or renamed name breaks the typecheck of each consumer. If a metric name changed, update the Grafana dashboards in `proj-airi/airi-deploy` in the same release.
+- When OpenTelemetry publishes an npm package for the GenAI conventions, import the names from it and delete the generator.
+- The other constants, for example `ATTR_CENSORED`, `ATTR_DECISION_LATENCY_MS`, and `ATTR_AIRI_TOPIC_ID`, are AIRI names.
+
+## Collect and read
+
+```ts
+const collector = new TraceCollector({ now: () => performance.now() })
+const timeline = createTimelineProjection()
+const reader = new TraceReader([timeline], collector.traceClock)
+collector.subscribe(message => reader.handle(message))
+reader.view(timeline).tracks
+```
+
+A subscription first gets the pinned set, the gaps, the buffer, and the series rings. Then it gets `caughtUp` and each later record. The host calls `collector.tick()` about once a second.
+
+The collector builds on the event stream primitives of `@proj-airi/stream-kit`: `RetentionBuffer`, `SequenceTracker`, `Watermark`, `DemandUnion`, `createLeaseTable`, `createCooldown`, and `createCatchUpFeed`. `onWantedChange` runs only when the union of the viewer tracks changes.
+
+A viewer that does not own the collector reads a `TraceFeedSource`: the trace clock and a `subscribe` function that sends `TraceFeedMessage` values. A host gives a local collector, a hub in another process, or a fixture as a feed source.
+
+To read a file or the records of a test, call `reader.handleRecords(records)`.
+
+The timeline keeps each series in a `SeriesRing` with the retention of the collector: the full rate for 5 minutes, then the minimum and the maximum of each second, for 30 minutes. A live view of a long session stays bounded. A file replay keeps every point with `createTimelineProjection({ seriesRetention: false })` or `createTraceViewReader(traceClock, { seriesRetention: false })`.
+
+## Clocks
+
+Each record names its clock. A source writes `clock.snapshot` records that pair its clock with another clock, and `clock.discontinuity` after sleep or a device change. `ClockGraph` fits offset and drift for each clock pair, and converts through the shortest path of pairs. A media stream clock counts frames. Declare its rate with `setUnitsPerMs`.
+
+A discontinuity starts a new segment, and the graph finds the segment of a value by the value. So a clock name must only go forward:
+
+- After a forward jump, for example sleep, write `clock.discontinuity` and a new `clock.snapshot`. A backdated value from before the jump still converts with the earlier snapshots.
+- After a backward reset, for example a restarted audio context, start a new clock name, for example `mono:window#2`. Write `clock.discontinuity` for the old name and a `clock.snapshot` for the new name. Otherwise a backdated value from before the reset converts with the new segment.

package/dist/clock-CewQJzn8.d.mts

@@ -0,0 +1,545 @@
+//#region src/core/types.d.ts
+/** Binary or large data, stored outside the record. */
+interface TraceAssetRef {
+  $asset: string;
+  mediaType: string;
+  bytes: number;
+}
+type TraceValue = string | number | boolean | string[] | number[] | TraceAssetRef;
+type TraceAttributes = Record<string, TraceValue>;
+/** Domain IDs by defined ID key, for example `{ turn: 't_1', actor: 'user' }`. */
+type TraceIds = Record<string, string | number>;
+/** Identifies one record of the stream. */
+interface TraceRef {
+  source: string;
+  epoch: string;
+  seq: number;
+}
+/**
+ * A typed relation from one record to another record, a span, or a domain ID.
+ *
+ * A link to a domain ID lets a producer link to work of another module without the `seq` of its record.
+ */
+interface TraceLink {
+  to: TraceRef | {
+    spanId: string;
+  } | {
+    key: string;
+    id: string | number;
+  };
+  /** A relation that `defineLink` declares, for example `caused-by` or `retry-of`. */
+  rel: string;
+}
+/** Fields of a record without a track: a system record or an annotation. */
+interface TraceUntrackedRecordBase {
+  /**
+   * Stable ID of one producer, for example `window:main`, `main`, `collector`, `plugin:minecraft`, or `server:api`.
+   * It must not contain `/`, because record, span, and epoch keys join their parts with `/`.
+   */
+  source: string;
+  /** One run of the source. A window reload or a plugin reconnect starts a new epoch. It must not contain `/`. */
+  epoch: string;
+  /** Emit order in the epoch, from 0. */
+  seq: number;
+  /** The raw value of `clock` when the event happened. It is not the emit time, so a producer can backdate it. */
+  ts: number;
+  clock: string;
+  /** The collector sets it on its own monotonic clock when it receives the record. */
+  observedTs?: number;
+  /** A stream uses it to name its actor. */
+  ids?: TraceIds;
+  attrs?: TraceAttributes;
+}
+/** Fields of a record about domain activity. */
+interface TraceRecordBase extends TraceUntrackedRecordBase {
+  /** A track path that matches a track definition, for example `participants/user/speech`. */
+  track: string;
+  links?: TraceLink[];
+  /** `reported` by the producer, or `observed` from outside, for example from audio. The default is `reported`. */
+  evidence?: 'reported' | 'observed';
+}
+/** `status` is closed. The open `reason` gives the detail, for example `interrupted`. */
+type TraceStatus = 'ok' | 'error' | 'cancelled';
+/** Who or what produced an annotation. */
+interface TraceAnnotator {
+  /** `rule`: deterministic code. `model`: an LLM or another model. `human`: a reviewer. */
+  kind: 'rule' | 'model' | 'human';
+  /** Stable name of the annotator, for example `wer` or `turn-judge`. */
+  id?: string;
+  /** The model ID when `kind` is `model`. */
+  model?: string;
+  /** A prompt hash, a rule set version, or a package version. */
+  version?: string;
+}
+type TraceSourceLostReason = 'ipc-closed' | 'heartbeat-timeout' | 'epoch-replaced';
+interface TraceSourceStarted extends TraceUntrackedRecordBase {
+  type: 'source.started';
+  format: number;
+  /** For example `electron-renderer`, `electron-main`, `browser`, or `node`. */
+  runtime: string;
+  profiles: {
+    key: string;
+    version: string;
+  }[];
+}
+interface TraceSourceStopped extends TraceUntrackedRecordBase {
+  type: 'source.stopped';
+}
+/** The collector writes it with its own identity. `of` names the lost epoch, so no `seq` of the lost source is used. */
+interface TraceSourceLost extends TraceUntrackedRecordBase {
+  type: 'source.lost';
+  of: {
+    source: string;
+    epoch: string;
+    lastSeq: number;
+  };
+  reason: TraceSourceLostReason;
+}
+/** The values of two or more clocks at one instant. */
+interface TraceClockSnapshot extends TraceUntrackedRecordBase {
+  type: 'clock.snapshot';
+  values: {
+    clock: string;
+    value: number;
+  }[];
+  uncertaintyMs: number;
+}
+/**
+ * A clock jumped or stopped, for example on sleep, a device change, or an audio context suspend.
+ *
+ * Values after a forward jump use only the later snapshots, and a backdated value from before the jump still uses the
+ * earlier ones. A backward reset makes old and new values overlap, so a value cannot tell its segment. A source whose
+ * clock goes back starts a new clock name, for example `mono:window#2`. It writes this record for the old name and a
+ * `clock.snapshot` for the new name.
+ */
+interface TraceClockDiscontinuity extends TraceUntrackedRecordBase {
+  type: 'clock.discontinuity';
+  of: string;
+  reason: string;
+}
+/** A media stream. It has its own clock. A recorded stream has a URI. */
+interface TraceStreamStarted extends TraceUntrackedRecordBase {
+  type: 'stream.started';
+  streamId: string;
+  mediaType: string;
+  rate?: number;
+  channels?: number;
+  uri?: string;
+}
+interface TraceStreamStopped extends TraceUntrackedRecordBase {
+  type: 'stream.stopped';
+  streamId: string;
+}
+interface TraceSpanBegin extends TraceRecordBase {
+  type: 'span.begin';
+  spanId: string;
+  /** Real nesting only. Any other relation is a link. */
+  parentSpanId?: string;
+  name: string;
+  /** The viewer marks the open span as overdue after this many milliseconds. It does not end the span. */
+  deadlineMs?: number;
+}
+/** Adds attributes to an open span. They merge shallowly in `seq` order, and the last write of a key wins. */
+interface TraceSpanUpdate extends TraceRecordBase {
+  type: 'span.update';
+  spanId: string;
+}
+interface TraceSpanEnd extends TraceRecordBase {
+  type: 'span.end';
+  spanId: string;
+  status: TraceStatus;
+  reason?: string;
+  message?: string;
+}
+/** A span that the producer measures after it ends. Chrome trace `X`. */
+interface TraceSpanComplete extends TraceRecordBase {
+  type: 'span.complete';
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  durationMs: number;
+  status: TraceStatus;
+  reason?: string;
+}
+/** With `spanId`, the instant belongs to that span. Without it, the instant belongs to its track only. */
+interface TraceInstant extends TraceRecordBase {
+  type: 'instant';
+  name: string;
+  spanId?: string;
+}
+/** A state change. `from` is the state that it leaves. The trigger is a `caused-by` link. */
+interface TraceState extends TraceRecordBase {
+  type: 'state';
+  value: string;
+  from?: string;
+}
+/** Values that change rarely. A frequent series uses `sample.chunk`. */
+interface TraceSample extends TraceRecordBase {
+  type: 'sample';
+  values: Record<string, number>;
+}
+/**
+ * About one second of a series. `ts` is the time of the first point.
+ * A regular series gives `intervalMs`. An irregular series gives `offsetsMs` from `ts`.
+ */
+interface TraceSampleChunk extends TraceRecordBase {
+  type: 'sample.chunk';
+  intervalMs?: number;
+  offsetsMs?: number[];
+  values: Record<string, number[]>;
+}
+interface TraceLog extends TraceRecordBase {
+  type: 'log';
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+}
+/** Announces one definition before the first record that uses it, and again when it changes. */
+interface TraceDefinitionRecord extends TraceUntrackedRecordBase {
+  type: 'definition';
+  kind: TraceDefinitionKind;
+  key: string;
+  data: unknown;
+}
+/** A label, score, or evaluation that is added later. A producer decision is not an annotation. */
+interface TraceAnnotation extends TraceUntrackedRecordBase {
+  type: 'annotation';
+  target: {
+    ref?: TraceRef;
+    spanId?: string;
+    ids?: TraceIds;
+  };
+  name: string;
+  value?: TraceValue;
+  label?: string;
+  explanation?: string;
+  annotator: TraceAnnotator;
+}
+type TraceRecord = TraceSourceStarted | TraceSourceStopped | TraceSourceLost | TraceClockSnapshot | TraceClockDiscontinuity | TraceStreamStarted | TraceStreamStopped | TraceSpanBegin | TraceSpanUpdate | TraceSpanEnd | TraceSpanComplete | TraceInstant | TraceState | TraceSample | TraceSampleChunk | TraceLog | TraceDefinitionRecord | TraceAnnotation;
+type TraceRecordType = TraceRecord['type'];
+/** A record with a track. */
+type TraceTrackedRecord = Extract<TraceRecord, {
+  track: string;
+}>;
+/** A record that describes the trace itself. */
+type TraceSystemRecord = Extract<TraceRecord, {
+  type: 'source.started' | 'source.stopped' | 'source.lost' | 'clock.snapshot' | 'clock.discontinuity' | 'stream.started' | 'stream.stopped' | 'definition';
+}>;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A record as a producer emits it. The source stamps `source`, `epoch`, and `seq`. The collector sets `observedTs`.
+ * `clock` is optional: the source fills in its own monotonic clock.
+ */
+type TraceRecordInput = DistributiveOmit<TraceRecord, 'source' | 'epoch' | 'seq' | 'observedTs' | 'clock'> & {
+  clock?: string;
+};
+/** One string, or one string for each BCP 47 locale. */
+type Localizable = string | Record<string, string>;
+type TraceDefinitionKind = 'track' | 'attribute' | 'id-key' | 'link' | 'end-reason' | 'clock' | 'metric' | 'score' | 'pipeline' | 'preset' | 'profile';
+//#endregion
+//#region src/core/definitions.d.ts
+/** Label and hover text of a key. A key without them still works, and the viewer shows the raw key. */
+interface TraceText {
+  label?: Localizable;
+  /** What the key means and how to read it. */
+  description?: Localizable;
+}
+type TraceTrackRender = 'spans' | 'instants' | 'state' | 'series';
+/**
+ * How the spans of a track show on the lane of their entity.
+ *
+ * - `waiting`: the entity holds a turn or a request and waits, for example for a sub-agent. Drawn hatched, below the rest.
+ * - `thinking`: work before output, such as a model request before its first chunk, recognition, or a judgement. Drawn light.
+ * - `active`: output or an action, such as speech, generation, playback, or a tool call. Drawn solid, on top.
+ */
+type TraceActivity = 'waiting' | 'thinking' | 'active';
+interface TraceTrackDefinition extends TraceText {
+  /** A path pattern. `{key}` matches one segment, named by an ID key, for example `participants/{actor}/speech`. */
+  path: string;
+  /** An open string. Profiles give their own groups. The viewer groups lanes by it. */
+  group: string;
+  /** Lane order inside the group. Lower comes first. */
+  order: number;
+  /** One track can combine kinds, for example `['spans', 'state']`. */
+  render: TraceTrackRender[];
+  color?: string;
+  icon?: string;
+  unit?: string;
+  /** The values of a state track, in legend order. */
+  states?: string[];
+  /**
+   * `single`: one source writes the state of this track, and a record from another source is a warning.
+   * `any`: every source can write it.
+   * @default 'single'
+   */
+  stateOwner?: 'single' | 'any';
+  /** Retention and sampling hints for the collector. */
+  retention?: {
+    keep: 'latest' | 'window';
+    maxHz?: number;
+    fullRateS?: number;
+  };
+  /**
+   * The `{key}` of the path that names the entity of the track, for example `actor` or `agent`. The viewer draws one
+   * lane for each entity value, and tracks of different patterns with the same value share it.
+   */
+  entity?: string;
+  /** How the spans of the track show on the entity lane. A track without it shows only in the expanded rows. */
+  activity?: TraceActivity;
+  /** An instant inside a span that changes its activity, for example `llm.first_chunk` from `thinking` to `active`. */
+  activitySplit?: {
+    instant: string;
+    activity: TraceActivity;
+  };
+  /**
+   * What a span of this track shows on its item in the timeline. Leave it unset when the track name already tells what
+   * a span is. Set `name` when the span names differ in a useful way, for example the tool name of a tool call. The
+   * hover card shows the name in both cases.
+   */
+  itemLabel?: 'name';
+}
+interface TraceAttributeDefinition extends TraceText {
+  key: string;
+  type: 'string' | 'number' | 'boolean' | 'list' | 'asset' | 'json';
+  unit?: string;
+  /**
+   * `content` is user content. Files on disk and exports remove it unless a developer setting keeps it.
+   * `secret` never leaves the process.
+   */
+  sensitivity: 'none' | 'content' | 'secret';
+  aggregatable?: boolean;
+}
+interface TraceIdKeyDefinition extends TraceText {
+  key: string;
+}
+interface TraceLinkDefinition extends TraceText {
+  rel: string;
+}
+interface TraceEndReasonDefinition extends TraceText {
+  reason: string;
+}
+interface TraceClockDefinition extends TraceText {
+  /** A key pattern, for example `mono:window:{window}` or `audio:capture:{stream}`. */
+  pattern: string;
+  /** `ms` for system clocks. `frames` for media streams. */
+  unit: 'ms' | 'frames';
+  /** Whether the clock stops during system sleep, when that is known. */
+  stopsInSleep?: boolean;
+}
+/** How a metric finds its values. */
+type TraceMetricValue = {
+  kind: 'attribute';
+  track: string;
+  record: TraceRecordType;
+  attribute: string;
+} |
+/** A first-party projection computes the value. */
+{
+  kind: 'derived';
+  projection: string;
+};
+type TraceAggregate = 'p50' | 'p95' | 'p99' | 'mean' | 'sum' | 'count';
+interface TraceMetricDefinition extends TraceText {
+  key: string;
+  unit?: string;
+  /** Whether a larger value is better (`higher`) or a smaller value is better (`lower`). */
+  better?: 'higher' | 'lower';
+  /** ID keys that split the metric, for example `['from', 'to']` for a matrix of participant pairs. */
+  dimensions?: string[];
+  /** @default ['p50', 'p95'] */
+  aggregate?: TraceAggregate[];
+  /**
+   * `session` keeps the values of the whole session. `window` uses the buffer only.
+   * @default 'window'
+   */
+  scope?: 'session' | 'window';
+  value: TraceMetricValue;
+}
+/** An annotation name for a score from 0 to 1, where higher is better. */
+interface TraceScoreDefinition extends TraceText {
+  key: string;
+  /** What usually produces the value. An annotation can name another annotator. */
+  annotator?: TraceAnnotator;
+}
+interface TracePipelineStage {
+  key: string;
+  label: Localizable;
+  /** Track path patterns. A pattern with `{key}` gives one stage instance for each value. */
+  tracks: string[];
+}
+interface TracePipelineDefinition extends TraceText {
+  key: string;
+  stages: TracePipelineStage[];
+  /** `kind` is open. The conventions define `cmd`, `data`, `audio`, and `signal`. Cycles are allowed. */
+  edges: {
+    from: string;
+    to: string;
+    kind: string;
+    name: string;
+  }[];
+}
+/** A view preset: the track paths to show, and the layout. */
+interface TracePresetDefinition extends TraceText {
+  key: string;
+  /** Track path patterns. */
+  tracks: string[];
+  /** @default 'timeline' */
+  layout?: 'timeline' | 'pipeline' | 'log';
+}
+interface TraceProfileDefinition extends TraceText {
+  /** `voice`, `agent`, or `plugin:<id>`. */
+  key: string;
+  version: string;
+  tracks?: TraceTrackDefinition[];
+  attributes?: TraceAttributeDefinition[];
+  idKeys?: TraceIdKeyDefinition[];
+  links?: TraceLinkDefinition[];
+  endReasons?: TraceEndReasonDefinition[];
+  clocks?: TraceClockDefinition[];
+  metrics?: TraceMetricDefinition[];
+  scores?: TraceScoreDefinition[];
+  pipelines?: TracePipelineDefinition[];
+  presets?: TracePresetDefinition[];
+}
+//#endregion
+//#region src/core/feed.d.ts
+/** The kept points of one series, on the trace clock. Old points are reduced to the min and max of each second. */
+interface TraceSeriesMessage {
+  kind: 'series';
+  source: string;
+  track: string;
+  key: string;
+  times: number[];
+  values: number[];
+}
+/**
+ * One message of a collector feed to a viewer.
+ *
+ * A subscription first sends the pinned set (`pinned: true`), the gaps, the buffered records, and the series rings.
+ * Then it sends `caughtUp`, and after that each later record.
+ * `gap` and `caughtUp` are feed markers, not trace records. The disk recording does not write them.
+ */
+type TraceFeedMessage = {
+  kind: 'record';
+  record: TraceRecord;
+  /** The record came from the pinned set, which stays outside the buffer limits. */
+  pinned?: boolean;
+  /** The record arrived after the watermark of its source. It changes the view with a `late` mark. */
+  late?: boolean;
+} |
+/** The buffer evicted records in this range of the trace clock. */
+{
+  kind: 'gap';
+  from: number;
+  to: number;
+} | TraceSeriesMessage |
+/**
+ * The end of the backlog. `cursor` has the last `seq` of each `source/epoch`. `now` is the trace clock at that moment,
+ * so a viewer can run a live clock before the next record arrives.
+ */
+{
+  kind: 'caughtUp';
+  cursor: Record<string, number>;
+  traceClock: string;
+  now?: number;
+};
+/**
+ * A collector feed that a tracer view reads.
+ *
+ * The host sets one: a local collector, a hub in another process, or a fixture in a story. The view store subscribes
+ * to it and gives each message to its reader.
+ */
+interface TraceFeedSource {
+  /** The clock that the collector converts every value to. A reader converts to the same clock. */
+  traceClock: string;
+  /**
+   * Calls `onMessage` with the backlog and then with each later message.
+   * `tracks` are the track paths that the view shows, so producers can skip costly series of other tracks.
+   */
+  subscribe: (onMessage: (message: TraceFeedMessage) => void, tracks: string[] | '*') => Promise<{
+    unsubscribe: () => void;
+    setTracks: (tracks: string[] | '*') => void;
+  }>;
+}
+//#endregion
+//#region src/core/clock.d.ts
+interface ClockConversion {
+  value: number;
+  /** A clock on the path has no measured latency, or a pair has only one sample of a non-ms clock. */
+  estimated: boolean;
+}
+interface ClockGraphOptions {
+  /**
+   * Snapshots in the drift fit of each clock pair. A drift of 50 ppm adds 3 ms each minute, so offset alone is not
+   * enough for long sessions.
+   * @default 16
+   */
+  fitWindow?: number;
+}
+/**
+ * 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.
+ */
+declare class ClockGraph {
+  readonly traceClock: string;
+  private readonly options;
+  /** Units of each clock in one millisecond. A media clock in frames at 48 kHz has 48. */
+  private readonly unitsPerMs;
+  private readonly pairs;
+  private readonly paths;
+  constructor(traceClock: string, options?: ClockGraphOptions);
+  /** Declares the unit of a clock. A clock without a declared unit counts in milliseconds. */
+  setUnitsPerMs(clock: string, unitsPerMs: number): void;
+  addSnapshot(values: {
+    clock: string;
+    value: number;
+  }[], uncertaintyMs: number, estimated?: boolean): void;
+  /** Starts a new segment for every pair of `clock`. Earlier samples stay for values before the jump. */
+  addDiscontinuity(clock: string): void;
+  /** Forgets every unit, snapshot, and discontinuity, for example before a reader reads another trace. */
+  clear(): void;
+  /** Converts a value of `clock` to the trace clock. Returns `undefined` when no snapshot path exists. */
+  convert(clock: string, value: number): ClockConversion | undefined;
+  private addSample;
+  /**
+   * 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²`.
+   */
+  private fit;
+  /** Breadth-first search from `clock` to the trace clock. The result is cached until a new pair appears. */
+  private pathTo;
+}
+interface ClockPingSample {
+  /** The local clock value at the middle of the round trip. */
+  local: number;
+  /** The remote clock value that the reply carried. */
+  remote: number;
+  /** Half the round trip. */
+  uncertaintyMs: number;
+}
+/**
+ * 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.
+ */
+declare function measureClockOffset(options: {
+  ping: () => Promise<number>;
+  now: () => number;
+  /** @default 5 */
+  count?: number;
+}): Promise<ClockPingSample | undefined>;
+//#endregion
+export { TraceSpanUpdate as $, TraceAttributes as A, TraceRecordBase as B, TraceText as C, TraceAnnotation as D, Localizable as E, TraceIds as F, TraceSampleChunk as G, TraceRecordType as H, TraceInstant as I, TraceSourceStarted as J, TraceSourceLost as K, TraceLink as L, TraceClockSnapshot as M, TraceDefinitionKind as N, TraceAnnotator as O, TraceDefinitionRecord as P, TraceSpanEnd as Q, TraceLog as R, TraceScoreDefinition as S, TraceTrackRender as T, TraceRef as U, TraceRecordInput as V, TraceSample as W, TraceSpanBegin as X, TraceSourceStopped as Y, TraceSpanComplete as Z, TraceMetricValue as _, measureClockOffset as a, TraceTrackedRecord as at, TracePresetDefinition as b, TraceSeriesMessage as c, TraceAttributeDefinition as d, TraceState as et, TraceClockDefinition as f, TraceMetricDefinition as g, TraceLinkDefinition as h, ClockPingSample as i, TraceSystemRecord as it, TraceClockDiscontinuity as j, TraceAssetRef as k, TraceActivity as l, TraceIdKeyDefinition as m, ClockGraph as n, TraceStreamStarted as nt, TraceFeedMessage as o, TraceUntrackedRecordBase as ot, TraceEndReasonDefinition as p, TraceSourceLostReason as q, ClockGraphOptions as r, TraceStreamStopped as rt, TraceFeedSource as s, TraceValue as st, ClockConversion as t, TraceStatus as tt, TraceAggregate as u, TracePipelineDefinition as v, TraceTrackDefinition as w, TraceProfileDefinition as x, TracePipelineStage as y, TraceRecord as z };