Speaker profiles — reference-environment index gate (Stage 8)

Phase 1 keeps longitudinal speaker profiles as portable files under data_dir/speaker_profiles/. A derived file index (or SQLite) may be added only after measuring a documented reference environment.

Reference dataset

  • 500 profiles

  • 5 000 links

  • 200 managed transcripts

Reference environment (record when measuring)

Document in the measurement run notes:

  • Machine class (CPU, RAM)

  • Disk type (SSD / HDD / network)

  • Python version

  • OS

Advisory latency targets (not CI ms gates)

Hot path

Advisory p95

list_profiles

250 ms

50-link appearance resolve

100 ms

Reverse lookup (hashed path)

50 ms

Absolute millisecond thresholds are not mandatory CI acceptance tests.

CI / acceptance (non-flaky)

Algorithmic assertions only:

  • Files scanned ≤ expected upper bound for the fixture

  • Records parsed == N for the fixture

  • Rebuild freshness token is byte-identical across two consecutive rebuilds

  • Reverse lookup examines O(1) hashed path (or O(index entries) if an index is present), not a full link-tree scan when an index exists

Optional nightly/reference-env jobs may track latency regressions without blocking merges.

Phase 1.6 analytics pack (2026-07)

Speakers detail builds AggregationSnapshot then build_profile_analytics_pack as an in-memory pure transform. No disposable analytics disk cache under speaker_profiles/.cache/ in v1.

Correctness does not depend on Streamlit TTL for pack payloads (snapshot rebuilt each Speakers render). CacheInvalidationSignal scopes today are speaker_profiles, speaker_links, transcript_summaries — transcript-library date edits outside profile mutations may not emit a signal; the next Speakers render still rebuilds from disk.

Reference-env measurement of snapshot+pack wall time on a many-link fixture is optional before introducing a versioned disposable analytics cache. Prefer freshness-key misses for correctness if a cache is added later.

When to add an index

Add a disposable file JSON index under speaker_profiles/.cache/ only if reference-env p95 exceeds the advisory targets and algorithmic scan counts show full-tree scans on the hot path. Prefer SQLite only if the file index still fails advisories on the same reference environment.