Files
hyperframes/packages/cli/src/telemetry/runId.ts
T
WaterrrForever 3b65321a20 feat(cli): classify identity persistence on every telemetry event (#3065)
* feat(cli): classify identity persistence on every telemetry event

Install-grain metrics currently trust every anonymousId equally, but
ephemeral/isolated-HOME workloads mint a fresh id per run — one machine
produced 2,956 rotating render identities since Jul 30 (94.4% seen on a
single render command), inflating acquisition and diluting per-install
penetration while looking like real product usage.

Every event now carries:

- identity_persistence: durable (id loaded from a preexisting config —
  proven to survive a process boundary) | unknown (minted+persisted this
  run; an ephemeral HOME is indistinguishable from a genuine first run
  from inside one process) | process_only (persist failed). Sticky per
  process so a fresh install re-reading its own write cannot self-promote.
- config_write_outcome: ok | ok_unmirrored | failed for the identity-
  establishing write; absent when the id came from disk.
- invocation_id: random uuid per CLI process, so one invocation's events
  group even when the install identity is untrustworthy (unlike run_id,
  which needs an orchestrator to set HYPERFRAMES_RUN_ID).

Install metrics can then count only durable identities, and a daily
churn monitor can alert on the unknown share.

* fix(cli): require the anonymousId to come off disk before classifying durable

Review finding: materializeConfig mints a replacement anonymousId when a
hand-edited/image-baked config lacks one. That replacement only reaches
disk when the bucket-seed backfill happens to write; with a seed present
the read path performs no write at all, so the install re-mints a fresh
id every run while the unconditional durable branch stamped each of them
with the one label durable-only counting is allowed to trust.

durable now requires parseNonEmptyString(parsed.anonymousId): a minted
replacement classifies like a fresh mint — by the backfill write outcome
when that path runs (unknown/process_only), and process_only on the
no-write path where the id provably dies with the process. Two tests pin
both shapes.
2026-08-06 22:19:14 +08:00

31 lines
1.0 KiB
TypeScript

import { randomUUID } from "node:crypto";
let resolved = false;
let runId: string | undefined;
export function getRunId(): string | undefined {
if (!resolved) {
const value = process.env["HYPERFRAMES_RUN_ID"]?.trim().slice(0, 128);
runId = value ? value : undefined;
resolved = true;
}
return runId;
}
// ---------------------------------------------------------------------------
// Invocation id — a random uuid minted once per CLI process, present on every
// event that process emits. Unlike run_id (set only when an orchestrator
// exports HYPERFRAMES_RUN_ID), it needs no environment plumbing: it exists so
// the events of ONE invocation can be grouped even when the install identity
// is untrustworthy (identity_persistence != durable, e.g. an ephemeral HOME
// minting a fresh anonymousId per run).
// ---------------------------------------------------------------------------
let invocationId: string | undefined;
export function getInvocationId(): string {
invocationId ??= randomUUID();
return invocationId;
}