---
description: Keep Telemetry, Observability, and the run log distinct, and apply the review level that matches the path a change touches.
globs: "packages/shared/src/telemetry/**,server/src/instrumentation.ts,doc/observability.md,packages/adapter-utils/src/duplex-observability.ts,server/src/services/duplex-observability-recorder.ts,packages/adapter-utils/src/acpx-engine/startup-timing.ts,doc/run-log-events.md,packages/db/src/schema/heartbeat_run_events.ts,server/src/services/heartbeat.ts"
alwaysApply: false
---

# Three data paths

## Scope and purpose

This repo has three separate data paths. Do not confuse them. Match a change to
a path by its file path, not by the word "observability" or "telemetry" alone.

This rule also applies to any file that adds or changes a caller of
`packages/shared/src/telemetry/events.ts` or
`packages/shared/src/telemetry/client.ts`, even when that file is outside the
globs above.

## The paths

- **Telemetry** is the Paperclip first-party event system. It is opt-out and it
  sends data to a Paperclip endpoint by default. Its paths are:
  - `packages/shared/src/telemetry/`
  - the generated contract `packages/shared/src/telemetry/generated/paperclip-telemetry.ts`
  - each caller of `packages/shared/src/telemetry/events.ts` or `packages/shared/src/telemetry/client.ts`
- **Observability** is the OpenTelemetry trace path. An operator must set an
  OTLP endpoint. Until an operator sets the endpoint, the tracer is a
  no-operation. Its paths are:
  - `server/src/instrumentation.ts`
  - `doc/observability.md`
  - `packages/adapter-utils/src/duplex-observability.ts`
  - `server/src/services/duplex-observability-recorder.ts`
  - the span attributes in `packages/adapter-utils/src/acpx-engine/startup-timing.ts`
- **The run log** holds rows in the local `heartbeat_run_events` table. The data
  stays in the instance database. Its paths are:
  - `doc/run-log-events.md`
  - `packages/db/src/schema/heartbeat_run_events.ts`
  - the append path `appendRunEvent` in `server/src/services/heartbeat.ts`

## Requirements

Apply a review level that matches the path:

- **Telemetry change (strict review).** The author updates the generated
  contract first. The author updates `packages/shared/src/telemetry/README.md`
  in the same pull request. The author requests a privacy review. Reason: a
  Telemetry event goes to a Paperclip endpoint by default, so a mistake sends
  data immediately.
- **Observability change (lighter review).** The operator endpoint gate stays in
  place. The no-operation behaviour stays when no endpoint is set. A privacy
  review is not necessary while the change stays inside the closed
  span-attribute allowlist.
- **Run-log change (no extra review).** A run-log change needs neither review
  level above, because the data stays in the instance database. Update
  `doc/run-log-events.md` when an event is added or changed.

## Exclusion

The word "observability" in a file such as
`server/src/services/recovery-observability.ts` names a different concept. Apply
this rule by path, not by word match.

## Review criteria

Identify which path each changed file belongs to. Flag a Telemetry change that
lacks the generated-contract update, the README update, or a privacy review
request. Flag an Observability change that emits without the operator endpoint
or adds a span attribute outside the allowlist. Flag data described as
"telemetry" or "observability" that is actually written to a different path. Do
not request a privacy review for a run-log-only change.