Buzz Score: Technical Documentation

Buzz Score: Technical Documentation

Status: Draft for tech-lead sign-off Created: 2026-08-18 Related Work: Buzz Score epic brief v1.1 - PRD v2.5 - Formula appendix v0.4.0 - EVO-4333 - EVO-4361 to EVO-4369 - EVO-4125

Combined edition of seven documents. Each appears below as a top-level section; use the document outline to navigate. The same content lives as separate markdown files in the repos, listed at the end.

Contents

Technical Feasibility Read - the artifact the tech-lead approval signs off
Cross-Repo Architecture - data flow, cron timing, null handling, service boundary
Service API and Data Contract - the AC1 contract, and what EVO-4125 reconciles against
Parameter Registry - P1 to P15 with defaults, ranges, and sensitivities, written for product
Validation Harness Runbook - AC7’s tuning procedure
Epic Breakdown - stories, estimates, dependency order, decision gates
Arti Integration - the genesis-train side

Read this first if you have five minutes. Four findings need a product decision, all verified against shipped code rather than inferred:

The brief’s “capping Buzz at 60” is arithmetically incompatible with its own locked 0.30 Intention weight, which caps at 70. A 60 cap requires 0.40.
AC3 asks for a variance penalty and also requires that a jump which holds must score. A variance penalty cannot do both; it scores the held jump at 37 where the brief wants full credit.
taskFollowThrough carries 15% of Action with no ratio definition anywhere, and Task has no completedAt field.
The no-floor Intention recency decay and the deliberately conservative Brand Hub write gate compound on the same slice, which the brief treats as separate risks.

Full detail and recommended resolutions in section 1.

Five diagrams run through this document, each answering a “why is it built this way” question rather than restating the text: signal flow and score composition, nightly cron timing, null handling and renormalization (all section 2), the story dependency graph (section 6), and the two Arti integration seams (section 7). They are drawn in monospace so they render identically here and in the repo.

Buzz Score: Technical Feasibility Read

Status: Draft for tech-lead sign-off Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 (Jacob, 2026-08-11) - PRD v2.5 - Formula appendix v0.4.0 - EVO-4333 (Brand Hub Phase 1) - EVO-4361 to EVO-4369 - EVO-4125 (“Your Buzz” gauge)

Purpose

The epic brief assigns the tech lead a feasibility read before breakdown. This is that read: an acceptance-criterion-by-acceptance-criterion verdict on whether Phase 1 can be built against the data and services that exist today, what is missing, and what must be decided before code.

Verdict: Phase 1 is feasible. Two of the seven acceptance criteria are unblocked and can be built today. Four are feasible with named prerequisites. One (taskFollowThrough, 15% of the Action slice) is blocked on a definition that does not exist in any document, and on an index.

Five items need a product decision. They are collected in Open items and each is raised inline where it bites.

Verdict summary

AC	Area	Verdict	Blocker
AC1	Score service and contract	Feasible	Config must be DB-backed, not a constants file. See AC1.
AC2	Action slice	Partially blocked	`taskFollowThrough` has no ratio definition and no index. Content and release cadence are ready.
AC3	Resonance slice	Feasible today	One formula ambiguity to confirm. Data is ready and deep.
AC4	Intention slice	Feasible on merge	Gated on EVO-4361 to EVO-4364. Coverage calculator must be built.
AC5	Surfacing	Feasible	Contract must be reconciled with EVO-4125 before that gauge hardens.
AC6	Recompute and history	Feasible	New collection plus a scheduler on existing infrastructure.
AC7	Validation harness	Feasible	Depends on the AC1 config decision and on the pure-function core.

AC1: Score service and contract

Feasible. The service, contract, and persistence all follow patterns this repo already runs. One requirement changes the design in a way worth stating up front.

AC7 rules out a constants file

AC1 requires all tunable constants to be read “from a single shared config source rather than being inlined at call sites”. AC7 then requires that Jacob and John tune those constants “without a code change”.

Those two together rule out the obvious home. Domain thresholds in this repo live in ES module constant files next to their service: services/gamification/constants/velocityThresholds.js, levelThreshold.js, percentageThreshold.js. Changing any of those is a code change, a PR, and a deploy. That satisfies AC1 and fails AC7.

P1 to P15 therefore need a DB-backed, versioned config record. The working precedent is models/FeatureFlag.js plus services/featureFlagService.js: a Mongo-backed record, a 60 second in-memory cache, an invalidation hook, and an admin surface. The same shape applies here, with one addition. Because scores are persisted with history (AC6), every snapshot must record the configVersion it was computed under, or a re-tune silently rewrites the meaning of every historical score without leaving a trace.

services/carouselInsightsService.js already establishes this precedent in-repo with its ALGORITHM_VERSION constant. Follow it.

Contract shape

The AC1 contract is three slices, each carrying its own status and sub-signal breakdown, plus the composite. Full specification in buzz-score-contract.md. It follows the standard envelope used everywhere in this service:

res.status(httpStatusCode.OK).json({ status: 'success', statusCode: httpStatusCode.OK, data });

Route mounts on the existing routes/buzz-factory/index.js, which is already behind isLogged and updateLastActive. Controller wraps in catchAsync, errors through AppError and controllers/error/index.js.

Null-renormalization is already house law

AC1’s null rule is not a new commitment. docs/DATA_ACCURACY_MANIFESTO.md already binds this codebase to it, and helpers/growthTrackHelper.js already implements it: calculateGrowthRate returns null when there is no baseline, never 0, and exports MIN_PERCENTAGE_BASELINE = 10 to suppress meaningless percentages off tiny denominators. The score service inherits the convention rather than inventing one.

The one deliberate exception is Intention on an empty Brand Hub, which scores 0. See AC4.

AC2: Action slice

Content and release cadence are ready. Task follow-through is blocked.

The curve is confirmed

AC2 specifies 100 * (1 - e^(-k * ratio)) / (1 - e^(-k)) with k = 4 and ratio = clamp(actual / max, 0, 1), against universal maxes of 7 posts per week and 2 releases per month.

This reproduces both scoring tables in the artist-facing document exactly, including its marginal-value column:

Posts/week	Doc	Formula	Marginal
7	100	100.00	+1.4
6	99	98.56	+2.5
5	96	96.02	+4.5
4	92	91.51	+8.0
3 (sweet spot)	84	83.52	+14.1
2	69	69.38	+25.0
1	44	44.34	+44.3

The same constant reproduces the release table (2 to 100, 1.5 to 96.79, 1 to 88.08, 0.5 to 64.39, 0.33 to 49.57). One formula, one constant, both cadences. No implementation risk here.

Data for content and release cadence is ready

Input	Source	Notes
Posts per week	`ScheduledPost.platformStatus.<platform>.publishedAt`	Instagram and TikTok. Includes `source: 'external'` posts pulled in by the sync crons, so counts are not limited to posts scheduled through Genesis.
Releases per month	`Release.release_date`	Compound index `{user: 1, release_date: -1}` already exists, which is exactly the shape a rolling-window query needs.

Both are already queried by services/gamification/helpers/velocityHelper.js via getPostingCadence(userId, days) and getReleaseCadence(userId, days). Those two fetchers are reusable with one change: both swallow errors into return 0, which under AC1 would report an API failure as an artist who did nothing. They need null-returning variants.

`taskFollowThrough` is blocked on two things

AC2 locks Action = 0.55 * content + 0.30 * release + 0.15 * taskFollowThrough. Unlike the two cadences, taskFollowThrough is given no max and no curve, so there is no actual / max ratio to feed into anything.

Missing definition. Candidate readings, all plausible, all scoring differently: tasks completed over tasks due in the window; tasks completed over tasks created; completed-on-time over due. Nothing in the brief selects one. This must come from the appendix or from product.

Missing data shape. models/Task.js has completed, status, and statusHistory: [{ status, changedAt }], but no completedAt field. Completion time has to be recovered by scanning statusHistory for the entry where status === 'COMPLETED'. The alternative ledger, models/ActivityLog.js, has two problems: it carries no index on {userId, activityDate}, so a nightly per-user scan table-scans a growing collection, and its unique constraint on (userId, activityId, activityType) makes it a first-occurrence log rather than an event stream.

The swing is material, so this is not a rounding concern. At the coaching sweet spot of 3 posts per week and 1 release per month:

`taskFollowThrough`	Action score
1.0	87.4
0.5	79.9
0.0	72.4

Fifteen points of the Action slice, which is 35% of the composite, rests on a signal with no definition. Either define it and add the index, or drop the sub-signal to weight 0 for Phase 1 and renormalize content and release, which the AC1 machinery already supports at no extra cost.

The prohibition is already load-bearing

AC2 forbids reading User.levelInfo.currentLevelProgress, the velocity or 7-day effort score, and questionnaire buzz points.

This matters more than it reads, because services/gamification/helpers/velocityHelper.js already computes a 0-100 composite from posting and release cadence, and someone will find it and reuse it. It is precisely what AC2 prohibits:

velocityHelper today	AC2 requires
Linear `(actual / target) * 100`	Concave curve, `k = 4`
Capped at 150%	Capped at 100, overshoot recorded as `overTargetRatio`
Per-level targets multiplied by `aggressionMultipliers` (LOW 0.75 / MEDIUM 1.0 / HIGH 1.25)	Universal maxes, per-artist targets dead as a scoring input
Weights `loginFrequency`	Engagement and progress signals excluded by design
`catch` returns `{ score: 0 }`	Missing data is `null`, never `0`

Its data fetchers are reusable. Its scoring is the thing being replaced. The distinction should be explicit in the story description or it will be lost at implementation time.

AC3: Resonance slice

Feasible today, and the data is deeper than the brief assumes. One formula ambiguity to confirm.

The time series is ready

models/MetricPoint.js is the unified metrics store: one document per (user, platform, metric, day), with meta.openId scoping so a disconnect-and-reconnect of a different account does not splice two audiences into one series.

About 165,000 documents, with points back to 2021-05-11
Daily granularity. The metrics crons run every 6 hours but normalizeDate floors to UTC midnight and the upsert is delete-then-insert on (user, platform, metric, date), so sub-daily runs converge on one row per day rather than creating four
Indexes {meta.user, meta.platform, meta.metric, date} and {meta.user, meta.platform, date: -1}
Read layer already exists: repositories/socialMetricsRepository.js (getTimeSeries with period resolution, gap filling, and a compare: true mode that already computes the prior equal-length window and its growth rate) over services/metrics/metricsService.js

One operational note carried in the model file itself: the granularity: 'days' timeseries option is not valid in MongoDB, so createCollection fell back to an ordinary collection. This costs columnar compression and nothing else. Query semantics are normal and updates are allowed.

Consequence worth stating plainly: the 4-week rolling window is computable today, and so is historical replay. AC7’s validation harness can be run over real artists across years of real history before any of this ships. That is unusual and it should be used.

Available metrics per platform

Platform	Metrics in `MetricPoint`
Instagram	`Total Followers`, `Content interactions`, `Likes`, `Comments`, `Saves`, `Shares`, `Replies`, `Accounts reached`, `Engagement Rate`
TikTok	`Total Followers`, `Content Interactions`, `Likes`, `Comments`, `Shares`, `Views`, `Engagement Rate`, plus `:AllTime` cumulative variants
Spotify	`Followers`, `Listeners`, `Popularity`, `Followers: Listeners Ratio`

The brief’s stated priority order, saves and shares and comments ranking above raw follows, is therefore satisfiable at the account level today.

Popularity is stored with real history, backfilled per day from Songstats historic-stats in helpers/spotify/songstatsArtistMetricsHelper.js.

One constraint to respect: saveMetrics drops any non-canonical metric title. A new metric name must be added to constants/metrics.js or it silently fails to persist.

Three gaps

Gap	Detail	Consequence for Phase 1
Per-track streams	`Track.sp_streams` is a current-value snapshot. The model comment says so outright. Songstats historical track stats are fetched on demand in `helpers/spotify/trackHistoricalMetricsHelper.js` and never persisted.	“Streams” in v1 means account-level Spotify `Listeners`. Per-track stream growth is not available.
Per-post metrics	`models/PostMetricPoint.js` shipped 2026-08-17, one day before this read. Prior per-post history is unrecoverable: `ScheduledPost.platformStatus.<p>.metrics` was destructively `$set` on every cron run.	Do not design any Phase 1 sub-signal on per-post history. It will have weeks of data by the time Phase 1 lands, not years.
YouTube	No OAuth, no client, no metrics anywhere. The only traces are a URL string on `InspirationArtist.socials.youtube` and an unused enum value in `Campaign.platforms`.	Permanent `null` and renormalized, per AC3’s disconnected-platform rule. Not a Phase 1 item.

The one formula ambiguity

AC3 defines Resonance as growthScore * consistency * baseScale, with consistency “penalizing variance in weekly rates”. It then requires, two bullets later, that “a one-week spike that decays back to baseline within the window does not raise Resonance, only a shift that holds does”.

A variance penalty cannot satisfy the second clause. A spike that crashes and a jump that holds have the same shape in the rate series: one very large week followed by small ones. Both get the same large coefficient of variation, so both get penalized identically, even though the brief wants one scored near zero and the other scored fully.

Simulated over 4-week follower series, comparing a CV penalty against a retention factor (end / window peak):

Scenario	CV penalty	Retention factor	AC3 requires
Steady +3% per week	100	100	full credit
Steady +2% per week	67	67	partial credit
Spike then decay to baseline	16	4	must not raise
Jump that holds	37	100	must score
Flat	0	0	near zero
Shrinking	0	0	floors at 0

A retention factor satisfies both clauses, and it satisfies the artist-facing framing directly: “a spike that falls back is not a pop, a jump that holds is”.

Appendix v0.4.0 may already resolve this. It is flagged here because it is the single formula item where a reasonable implementation of the stated wording produces behaviour that inverts the score’s headline promise, and because it will not surface in testing unless someone writes the jump-that-holds fixture specifically.

Coverage threshold

AC3’s 60% non-null-day threshold is directly countable against MetricPoint day rows for the window. No new instrumentation needed.

AC4: Intention slice

Feasible once EVO-4361 to EVO-4364 merge. The coverage calculator has to be built.

What exists

Collection	Role for Buzz
`BrandHubDocument`	Current state, one row per `(user, docSlug)`. Carries `version`, `lastUpdatedBy` (`seed` / `user` / `system` / `arti`), `seededAt`, `triggeringAction`, and document-level `createdAt` / `updatedAt`. `content` is `Schema.Types.Mixed`.
`BrandHubWriteLog`	Append-only and immutable, with `before` / `after` per write and a `section` field holding the dotted path(s) touched. Indexed `{user, docSlug, createdAt}`. This is the version history; the document itself keeps none.
`BrandHubProposal`	`proposed` to `approved` / `rejected`, with `fingerprint` dedup.

Canonical field shapes for all six docs are in services/brand-hub/emptyDocs.js. That file is the facet checklist. It is a convention rather than schema enforcement, since content is Mixed, so the coverage scorer must own a canonical facet-path map and read defensively.

What must be built

There is no completeness or percent-filled notion anywhere in the codebase. The nearest thing is getBrandMemoryForUser returning isSeeded: docs.length === 6, which is a boolean and is true for a completely empty seed. The genesis-train side has a per-field _nonempty(value) predicate in app/services/brand_hub/prompt_renderer.py, which is the right emptiness test, but it is Python-side and produces no number.

The seed-entry trap

services/brand-hub/seedFromBuzz.js writes three taste-timeline entries and exactly one decision-log entry for every artist who completes the Buzz questionnaire, plus the backfill in EVO-4364 does the same retroactively for the existing cohort.

A naive “does this append-only doc have entries” facet therefore passes automatically for the entire backfilled alpha cohort on day one, measuring nothing. The brief flags this in appendix section 2.3. Confirming the exclusion mechanism is on the open items list. lastUpdatedBy: 'seed', seededAt, and each entry’s own source field all make seeded material identifiable, so this is straightforward once the rule is stated.

Recency is available at document level

AC4’s recency multiplier needs days since the last write to any brand doc. Two sources agree:

BrandHubDocument.updatedAt, since applyBrandHubPatch is the single write choke point and bumps it on every write
BrandHubWriteLog.createdAt, which the same function writes on every patch

Document level is sufficient for AC4 as written. Section-level attribution is available from the write log, with three caveats worth knowing before anyone depends on it: it only goes back to 2026-08-12 when the model shipped, a multi-path set stores all paths joined into one string and needs splitting, and write-log inserts are best-effort with failures logged and swallowed, so absence of a row is not proof of absence of a write.

The decay and the write gate compound

AC4’s multiplier is 1 for d <= 90 and exp(-(d - 90) / 90) beyond, with no floor:

Days since last brand write	Multiplier	Intention 80 becomes	Composite cost at w=0.30
90 or fewer	1.000	80.0	0.0
120	0.717	57.3	6.8
180	0.368	29.4	15.2
270	0.135	10.8	20.8
365	0.047	3.8	22.9

Separately, the brief accepts a precision-first Brand Hub write gate (EVO-4368) as a monitored risk, on the correct reasoning that Arti writes with no user in the loop.

These two decisions interact, and the brief treats them in separate sections. AC4 says any write resets the clock, including Arti’s automatic ones. So how fast an artist’s Intention decays is governed by how often a gate that was deliberately tuned to be stingy chooses to fire. A conservative gate does not merely under-write coverage, which the brief anticipates; it also leaves the recency clock running, and the two markdowns compound on the same slice.

The brief’s chosen leading indicator, writes per artist per week off BrandHubWriteLog, is the right instrument. The recommendation here is only that its alert threshold be derived from the table above (what write frequency keeps a typical artist inside d <= 90) rather than picked freehand.

The 60 versus 70 contradiction

The brief locks slice weights at 0.30 Intention / 0.35 Action / 0.35 Resonance, and states in the same table that an empty Brand Hub “scores 0, capping Buzz at 60”.

Those cannot both be true. With Intention at 0 and no renormalization, the ceiling is (0.35 + 0.35) * 100 = 70. A cap of exactly 60 requires an Intention weight of 0.40.

That number is not arbitrary. The artist-facing buzz-score-explained.md states four constraints: “roughly a third each”, “the two you control adding up to more than half”, “your score can’t pass 60”, and “slice weights (55/45 today)”. Exactly one weight triple satisfies all four simultaneously: 0.40 / 0.33 / 0.27, where 33:27 is precisely 55:45 of the non-Intention remainder. Its own worked example reproduces too: Intention 75, Action 95, Resonance 0 gives 61.4, matching “lands around a 61”, and the same artist at Resonance 48 gives 74.3, matching “somewhere around 74 in three weeks”.

So the two documents encode different weight generations, and the artist-facing “can’t pass 60” line is stale against the locked weights. This is a copy decision as much as a scoring one, since the 60 figure has already been written into artist-facing framing. Raised as open item 1.

AC5: Surfacing

Feasible. The pre-activation state (Intention and Action live and moving, Resonance dormant, composite grayed) is a contract concern rather than a data one, and is specified in buzz-score-contract.md.

Coordination flag, wider than the brief states

The brief flags artistevolve-fe/components/common/components/BuzzfactoryInfo.tsx for hardcoding buzz_score: 0 in its analytics payload. There are two such sites, not one, and both also hardcode the level:

File	Lines	Hardcoded
`components/common/components/BuzzfactoryInfo.tsx`	30, 38	`buzz_score: 0`, `user_level: 1`
`app/(dashboard)/dashboard/page.tsx`	821	`buzz_score: 0`, `user_level: 1`

There is also a complete PostHog surface already built and waiting for real values: lib/analytics/trackers/gamification-tracker.ts defines buzz_score_updated carrying old_buzz_score and new_buzz_score, and buzz_score_milestone.

That existing event maps directly onto AC6’s requirement that sub-signal movement be detectable by downstream consumers. It is a lever rather than debt, and it should be wired in the same story that lands the recompute job rather than discovered later.

AC6: Recompute cadence and history

Feasible on existing infrastructure.

History needs a new BuzzScoreSnapshot collection, one document per user per day, storing the composite, all three slices with status, every sub-signal with value-or-null and reason, overTargetRatio, coverage flags, and configVersion. Design in buzz-score-architecture.md.
Cadence needs a BuzzScoreScheduler extends BaseCronService, registered in services/cron/index.js. The base class already provides overlap protection, timeouts, a per-job child logger, and a cross-instance run lock via models/CronJobRunClaim.js with a two-minute lease. Nothing new is required.
Timing must fall after the metrics crons settle. The last one is instagram-engagement-notify at 20 22 * * *, so roughly 23:00 UTC.

One precedent to avoid rather than follow: getBuzzFactoryOverviewV2Service promotes users, appends level history, and fires notifications and emails from inside a GET. The Buzz Score read path must be a pure read against the latest snapshot, or the score will move as a side effect of someone opening a page.

AC7: Validation harness

Feasible, and unusually well supported by the data.

The harness needs three things. Two follow from decisions above and one is free:

Config injectable at call time, not imported at module scope. This is the real reason the scoring core must be pure functions of (signals, config). It is not a style preference.
DB-backed parameters so a tuning pass is a data change (AC1 plus AC7, discussed above).
Historical replay, which is free: MetricPoint holds daily history back to 2021, so the formula can be scored over the alpha cohort across real history before any of this ships.

The distribution check matters as much as any individual score. The band table claims 75-89 is “the top of the realistic scale” and the target state. Running the locked formula with WORKING constants over the real cohort will show whether that band is populated or empty, which is the single most useful output of the tuning pass and the cheapest to produce.

Procedure in buzz-score-validation-harness.md.

Open items

Five decisions. None blocks starting Phase 1; each blocks a specific story.

#	Item	Owner	Blocks
1	60 versus 70 cap. Re-weight Intention to 0.40, or correct the artist-facing copy and UI to 70.	Jacob, John	AC4 story, and any UI copy referencing the cap
2	AC3 consistency mechanism. Confirm whether appendix v0.4.0 resolves the spike-versus-hold tension, and with what term.	Jacob, John	AC3 story
3	`taskFollowThrough` ratio definition. No max, no denominator, no curve is specified anywhere. Alternative: weight it 0 for Phase 1.	Jacob, John	AC2 story
4	P15. Does Intention count proposed-but-unapproved Brand Hub material, or only what reached the document? Both collections are queryable, so this is purely a scoring decision.	Jacob, John	AC4 story
5	Seed-entry exclusion. Confirm the facet map excludes `seedFromBuzz`’s three `taste-timeline` and one `decision-log` entries, via `lastUpdatedBy: 'seed'` or `seededAt`.	Jacob, John	AC4 story

Dependencies

Dependency	Status	Gates
EVO-4361 (six docs as structured records)	In PR	AC4
EVO-4362 (read API, version metadata, write log)	In PR	AC4
EVO-4363 (deterministic seeding)	In PR	AC4 coverage floor
EVO-4364 (backfill for existing users)	In PR	Must run before the score is surfaced, or the alpha cohort launches at Intention near 0
Appendix v0.4.0	Exists, not reviewed here	Open items 2 and 3
EVO-4125 (“Your Buzz” gauge)	In PR	Contract reconciliation, AC5

Instagram, TikTok, and Songstats ingestion are all live and need no changes.

Buzz Score: Cross-Repo Architecture

Status: Design, pending tech-lead sign-off Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 - PRD v2.5 - Formula appendix v0.4.0 - EVO-4333 - EVO-4361 to EVO-4369 - EVO-4125

Purpose

How the Buzz Score is computed, stored, served, and explained across genesis-web and genesis-train. Feasibility and data availability are covered separately in buzz-score-feasibility.md; the wire format is in buzz-score-contract.md.

Service boundary

genesis-web computes. genesis-train explains.

text

  SOURCE DATA (genesis-web owns)         SCORING CORE (pure)            OUTPUT
  ------------------------------         -------------------           --------

  BrandHubDocument --+
  BrandHubWriteLog --+--> coverage --+
                          recency ---+--> INTENTION --+  w 0.30
                                                      |
  ScheduledPost --------> content ---+                |
  Release --------------> release ---+--> ACTION -----+--> COMPOSITE --> BuzzScoreSnapshot
  Task -----------------> follow --=-+     w 0.35     |      0-100        one per day
                                                      |                        |
  MetricPoint ----------> weekly ----+                |                        |
   daily, back to 2021    series     +--> RESONANCE --+  w 0.35                |
                                                                               |
                              ^                  ^                             +--> GET /buzz-score --> artistevolve-fe
                              |                  |                             |
                       BuzzScoreConfig    every leaf is                        +--> moduleContext ----> genesis-train (Arti)
                       P1-P15, versioned  {value | null, reason}

Read left to right: five collections feed six collectors, the collectors feed three slices, the slices compose into one number, and that number is persisted once per day and served two ways. Two things are deliberately drawn as inputs to the core rather than as part of it. BuzzScoreConfig is injected, which is what makes AC7 tuning possible. And every leaf carries a value or a null with a reason, which is what makes the renormalization in the failure-mode table work.

The split is not arbitrary. Deterministic math belongs next to the data that feeds it, where it can be unit tested, replayed, and audited. Narrative belongs next to the LLM. It also mirrors how the source documents are already split: an appendix that specifies math and an “explained” document that specifies language.

Why genesis-train does not compute the score

genesis-train has direct Mongo access, but only for its own concerns: LangGraph checkpoints, memory extraction, credits, and Idea Center boards. Every piece of product data it uses (tasks, projects, questionnaires, badges, profile, brand hub) arrives over HTTP from genesis-web via app/utils/api_client.py. There is no model for badges, levels, or metrics anywhere in that repo.

Computing the score there would mean either replicating the entire signal layer or shipping four weeks of per-artist time series over HTTP on every request. Neither is worth doing for arithmetic that has no LLM in it.

The scoring core is pure functions

Every scoring function takes (signals, config) and returns a plain object. No database access, no clock reads, no imports of module-scope constants.

services/buzz-score/
  core/
    cadenceCurve.js      score(actual, max, k) -> 0..100, plus overTargetRatio
    actionSlice.js       content + release + taskFollowThrough -> slice
    resonanceSlice.js    growth * consistency * baseScale per sub-signal -> slice
    intentionSlice.js    coverage * recencyMultiplier -> slice
    compose.js           renormalization over available components -> composite
  signals/               the impure half: one collector per input
  buzzScoreService.js    orchestration
  config/                DB-backed config accessor with cache

This shape is load-bearing, not stylistic. Three separate acceptance criteria require it:

AC1 wants a single config source, so config must be injected rather than imported.
AC7 wants Jacob and John tuning constants without a code change, which means the same function must be callable with overridden parameters.
AC7’s harness replays the formula over historical data, which means the core cannot read “now” or query the database itself.

A core that imports its constants from services/gamification/constants/ cannot do any of the three.

Configuration

Why not a constants file

Domain thresholds in this repo live in ES module constant files next to their service: services/gamification/constants/velocityThresholds.js, levelThreshold.js, percentageThreshold.js. That satisfies AC1 and fails AC7, because changing one is a PR and a deploy.

P1 to P15 need a DB-backed, versioned record. The working precedent in this repo is models/FeatureFlag.js plus services/featureFlagService.js: Mongo-backed, a short in-memory cache with an invalidation hook, and an admin surface for edits.

`BuzzScoreConfig`

One active record, plus history. Fields:

Field	Purpose
`version`	Monotonic integer. Stamped onto every snapshot computed under it.
`isActive`	Exactly one active record at a time.
`params`	The P1 to P15 values. Shape documented in `buzz-score-parameters.md`.
`note`, `changedBy`, `createdAt`	Audit trail for a tuning pass.

Accessor caches for 60 seconds and exposes an invalidation hook, matching featureFlagService.invalidateFlagCache().

Every snapshot stores the configVersion it was computed under. Without it, a tuning pass silently rewrites the meaning of every historical score, and the trajectory that the notifications work depends on becomes a comparison between two different formulas. services/carouselInsightsService.js already establishes this precedent in-repo with ALGORITHM_VERSION.

Signal collectors

One collector per input. Each returns a value or null with a machine-readable reason. None of them return 0 for missing data.

Slice	Signal	Source	Notes
Action	posts per week	`ScheduledPost.platformStatus.<p>.publishedAt`	Rolling 28 days. Includes `source: 'external'`. Reuse `getPostingCadence` from `services/gamification/helpers/velocityHelper.js`, but through a null-returning wrapper.
Action	releases per month	`Release.release_date`	Rolling 90 days. Index `{user: 1, release_date: -1}` already exists. Same wrapper note for `getReleaseCadence`.
Action	task follow-through	`Task.statusHistory[].changedAt`	Blocked on a definition. See feasibility open item 3.
Resonance	per-metric weekly series	`models/MetricPoint.js` via `repositories/socialMetricsRepository.js`	Daily points, `openId` scoped, back to 2021-05-11.
Intention	coverage	`BrandHubDocument.content` against `services/brand-hub/emptyDocs.js`	Facet map owned by the coverage scorer, since `content` is `Mixed`.
Intention	recency	`BrandHubDocument.updatedAt`	Document level is sufficient for AC4 as written.

The two reuse traps

velocityHelper scoring must not be reused. It already computes a 0-100 composite from posting and release cadence, and it is exactly what AC2 prohibits: linear actual / target, capped at 150%, per-level targets multiplied by aggressionMultipliers, weighted with login frequency, and returning { score: 0 } from its catch. Its two fetchers are fine. Its scoring is the thing being replaced.

calculateGrowthRate should be reused. helpers/growthTrackHelper.js already implements the null-versus-zero convention correctly: null when there is no baseline, 0 only when the value genuinely did not change, and an opt-in MIN_PERCENTAGE_BASELINE = 10 floor for count metrics so a follower going from 1 to 3 does not read as +200% growth. Resonance wants that floor on follower counts and must not apply it to rate metrics such as Engagement Rate.

`BuzzScoreSnapshot`

One document per user per day. This is what makes AC6’s history requirement real and what the notification work reads.

{
  date,                       // UTC midnight, matching the MetricPoint convention
  meta: { user },
  composite: { value, band, status },
  slices: {
    intention: { value, status, weight, subSignals: { coverage, recency } },
    action:    { value, status, weight, subSignals: { content, release, taskFollowThrough } },
    resonance: { value, status, weight, subSignals: { /* per metric */ } }
  },
  overTargetRatio: { content, release },   // recorded, never scored
  coverage: { /* per sub-signal: observed days, required days, passed */ },
  configVersion,
  computedAt
}

Every sub-signal is { value: number|null, reason: string|null, weight: number }. The reason vocabulary is enumerated in buzz-score-contract.md because the frontend renders against it.

Index { 'meta.user': 1, date: -1 }. Follow the MetricPoint meta convention rather than inventing a new one, and note the lesson recorded in that model: do not pass timeseries: { granularity: 'days' }, because it is not a valid MongoDB value and silently falls back to an ordinary collection. Declare an ordinary collection deliberately.

No TTL. The same reasoning that kept a TTL off PostMetricPoint applies here: a timeseries TTL expires against the time field, so history would vanish without a log line, and the volume does not justify it.

Compute path

BuzzScoreScheduler extends BaseCronService, registered in services/cron/index.js.

super(
  'buzz-score-daily',
  '0 23 * * *',
  'UTC',
  90,
  'Compute and persist daily Buzz Score snapshots'
);

The base class already provides overlap protection, a timeout, a per-job child logger, and a cross-instance run lock through models/CronJobRunClaim.js with a two-minute lease and a heartbeat. Nothing new is needed.

Timing matters. The score must run after the metrics crons settle, or it scores yesterday’s data and reports it as today’s. Current tail of the daily sequence:

Job	Schedule (UTC)
`instagram-posts-reconcile`	`35 21 * * *`
`tiktok-engagement-notify`	`0 22 * * *`
Songstats daily (prod)	`0 22 * * *`
`instagram-engagement-notify`	`20 22 * * *`
`buzz-score-daily`	*`0 23 * `*

Recompute is idempotent. Re-running for the same day overwrites that day’s snapshot, matching how bulkUpsertPoints treats metricpoints.

Why 23:00 and not earlier

text

   UTC     21:00      21:30      22:00      22:30      23:00
            |          |          |          |          |
  IG        +--21:15---+--------- +--22:20 --+          |     * writes MetricPoint
            *  reconcile          *  notify             |
  TikTok       +--21:35--+--22:00-+                     |
               *         *                              |
  Spotify              +--22:00--+                      |
                       *                                |
                                                        |
  BUZZ  --------------------------------------------->  *  buzz-score-daily
                                                        |
                            <-- 40 min margin -->

The score reads MetricPoint, ScheduledPost, and Release. Every one of those has a writer earlier the same evening, and the last is instagram-engagement-notify at 20 22 * * *. Running before that margin means scoring a partially written day and reporting it as final, which the snapshot then freezes into history. The 40 minutes is slack for a slow run, not precision.

Change detection

AC6 requires that a sub-signal moving materially while the composite does not must be detectable downstream. The scheduler compares each sub-signal against the previous snapshot and emits through eventsHub/eventEmitter.js when a configured delta is crossed.

The frontend already has the receiving end built: artistevolve-fe/lib/analytics/trackers/gamification-tracker.ts defines buzz_score_updated carrying old_buzz_score and new_buzz_score, plus buzz_score_milestone. Wire these in the same story that lands the scheduler rather than leaving them to be rediscovered.

Read path

GET /api/v1/buzz-factory/v2/buzz-score reads the latest snapshot and returns it. It computes nothing.

The precedent to avoid is in this same subsystem: getBuzzFactoryOverviewV2Service persists progress, promotes users a level, appends level history, and fires notifications and emails, all from inside a GET. Applying that pattern here would make an artist’s score move because somebody opened a page, and would make the validation harness unreproducible.

Route mounts on the existing routes/buzz-factory/index.js, which is already behind isLogged and updateLastActive. Gated by requireFlag, which needs a key added to enums/flagKey.js and a seed row in seeds/featureFlags.js. Seeds sync key, name, description, and scope only, never enabled or targeting, so rollout stays a DB decision.

Failure modes

text

                        for each sub-signal
                                |
                    +-----------+-----------+
                    |  collector ran clean? |
                    +-----------+-----------+
                    no |                    | yes
                       v                    v
              value = null        +---------+----------+
              reason =            |  coverage >= P9 ?  |
              collection_failed   +---------+----------+
                       |            no |         | yes
                       |               v         v
                       |        value = null   value = 0-100
                       |        reason =       reason = null
                       |        insufficient_
                       |        coverage
                       +---------------+---------+
                                       v
                       +-------------------------------+
                       | drop the nulls, renormalize   |
                       | weights across what remains   |
                       +---------------+---------------+
                                       v
                              slice value, 0-100

  THE ONE EXCEPTION
  Brand Hub with zero documents  ->  Intention = 0, status = empty
  Included at zero, never renormalized away, because a dash here would
  make skipping brand definition score better than completing it.

Failure	Behaviour
Platform disconnected	Sub-signal `null`, reason `platform_disconnected`, weights renormalize.
Metric series below the coverage threshold	Sub-signal `null`, reason `insufficient_coverage`.
Artist below the activation level	Resonance slice `dormant`, composite renormalizes over Intention and Action.
No Brand Hub documents	Intention `0`, status `empty`. The single deliberate exception to the null rule, because renormalizing over a dash would make skipping brand definition score better than completing it.
Signal collector throws	Sub-signal `null`, reason `collection_failed`, logged with the job’s child logger. Never `0`.
Every slice unavailable	Composite `null`. There is no floor value to fall back to.

This is not a new posture. docs/DATA_ACCURACY_MANIFESTO.md already binds this codebase to it, and the social cron split (docs/SOCIAL_CRON_SPLIT_PLAN.md) exists precisely because code that could not tell “the API failed” from “the value is zero” wrote failures into the database as fact and destroyed hundreds of posts.

genesis-train integration

Two seams, both following existing patterns in that repo. Detail in genesis-train docs/BUZZ_SCORE_INTEGRATION.md.

Page-open rollup. Extend services/agent/smartRollupBuzzFactoryService.js to carry the score block in its ModuleContext. On the Python side, add the branch in generate_initial_rollup_stream() (app/api/routers/chat_api.py, the buzz_factory branch) and a typed formatter in app/services/user_data_insights/data_formatter_service.py so follow-up turns stop falling through to the generic formatter.

On-demand. A BUZZ_TOOLS module on the app/agents/questionnaire/tools.py template, registered in CHAT_TOOLS (app/agents/chat/tools.py) and announced in both catalogues in app/services/ai/prompt_service.py. It calls this service through APIClient._make_request with the user’s JWT from state["token"].

Voice conflict

The existing buzz_factory rollup prompt is celebratory and gamified: its response structure opens with “Celebration”, asks for “genuine enthusiasm”, and instructs the model to “make them feel proud”. The Buzz Score register is the opposite by design. The PRD commits to a falling score reading as a diagnosis rather than a scolding, to not handing out participation points, and to being able to tell an artist to do less of something.

These cannot share a prompt. The Buzz Score branch needs its own.

Testing

Layer	Approach	Template
Scoring core	Plain unit tests, no mocks needed, since the functions are pure	any pure helper test
Signal collectors	`jest.unstable_mockModule` on each model, then dynamic `await import()`	`__tests__/smartRollupBuzzFactoryService.test.js`
Snapshot and scheduler	`mongodb-memory-server` with real models, mocking only side-effecting collaborators	`__tests__/buzzFactoryOverviewV2.test.js`
Config service	Mock-only, covering cache expiry and version stamping	`__tests__/featureFlagService.test.js`
API contract	Contract test	`docs/UI_CONTRACT_TESTING.md`, `__tests__/contracts/instagramOverview.contract.test.js`
genesis-train	`AsyncMock` on `APIClient._make_request`	`app/tests/unit/test_buzz_factory_rollup.py`

Jest here runs ESM through NODE_OPTIONS=--experimental-vm-modules with jest.config.cjs, and utils/logger.js is mocked in every unit test.

The fixtures that must exist regardless of tuning are listed in buzz-score-validation-harness.md. The jump-that-holds case in particular will not surface on its own.

Buzz Score: Service API and Data Contract

Status: Draft, needs reconciliation with EVO-4125 before that gauge hardens Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 AC1 and AC5 - EVO-4125 (“Your Buzz” gauge) - Data Accuracy Manifesto

Purpose

AC1 requires that the score service return “all three slices plus the composite in a single documented contract, each slice carrying its own status and its sub-signal breakdown”. This is that contract.

It is also the artifact EVO-4125 needs to be reconciled against. That gauge is in PR and currently renders level progress as a placeholder, which is a sensible interim, but the shape below is three slices with per-slice status and an inspectable breakdown rather than a single number. Settling this before the gauge hardens avoids rework.

Endpoint

GET /api/v1/buzz-factory/v2/buzz-score

Mounts on routes/buzz-factory/index.js, which already applies isLogged and updateLastActive to the whole router. Gated by requireFlag, which needs a key in enums/flagKey.js and a seed row in seeds/featureFlags.js.

No query parameters in Phase 1. Score projection and historical ranges are explicitly out of scope per the brief, so no from or to.

This is a pure read. It returns the latest BuzzScoreSnapshot and computes nothing. See the architecture doc for why that constraint exists.

Response

Standard service envelope, as used throughout this codebase:

res.status(httpStatusCode.OK).json({ status: 'success', statusCode: httpStatusCode.OK, data });

Worked example

An artist at Level 5 with Instagram and TikTok connected, Spotify not connected, a Brand Hub that is about three quarters filled and was touched last month, posting at the sweet spot, and growing slowly.

json

{
  "status": "success",
  "statusCode": 200,
  "data": {
    "composite": {
      "value": 65.8,
      "band": "building",
      "status": "live"
    },
    "slices": {
      "intention": {
        "value": 72.0,
        "status": "live",
        "weight": 0.30,
        "effectiveWeight": 0.30,
        "subSignals": {
          "coverage":  { "value": 72.0, "reason": null, "weight": 1.0 },
          "recency":   { "value": 100.0, "reason": null, "weight": null,
                         "daysSinceLastWrite": 30, "multiplier": 1.0 }
        }
      },
      "action": {
        "value": 85.1,
        "status": "live",
        "weight": 0.35,
        "effectiveWeight": 0.35,
        "subSignals": {
          "content":           { "value": 83.5, "reason": null, "weight": 0.55,
                                 "actual": 3, "max": 7, "unit": "posts/week" },
          "release":           { "value": 88.1, "reason": null, "weight": 0.30,
                                 "actual": 1, "max": 2, "unit": "releases/month" },
          "taskFollowThrough": { "value": null, "reason": "not_configured", "weight": 0.15 }
        }
      },
      "resonance": {
        "value": 41.2,
        "status": "live",
        "weight": 0.35,
        "effectiveWeight": 0.35,
        "subSignals": {
          "instagramFollowers": { "value": 44.0, "reason": null, "weight": 0.30 },
          "instagramSaves":     { "value": 51.5, "reason": null, "weight": 0.20 },
          "tiktokFollowers":    { "value": 28.7, "reason": null, "weight": 0.30 },
          "spotifyListeners":   { "value": null, "reason": "platform_disconnected",
                                  "weight": 0.20 }
        }
      }
    },
    "overTargetRatio": { "content": 0, "release": 0 },
    "coverage": {
      "instagramFollowers": { "observedDays": 28, "requiredDays": 17, "passed": true },
      "tiktokFollowers":    { "observedDays": 22, "requiredDays": 17, "passed": true }
    },
    "window": { "weeks": 4, "start": "2026-07-21", "end": "2026-08-17" },
    "configVersion": 3,
    "computedAt": "2026-08-18T23:04:11.204Z"
  }
}

Reading the example: taskFollowThrough is a dash rather than a zero, so Action renormalizes over content and release alone, (0.55 * 83.5 + 0.30 * 88.1) / 0.85 = 85.1. Spotify is a dash, so Resonance renormalizes over the three available metrics. The composite is 0.30 * 72.0 + 0.35 * 85.1 + 0.35 * 41.2 = 65.8.

Field reference

`composite`

Field	Type	Notes
`value`	`number \| null`	0 to 100, one decimal. `null` when no slice is available.
`band`	`string \| null`	See bands.
`status`	enum	`live`, `dormant`, or `empty`.

Slice

Field	Type	Notes
`value`	`number \| null`	0 to 100 for the slice on its own.
`status`	enum	See status.
`weight`	`number`	The configured weight from `BuzzScoreConfig`.
`effectiveWeight`	`number`	The weight after renormalization. Differs from `weight` whenever another slice is unavailable. Clients displaying “what is holding my score down” should use this one.
`subSignals`	object	One entry per sub-signal, always present even when `null`.

Sub-signal

Field	Type	Notes
`value`	`number \| null`	`null` means unmeasurable, never “measured as zero”.
`reason`	`string \| null`	Non-null exactly when `value` is `null`. See reasons.
`weight`	`number`	Configured weight within its slice.

Cadence sub-signals additionally carry actual, max, and unit so the frontend and Arti can say “3 of a possible 7 posts a week” without re-deriving it.

Slice status

Status	Meaning	Renormalization
`live`	Measured and contributing.	Included.
`dormant`	Deliberately switched off for this artist, not missing. Resonance before the activation level is the only Phase 1 case.	Excluded, remaining slices renormalize.
`empty`	Measurable but genuinely empty, and that emptiness is meaningful. Intention with no Brand Hub documents is the only Phase 1 case.	Included at value `0`.

The empty status exists to carry the one sanctioned carve-out from the Data Accuracy Manifesto. An artist who has written nothing about their brand scores 0 on Intention rather than a dash, because renormalizing over a dash would make skipping brand definition score better than completing it. Every other absence is a dash.

The frontend must render dormant and empty differently. They look similar (neither is a normal score) and they mean opposite things.

Reason vocabulary

Machine-readable and stable. The frontend maps these to copy; Arti maps them to explanation.

Reason	Meaning
`platform_disconnected`	The artist has not connected this platform, or has disconnected it.
`insufficient_coverage`	Fewer non-null days in the window than the coverage threshold requires.
`no_baseline`	A growth calculation had no prior value to compare against. Mirrors `calculateGrowthRate` returning `null`.
`below_minimum_base`	Base too small for a percentage to mean anything. Mirrors `MIN_PERCENTAGE_BASELINE` in `helpers/growthTrackHelper.js`.
`slice_dormant`	The parent slice is not active for this artist yet.
`not_configured`	The sub-signal is weighted but has no definition or is switched off in config.
`collection_failed`	The collector errored. Distinct from all of the above, and it should be rare enough to alert on.

collection_failed earns its own value deliberately. Folding an API failure into insufficient_coverage would recreate the exact ambiguity that SOCIAL_CRON_SPLIT_PLAN.md exists to remove.

Bands

Band	Range	Framing
`exceptional`	90 and above	Sustained maximum output and strong market response. Rare by design.
`green`	75 to 89	The target state. Should read as very good, not as missing 20 points.
`building`	60 to 74	The work is happening, the market has not fully answered.
`early`	45 to 59	Early or drifting. A strategy conversation, not a guilt trip.
`low`	Below 45	Either genuinely stalled or not enough visibility. Check `coverage` before saying anything.

Band thresholds are config, not literals. They are P-parameters like everything else.

Pre-activation (AC5)

Below the activation level, Resonance is dormant and the composite is grayed in the UI. The contract still returns Intention and Action at full fidelity, because AC5 requires them to be “visible and moving”.

json

{
  "composite": { "value": null, "band": null, "status": "dormant" },
  "slices": {
    "intention": { "value": 55.0, "status": "live", "weight": 0.30, "effectiveWeight": 0.46, "...": "..." },
    "action":    { "value": 71.3, "status": "live", "weight": 0.35, "effectiveWeight": 0.54, "...": "..." },
    "resonance": { "value": null, "status": "dormant", "weight": 0.35, "effectiveWeight": 0,
                   "subSignals": { "instagramFollowers": { "value": null, "reason": "slice_dormant", "weight": 0.30 } } }
  },
  "activation": { "required": 4, "current": 3, "unlocked": false }
}

composite.value is null rather than a partial number. Returning a two-slice composite would mean the number changes meaning at activation, which AC5 forbids (“without a retroactive score discontinuity”). The activation block gives the frontend what it needs to render the locked state without inventing a value.

Note effectiveWeight on the live slices: 0.30 and 0.35 renormalize to 0.46 and 0.54. This is what lets the UI show relative contribution correctly while the composite stays hidden.

`overTargetRatio`

AC2 requires that exceeding a cadence maximum be “recorded but not scored”. The score caps at 100; the overshoot lands here as (actual - max) / max, floored at 0.

Nine posts against a maximum of seven gives content: 0.286. Nothing in the composite moves. The value exists so coaching can say that two posts’ worth of effort bought nothing, which the PRD names as one of the score’s most useful messages.

Clients must not display this as a score, a percentage over 100, or a bonus.

`configVersion`

Every response carries the config version its snapshot was computed under.

Clients must not cache across versions, and any client comparing two scores over time must check that the versions match before drawing a trend. A tuning pass changes what the number means, so a movement between two config versions is not a movement in the artist’s work.

Errors

Errors flow through catchAsync and utils/AppError.js to controllers/error/index.js, which attaches requestId from req.debugId to every response.

Case	Status	Notes
No token, or invalid	401	`isLogged`.
Feature flag off for this user	403	`requireFlag`.
No snapshot exists yet for this artist	200	Not an error. Returns the contract with every slice `null` and reason `insufficient_coverage`, plus `computedAt: null`. A new artist is not a failure.
Snapshot read fails	500	Generic, masked by the global handler.

The third row is the one worth being deliberate about. Returning 404 for an artist whose first nightly run has not happened yet would push the frontend into treating a normal state as an error path.

Contract test

Add a fixture under __tests__/contracts/ following docs/UI_CONTRACT_TESTING.md and the existing contracts/instagramOverview.contract.js pattern. The cases that matter are the ones where the shape changes rather than the numbers:

Everything live, all three slices present.
One platform disconnected, sub-signal null and Resonance renormalized.
Pre-activation, composite null and Resonance dormant.
Empty Brand Hub, Intention 0 and status empty.
No snapshot yet, 200 with all-null slices.

Open item affecting this contract

The brief states both that slice weights are locked at 0.30 / 0.35 / 0.35 and that an empty Brand Hub caps Buzz at 60. Those are inconsistent: with Intention at 0, the ceiling is 70. A 60 cap requires an Intention weight of 0.40. Details in buzz-score-feasibility.md, open item 1.

This does not change the contract’s shape, only the weight values it reports, so the contract can be agreed with EVO-4125 before the question is settled.

Buzz Score: Parameter Registry

Status: Working map, pending reconciliation with formula appendix v0.4.0 section 8 Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 AC1 and AC7 - Formula appendix v0.4.0 - PRD v2.5

Purpose

Written for product rather than engineering. AC7 makes these values yours to move, so this is the reference for what each one does, what it is safe to move it to, and what actually happens to a real artist’s score when you do.

A range without a sensitivity figure is not tunable. Knowing that the full-credit growth rate can be set between 2% and 4% tells you nothing useful; knowing that moving it from 3% to 2% takes a steadily growing artist from 67 to 100 on that sub-signal tells you everything. Every row below carries the second kind of information.

Numbering caveat. Appendix v0.4.0 section 8 owns the canonical P-numbers. That appendix was not available when this was written, so the numbering below is a working map derived from the parameters the epic brief names. Reconcile before this is used to write tickets. The parameters themselves are correct; only their labels are provisional.

How these are stored

Not a constants file. AC1 wants a single shared config source and AC7 wants changes without a code change, which together rule out services/gamification/constants/.

Parameters live in a BuzzScoreConfig record in Mongo, versioned, with exactly one active at a time. Changing a value creates a new version rather than mutating the old one, and every score snapshot records the version it was computed under.

That last point is the one with a consequence you will feel. After a tuning pass, scores from before and after are not comparable, because the formula that produced them differs. The snapshot’s configVersion is what stops a re-tune from silently rewriting every artist’s history. Plan tuning passes accordingly: they are cheap to run and not free to run often.

Status vocabulary

Status	Meaning
LOCKED	Decided in the brief under “do not re-litigate”. Config-driven so it can move, but moving it is a product reversal, not a tuning decision.
WORKING	Placeholder awaiting the validation pass. Expected to move.
DECIDED (v1)	Settled for Phase 1 specifically, with a known follow-on epic that changes it.
OPEN	Needs a decision before the dependent story can be built.

The registry

Composition

P	Parameter	Default	Status	Range
P1	Slice weights, Intention / Action / Resonance	`0.30 / 0.35 / 0.35`	LOCKED, but see below	must sum to 1
P14	Band thresholds	`90 / 75 / 60 / 45`	WORKING	ascending, within 0 to 100

P1 sensitivity, using a representative artist (Intention 72, Action 85.1, Resonance 41.2):

Intention weight	Composite	Empty Brand Hub ceiling
0.30	65.8	70
0.35	66.2	65
0.40	66.7	60

Note what moves and what does not. The composite barely shifts, under one point across the whole range. The ceiling moves ten points, and that is the number the artist-facing copy quotes.

This is the open contradiction flagged in buzz-score-feasibility.md item 1: the brief locks 0.30 and also states that an empty Brand Hub caps Buzz at 60, and those cannot both hold. Whichever way it resolves, resolve it before UI copy ships, because the artist-facing document already says 60.

Action slice

P	Parameter	Default	Status	Notes
P2	Cadence curve constant `k`	`4`	LOCKED	Same curve for both cadences. Reproduces every value in the published tables exactly.
P3	Content cadence maximum	`7` posts/week	LOCKED	Universal, not per-artist.
P4	Release cadence maximum	`2` releases/month	LOCKED	Universal.
P5	Action sub-weights, content / release / task	`0.55 / 0.30 / 0.15`	LOCKED
P5b	`taskFollowThrough` ratio definition	none	OPEN	No max, denominator, or curve is specified anywhere. See below.

P2 is not a tuning knob in practice. Changing k changes every published number at once. At k = 4 the sweet spots land at 84 (3 posts/week) and 88 (1 release/month), and the marginal value of the Nth post runs +44, +25, +14, +8, +4, +3, +1, which is the sequence the artist-facing copy quotes directly. Move k and that copy is wrong.

P5b sensitivity. At the coaching sweet spot of 3 posts per week and 1 release per month:

`taskFollowThrough`	Action score
1.0	87.4
0.5	79.9
0.0	72.4
`null` (renormalized)	85.1

Fifteen points of a slice worth 35% of the composite currently rests on a signal with no definition. The bottom row is the escape hatch: setting the weight to 0 for Phase 1 makes the sub-signal a dash and renormalizes content and release, which the null machinery already supports at no extra cost. That is a real option, not a workaround.

Resonance slice

P	Parameter	Default	Status	Range
P6	Rolling window	`4` weeks	WORKING	3 to 8 weeks
P7	Full-credit weekly growth rate	`+3%`	WORKING	1% to 5%
P8	Base-size reference	`10,000`	WORKING	1,000 to 100,000
P9	Coverage threshold, non-null days	`60%`	WORKING	40% to 80%
P10	Activation level	`L4`	WORKING	3 to 5
P11	Sub-signal weights, early and mature	see note	WORKING	must sum to 1 within each set

P7 sensitivity, for an artist growing steadily at +2% per week:

Full-credit rate	Their sub-signal score
2.0%	100.0
2.5%	80.0
3.0%	66.7
4.0%	50.0

This is the single most consequential parameter in the whole registry. It sets what “good” means for every artist at once, and the score is linear in it up to the cap, so a one-point move in the rate is a thirty-point move in the sub-signal. Tune it first, and tune it against the cohort distribution rather than against intuition about a single artist.

P8 sensitivity, showing the base-size multiplier by follower count:

Reference	200 followers	1,000	10,000	50,000
5,000	81.1	90.6	100.0	100.0
10,000	78.8	87.5	100.0	100.0
50,000	74.5	81.9	92.6	100.0

The parameter is gentler than it looks. Across the entire plausible range, a 200-follower artist sits between 74 and 81, never near zero. That is the intended behaviour: small artists are dampened, not penalised. If a proposed value pushes a small artist below about 70, it has stopped implementing “growth on a bigger base is more buzz” and started implementing “small artists cannot score”.

P9 and P10 cannot be given a sensitivity table here, because their effect is a count of artists rather than a score. Both should be set from the validation run output: P9 from how many artists flip to a dash at each threshold, P10 from where enough market signal actually exists to say something true.

P11 note. The brief calls for these to be split into early-post-activation and mature weightings. The priority order it states is that saves, shares, and comments rank above raw follows, and that social growth is weighted ahead of streaming early with streaming gaining weight as the artist matures. The exact numbers come from the appendix.

Intention slice

P	Parameter	Default	Status	Notes
P12	Sub-signal weights	coverage dominant, geometric three at `0`	DECIDED (v1)	Structure accommodates tightness, specificity, and trajectory at weight 0, so the follow-on epic switches them on by re-weighting rather than restructuring.
P13a	Recency grace period	`90` days	WORKING
P13b	Recency decay constant	`90` days	WORKING
P13c	Recency floor	none	WORKING
P15	Count proposed-but-unapproved material?	undecided	OPEN	Both `BrandHubDocument` and `BrandHubProposal` are queryable, so this is a scoring decision rather than a data one.

P13 sensitivity, for an artist whose Brand Hub coverage scores 80:

grace / decay	90 days	120 days	180 days	365 days
90 / 90 (default)	80.0	57.3	29.4	3.8
60 / 90	57.3	41.1	21.1	2.7
90 / 180	80.0	67.7	48.5	17.4
120 / 90	80.0	80.0	41.1	5.3

Read the default row carefully. With no floor, a complete Brand Hub that has not been touched for a year scores 3.8, which costs roughly 23 points of composite. Whether that is right depends entirely on how often the Brand Hub write gate fires.

That gate ships precision-first as an accepted risk (EVO-4368), and AC4 says any write resets the clock, including Arti’s automatic ones. So the decay’s severity is governed by the generosity of a gate deliberately tuned to be stingy. The brief’s chosen leading indicator, writes per artist per week off BrandHubWriteLog, is the right instrument; set its alert threshold from this table, by asking what write frequency keeps a typical artist inside the grace period, rather than picking a number freehand.

The 90 / 180 row is the obvious softener if the monitor shows low write rates: same grace period, half the decay speed, and a year of silence still costs real points without erasing the slice.

Parameters the appendix must settle

Three values cannot be responsibly set from the brief alone.

The Resonance consistency term (part of P6 and P7’s neighbourhood). AC3 describes it as penalising variance in weekly rates, and separately requires that a jump which holds must score while a spike that decays must not. A variance penalty cannot do both. See buzz-score-feasibility.md item 2 for the simulation.
P5b, the taskFollowThrough ratio. No max, no denominator, no curve.
P11, the Resonance sub-signal weights, both sets.

Changing a parameter

Edit the value through the admin surface. This creates a new BuzzScoreConfig version.
Run the validation harness against the new version before activating it. Procedure in buzz-score-validation-harness.md.
Check the cohort distribution, not just individual artists. The band table claims 75 to 89 is the target state, so if that band is empty or holds most of the cohort, the parameters are wrong regardless of how any single artist scores.
Activate. The next nightly run stamps the new version onto every snapshot.
Note that trend comparisons spanning the change are invalid, and that downstream consumers check configVersion before drawing one.

Buzz Score: Validation Harness Runbook

Status: Draft Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 AC7 - Parameter registry - Formula appendix v0.4.0

Purpose

AC7 is a soft gate with an unusual shape: it asks that Jacob and John be able to run the formula against real artists, compare the output against their own judgement, and change constants without a code change.

That is a procedure, not a feature, so this is a runbook rather than a design doc. It covers how to run it, how to change parameters, what invariants must hold no matter how you tune, and how to read the result.

The unusual advantage here is worth stating up front. MetricPoint holds daily metrics back to 2021-05-11, roughly 165,000 points. That means the formula can be scored over real artists across years of real history before any of this ships. Most scoring features have to launch to find out whether their numbers are sane. This one does not.

What the harness is

A script under scripts/, alongside the other operational tooling in this repo, that:

loads a BuzzScoreConfig version, or a plain JSON file of parameter overrides
resolves a cohort of artists
runs the same scoring core the nightly job runs, with no forks and no re-implementations
writes a per-artist breakdown and a distribution summary

Point 3 is the whole reason the scoring core is pure functions of (signals, config). A harness that reimplements the math validates the harness, not the product.

The script does not write BuzzScoreSnapshot. A tuning run must never mutate what artists see.

Running it

bash

node scripts/buzz-score-validate.js --config 4 --cohort alpha --out ./validation-2026-08-18

Flag	Meaning
`--config`	A `BuzzScoreConfig` version number, or a path to a JSON overrides file.
`--cohort`	`alpha`, `all`, a path to a file of user ids, or a single id for spot checks.
`--asOf`	Score as if run on this date. Defaults to today. This is what makes historical replay possible.
`--out`	Directory for the outputs.

Point it at stage. It is a read-only workload, but it is a wide one, and there is no reason to put that read pressure on production.

Changing parameters without a deploy

Two routes, both satisfying AC7:

For a real tuning pass, edit values through the admin surface. That creates a new BuzzScoreConfig version, inactive until activated, so it can be validated first and activated second.

For exploration, pass a JSON file. Only the keys present are overridden; everything else comes from the active config.

json

{
  "resonance": { "fullCreditWeeklyGrowth": 0.02, "refBase": 5000 },
  "intention": { "recencyDecayDays": 180 }
}

Sweeping one parameter is a loop over files. Do not sweep two at once on the first pass; the parameters interact and a two-dimensional sweep is unreadable before you know the shape of each one on its own.

Invariants: fixtures that must pass regardless of tuning

These are properties of the design, not of any parameter value. If a tuning pass breaks one, the parameters are not the problem.

Run as unit tests against the core, not as part of a cohort run.

#	Fixture	Must hold
1	Jump that holds. Followers double in week 1 and stay at the new level for weeks 2 to 4.	Scores near full credit. This is the one that fails silently under a naive variance penalty, and it will not surface unless the fixture exists. See feasibility item 2.
2	Spike then crash. Followers double in week 1 and return to baseline by week 4.	Scores near zero, and strictly below a steady +2% per week artist.
3	Disconnected platform. One platform absent.	Sub-signal is `null` with reason `platform_disconnected` and the slice renormalizes. Never `0`.
4	Empty Brand Hub. No documents.	Intention is `0` with status `empty`, and the composite ceiling equals `(1 - intentionWeight) * 100`.
5	Over maximum. Nine posts a week against a max of seven.	Content scores exactly 100 and `overTargetRatio` records the overshoot. No credit above the ceiling.
6	Shrinking metric. Followers decline every week.	Floors at `0`. Never negative.
7	Below activation. Artist under the activation level.	Composite is `null`, not a two-slice partial. Resonance is `dormant`.
8	Collector failure. A signal collector throws.	`null` with reason `collection_failed`. Never `0`, and distinguishable from `insufficient_coverage`.
9	Published table reproduction. Cadence scores at 0 through 7 posts per week and 0 through 2 releases per month.	Matches the published tables. These numbers are quoted in artist-facing copy.

Fixtures 1, 2, and 9 are the ones to write first. Fixture 9 is a regression guard on the copy; fixtures 1 and 2 are the pair that decides whether the score means what the PRD says it means.

Reading the output

`artists.csv`

One row per artist: composite, each slice, each sub-signal, each reason, coverage counts, and the band. Sort by composite and read the extremes first. The middle of the distribution is usually unremarkable; the artists at 95 and at 12 are where a wrong parameter shows itself.

`distribution.md`

This matters as much as any individual score, and it is the cheapest output to produce.

The band table claims 75 to 89 is “the top of the realistic scale” and the target state. Whether that is true is an empirical question about the cohort, and it is answerable now:

Symptom	Likely cause
Green band nearly empty	Full-credit growth rate set too high, or cadence expectations unreachable for this cohort.
Most of the cohort in green	Full-credit growth rate too low. The band stops distinguishing anything.
Bimodal, with a cluster near zero	Check `reason` counts before touching parameters. This is usually coverage or connection gaps, not scoring.
Everyone within a few points	A slice is dominating, or too many sub-signals are dashing and renormalizing to the same handful of inputs.

`coverage.md`

Counts of each reason across the cohort. Read this before the distribution, every time.

A cohort where 40% of artists have Spotify dashing does not have a scoring problem, and no parameter change will fix it. Confusing a data gap for a tuning problem is the most likely way for a validation pass to reach a wrong conclusion, which is why coverage gets its own file rather than a column.

The tuning loop

Run with the current active config. This is the baseline. Do not skip it; you need something to compare against.
Read coverage.md first. Resolve data gaps before touching parameters.
Sweep one parameter. Start with the full-credit weekly growth rate. It is the most consequential value in the registry: the score is linear in it up to the cap, so a one point move in the rate is roughly a thirty point move in the sub-signal.
Check the invariants still pass. They are parameter-independent, so a failure means something structural broke.
Compare distributions, not artists. Individual scores will move; the question is whether the bands land where product intends.
Spot-check named artists. This is where Jacob and John’s judgement is the instrument. Pick artists whose situation they know well, and check that the number and its breakdown match what they would have said unprompted.
Write the chosen values into a new config version, with a note recording why.
Activate. The next nightly run stamps the new version onto every snapshot.

After activation

Scores computed under different config versions are not comparable, because the formula differs. Every snapshot carries its configVersion for exactly this reason, and any consumer drawing a trend must check that the versions match.

Practical consequence: a tuning pass creates a seam in every artist’s history. Tuning passes are cheap to run and not free to run often. Batch parameter changes into one pass rather than trickling them.

Prerequisites

Needs	Why
Pure scoring core	The harness calls the same functions the nightly job does.
DB-backed config with overrides	AC7’s “without a code change”.
`--asOf` support in the collectors	Historical replay. Collectors must accept a date rather than reading the clock.
Stage data refreshed	`MetricPoint` history is what makes replay meaningful.

The first three land in the config and core stories, so the harness is buildable before the API. It runs the core directly and does not need an endpoint. That ordering is deliberate: it means constants can be tuned while the API and frontend work proceeds in parallel.

Buzz Score: Epic Breakdown

Status: Draft for breakdown session Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 - EVO-4333 - EVO-4361 to EVO-4369 - EVO-4125

Purpose

Phase 1 cut into stories, with dependency order and the open product item each one is blocked on.

Estimates are indicative starting points, not commitments. They assume one backend engineer familiar with the gamification and metrics subsystems and exclude review and QA. Size them properly with the people who will do the work.

Sequencing

text

  BS-15 spike ......................................... informs BS-9
  (do first, 1d, no deps)

  BS-1        BS-2         BS-3 Action ----+
  config ---> core ---+--> (open item 3)   |
  3d          3d      |                    |
                      +--> BS-4 Resonance -+--> BS-6 -----+--> BS-7 ---> BS-8 ---> BS-14
                      |    (open item 2)   |    snapshot  |    cron      events    FE wiring
                      |                    |    2d        |    2d        2d        1d
  EVO-4361..4364 -----+--> BS-5 Intention -+              |
  Brand Hub, in PR    |    (open items 4,5)               +--> BS-9 ---> BS-13
                      |                                   |    API       Arti tool
                      |                                   |    3d        2d
                      |                                   |
                      +--> BS-10 ------> BS-11            +--> BS-12
                           harness       replay                Arti rollup
                           3d            2d                    3d

                           \____ no API dependency ____/

Three things fall out of this shape:

BS-1 and BS-2 gate everything. Nothing else can start meaningfully until config and the pure core exist. They are also the two smallest stories with the least uncertainty, so this is a good place for the epic to start rather than a bottleneck to work around.
BS-10, the validation harness, does not wait for the API. It runs the core directly. That means the parameter tuning pass can happen in parallel with API and frontend work rather than after it, which is the difference between tuning before launch and tuning after.
BS-15 should run first, before BS-9 hardens the contract. It is a one-day spike, and its whole value is being cheap and early.

Stories

BS-1: `BuzzScoreConfig` model, service, and admin surface

AC1, AC7. Approximately 3 days. No blockers.

DB-backed versioned parameter record with exactly one active version, a 60 second cached accessor with an invalidation hook, and an admin surface for edits. Follow models/FeatureFlag.js plus services/featureFlagService.js, which already solve this exact problem in this repo.

Not a constants file. AC1 wants a single shared source and AC7 wants changes without a deploy, which together rule out services/gamification/constants/.

Done when: a parameter can be changed and take effect without a deploy, and every version is retrievable by number.

BS-2: Scoring core

AC1, AC2. Approximately 3 days. Depends on BS-1.

Pure functions of (signals, config): the cadence curve, the three slice composers, and the top-level composition with weight renormalization. No database access, no clock reads, no module-scope constant imports.

Includes the invariant fixtures from buzz-score-validation-harness.md, in particular the published cadence tables and the jump-that-holds and spike-then-crash pair.

Note for the story description: services/gamification/helpers/velocityHelper.js already computes a 0-100 composite from posting and release cadence and must not be reused. It is linear, caps at 150%, applies per-level aggressionMultipliers, weights login frequency, and returns { score: 0 } on error. Every one of those is explicitly prohibited by AC2 or the null rule. Its two fetchers are fine; its scoring is the thing being replaced. Say this in the ticket or it will be rediscovered the expensive way.

Done when: the published tables reproduce exactly and all nine invariants pass.

BS-3: Action slice collectors

AC2. Approximately 3 days. Depends on BS-2. Blocked in part by open item 3.

Rolling 28-day posts per week from ScheduledPost.platformStatus.<p>.publishedAt, and rolling 90-day releases per month from Release.release_date. Both wrap the existing velocityHelper fetchers in null-returning variants, because both currently swallow errors into 0.

taskFollowThrough carries 15% of the slice and has no ratio definition anywhere. It also has no clean data path: Task.js has no completedAt, so completion time comes from statusHistory[].changedAt, and ActivityLog has no {userId, activityDate} index.

Two ways to unblock, and the ticket should name both:

Define the ratio and add the index. Adds roughly 1 day.
Set its weight to 0 for Phase 1. Content and release renormalize automatically through the AC1 machinery, at no extra cost. Action at the sweet spot then reads 85.1 rather than swinging between 72.4 and 87.4 on an undefined signal.

Done when: posts and releases produce correct rolling rates including externally-created posts, and a collector failure yields null rather than 0.

BS-4: Resonance slice collectors and math

AC3. Approximately 5 days. Depends on BS-2. Blocked by open item 2.

Weekly series per metric per platform out of MetricPoint through repositories/socialMetricsRepository.js, then growth, consistency, and base-size scaling per sub-signal, with the coverage threshold and per-platform renormalization.

Reuse calculateGrowthRate from helpers/growthTrackHelper.js. It already implements the null-versus-zero convention correctly and carries MIN_PERCENTAGE_BASELINE = 10 for count metrics. Apply that floor to follower counts and not to rate metrics such as Engagement Rate, per the warning in that file.

The consistency term is the open question. AC3 asks for a variance penalty and separately requires that a jump which holds must score, and a variance penalty cannot do both. The ticket should carry the simulation from buzz-score-feasibility.md item 2 and be explicit that fixture 1 is the acceptance test.

Scope note: “streams” in Phase 1 means account-level Spotify Listeners. Per-track stream history is not persisted, and YouTube does not exist as an integration at all.

Done when: all four Resonance invariants pass and a disconnected platform renormalizes rather than zeroing.

BS-5: Intention slice, coverage and recency

AC4. Approximately 5 days. Depends on BS-2 and on EVO-4361 to EVO-4364 merging. Blocked by open items 4 and 5.

A facet coverage calculator over the six Brand Hub documents, using services/brand-hub/emptyDocs.js as the canonical field map, plus the recency multiplier off BrandHubDocument.updatedAt.

Three things the ticket must carry:

There is no completeness notion today. isSeeded is a boolean and is true for a completely empty seed. This is built from scratch.
content is Schema.Types.Mixed, so shapes are convention rather than schema. The scorer owns a canonical facet-path map and reads defensively.
Seeded entries must be excluded. seedFromBuzz writes exactly three taste-timeline entries and one decision-log entry for every questionnaire completer, and EVO-4364 backfills the same for existing users. A naive “does this document have entries” facet therefore passes automatically for the entire alpha cohort and measures nothing. lastUpdatedBy: 'seed', seededAt, and each entry’s source all make seeded material identifiable.

Done when: an all-empty seeded Brand Hub scores near 0 on coverage rather than passing the append-only facets, and the recency curve matches the parameter registry table.

BS-6: `BuzzScoreSnapshot` model and persistence

AC6. Approximately 2 days. Depends on BS-3, BS-4, BS-5.

One document per user per day carrying the composite, three slices with status, every sub-signal with value-or-null and reason, overTargetRatio, coverage counts, and configVersion.

Follow the MetricPoint meta convention, and heed the lesson recorded in that model: do not pass timeseries: { granularity: 'days' }, which is not a valid MongoDB value and silently degrades to an ordinary collection. Declare an ordinary collection deliberately. No TTL, for the reasons recorded on PostMetricPoint.

Done when: a snapshot round-trips with nulls and reasons intact, and configVersion is always populated.

BS-7: `BuzzScoreScheduler`

AC6. Approximately 2 days. Depends on BS-6.

extends BaseCronService, registered in services/cron/index.js, at 0 23 * * * UTC so it runs after the metrics crons settle. The last of those is instagram-engagement-notify at 20 22 * * *.

Overlap protection, timeout, per-job logging, and the cross-instance run lock through models/CronJobRunClaim.js all come from the base class. Recompute must be idempotent: rerunning for the same day overwrites that day’s snapshot.

Done when: a full cohort run completes inside its timeout and a second run for the same day produces an identical snapshot.

BS-8: Change detection and downstream events

AC6. Approximately 2 days. Depends on BS-7.

AC6 requires that a sub-signal moving materially while the composite does not must be detectable downstream. Compare each sub-signal against the previous snapshot and emit through eventsHub/eventEmitter.js when a configured delta is crossed.

The threshold is a config parameter, not a literal.

Done when: a sub-signal move with a flat composite produces an event.

BS-9: API endpoint, feature flag, contract test

AC1, AC5. Approximately 3 days. Depends on BS-6. Informed by BS-15.

GET /api/v1/buzz-factory/v2/buzz-score on the existing router, standard envelope, catchAsync and AppError, gated by requireFlag with a key in enums/flagKey.js and a seed row in seeds/featureFlags.js. Full shape in buzz-score-contract.md.

A pure read. The precedent to avoid is in this same subsystem: getBuzzFactoryOverviewV2Service promotes users and fires notifications from inside a GET.

Contract test covering the five shape-changing cases, following docs/UI_CONTRACT_TESTING.md. Note that “no snapshot yet” returns 200 with null slices, not 404. A new artist is not an error.

Done when: all five contract cases pass and the flag gates cleanly in both states.

BS-10: Validation harness

AC7. Approximately 3 days. Depends on BS-2. Does not depend on the API.

Script under scripts/ that loads a config version or an overrides file, resolves a cohort, runs the same scoring core the nightly job runs, and writes per-artist, distribution, and coverage outputs. Read-only; it must never write snapshots.

Requires --asOf support in the collectors, which is what makes historical replay work.

Done when: Jacob and John can change a parameter, rerun, and read a distribution without an engineer in the loop.

BS-11: Historical replay and seeding

AC6, AC7. Approximately 2 days. Depends on BS-10.

Backfill snapshots over historical MetricPoint data so trajectory exists at launch rather than accumulating from zero.

Label backfilled snapshots honestly. They are the formula applied retroactively, not measurements taken on those days. The Intention slice in particular cannot be replayed accurately, because Brand Hub history only goes back to when BrandHubWriteLog shipped on 2026-08-12.

Done when: replayed snapshots are distinguishable from live ones.

BS-12: Arti rollup branch and formatter

AC5. Approximately 3 days. Depends on BS-6. Repo: both.

Extend services/agent/smartRollupBuzzFactoryService.js to carry the score block. On the Python side, add the branch in generate_initial_rollup_stream() and a typed formatter in app/services/user_data_insights/data_formatter_service.py, so follow-up turns stop falling through to the generic formatter.

Voice constraint, and this is the substance of the story rather than a footnote. The existing buzz_factory rollup prompt opens with “Celebration”, asks for “genuine enthusiasm”, and instructs the model to “make them feel proud”. The Buzz Score register is the opposite by design: a falling score is a diagnosis rather than a scolding, no participation points, and the ability to tell an artist to do less of something. These cannot share a prompt.

Done when: a score with a dash in it is explained as “we cannot see this” rather than as a deficiency.

BS-13: Arti on-demand tool

AC5. Approximately 2 days. Depends on BS-9. Repo: genesis-train.

A BUZZ_TOOLS module on the app/agents/questionnaire/tools.py template, registered in CHAT_TOOLS and announced in both catalogues in app/services/ai/prompt_service.py. Calls the API through APIClient._make_request with the user’s JWT from state["token"].

Done when: “why is my buzz score 62” returns an explanation grounded in the actual breakdown.

BS-14: Frontend analytics wiring

AC6. Approximately 1 day. Depends on BS-8. Repo: artistevolve-fe.

Replace the hardcoded values at components/common/components/BuzzfactoryInfo.tsx lines 30 and 38 and at app/(dashboard)/dashboard/page.tsx:821, each of which currently sends buzz_score: 0 and user_level: 1, and wire the real score into the PostHog events that lib/analytics/trackers/gamification-tracker.ts already defines: buzz_score_updated with old_buzz_score and new_buzz_score, and buzz_score_milestone.

The tracker is already built. This is wiring, not new instrumentation.

BS-15: EVO-4125 contract reconciliation

AC5. Approximately 1 day, spike. No dependencies. Do this first.

EVO-4125 is in PR and renders level progress as a placeholder. The real contract is three slices with per-slice status and an inspectable breakdown, not a single number, and level progress is an explicit non-input under AC2. So the eventual swap changes what the gauge means rather than repointing a data source.

Settle whether the gauge’s props match the AC1 shape before it hardens.

Done when: the gauge’s contract is agreed against buzz-score-contract.md, or a follow-up is raised.

Decision gates

Each open item blocks a specific story. None blocks starting the epic.

Open item	Blocks	If unresolved at sprint start
1. 60 versus 70 cap	UI copy, not code	Ship with the locked 0.30 weight. Hold copy referencing a cap.
2. Resonance consistency term	BS-4	Implement the retention factor. It satisfies both AC3 clauses; a variance penalty does not.
3. `taskFollowThrough` definition	BS-3	Set weight to `0` and renormalize. Reversible through config alone.
4. P15, unapproved brand material	BS-5	Count only what reached the document. The narrower reading is the reversible one.
5. Seed-entry exclusion	BS-5	Exclude via `lastUpdatedBy: 'seed'`. Not excluding makes the facet measure nothing.

Every fallback in the right-hand column is reversible through config or a small change. None of them require guessing at something expensive to undo.

Explicitly out of Phase 1

From the brief, recorded here so they do not creep in at breakdown: geometric Intention (distillation, embeddings, tightness, specificity, trajectory), uniqueness and cross-artist comparison, LLM-judged content quality, L6 gating on Buzz, score projection, and external output analysis.

Testing conventions

Layer	Approach	Template
Scoring core	Plain unit tests, no mocks	any pure helper test
Collectors	`jest.unstable_mockModule`, then dynamic `await import()`	`__tests__/smartRollupBuzzFactoryService.test.js`
Snapshot and scheduler	`mongodb-memory-server`, mocking only side-effecting collaborators	`__tests__/buzzFactoryOverviewV2.test.js`
Config service	Mock-only, covering cache expiry and version stamping	`__tests__/featureFlagService.test.js`
API	Contract test	`__tests__/contracts/instagramOverview.contract.test.js`
genesis-train	`AsyncMock` on `APIClient._make_request`	`app/tests/unit/test_buzz_factory_rollup.py`

Jest runs ESM through NODE_OPTIONS=--experimental-vm-modules; utils/logger.js is mocked in every unit test.

Buzz Score Integration

Status: Design, pending tech-lead sign-off Created: 2026-08-18 Last Updated: 2026-08-18 Related Work: Buzz Score epic brief v1.1 AC5 - genesis-web docs/architecture/buzz-score-architecture.md

What this covers

Arti’s side of the Buzz Score. genesis-web computes the score; this service explains it.

Thin by design. SMART_ROLLUP.md and SERVICE_AUTHENTICATION.md already carry the shared background for both repos, and this document only adds what is specific to Buzz Score.

What this service does not do

It does not compute any part of the score.

This service has direct Mongo access, but only for its own concerns: LangGraph checkpoints, memory extraction, credits, and Idea Center boards. Every piece of product data it uses arrives over HTTP from genesis-web through app/utils/api_client.py. There are no models for badges, levels, or metrics anywhere in this repo, and there should not be.

Score data reaches Arti one of two ways, matching the two existing patterns:

Pattern	Path	Existing example
Pushed with the page	`moduleContext.data` on a rollup request	`smartRollupBuzzFactoryService` today
Pulled on demand	`APIClient._make_request` with the user’s JWT	`app/agents/questionnaire/tools.py`

text

  SEAM 1   page open, pushed
  ---------------------------
  artist opens Buzz Factory
        |
        v
  genesis-web   smartRollupBuzzFactoryService builds moduleContext
        |       (level + badges + questionnaire + buzz_score block)
        v
  POST /api/v1/agent/chat/stream   { generateInitialRollup: true, moduleContext }
        |
        v
  genesis-train  generate_initial_rollup_stream() -> buzz_score branch -> LLM
        |
        v
  SSE deltas ---> genesis-web ---> browser        Arti speaks first, no user message


  SEAM 2   conversation, pulled
  -----------------------------
  "why is my buzz score 62?"
        |
        v
  genesis-train  chat graph -> BUZZ_TOOLS
        |        APIClient._make_request, user JWT from state["token"]
        v
  GET /api/v1/buzz-factory/v2/buzz-score ---> genesis-web reads latest snapshot
        |
        v  lean JSON
  LLM narrates the breakdown ---> browser

The two seams differ in who starts the conversation and in how the data travels, but both read the same snapshot. Neither recomputes anything. Seam 1 gets the score handed to it as page context; seam 2 fetches it because the artist asked a question that the page context may not be open to answer.

Seam 1: the page-open rollup

When an artist opens the Buzz Factory page, genesis-web gathers the module data and POSTs to /api/v1/agent/chat/stream with generateInitialRollup: true. Arti speaks first, with no user message.

What arrives

genesis-web extends services/agent/smartRollupBuzzFactoryService.js so the existing buzz_factory ModuleContext carries a score block alongside level, badges, and questionnaire:

python

data["buzz_score"] = {
  "composite":  {"value": 65.8, "band": "building", "status": "live"},
  "slices": {
    "intention": {"value": 72.0, "status": "live",   "subSignals": {...}},
    "action":    {"value": 85.1, "status": "live",   "subSignals": {...}},
    "resonance": {"value": 41.2, "status": "live",   "subSignals": {...}},
  },
  "overTargetRatio": {"content": 0, "release": 0},
  "trend": {"deltaVsLastWeek": +3.1, "configVersionStable": True},
  "configVersion": 3,
}

Every sub-signal is {"value": number|null, "reason": str|null, "weight": float}. The full contract, including the reason vocabulary, lives in genesis-web’s docs/architecture/buzz-score-contract.md.

Changes needed here

A buzz_score branch in generate_initial_rollup_stream() in app/api/routers/chat_api.py, or an extension of the existing buzz_factory branch. Note the voice constraint below before reusing that branch’s prompt.
An onboarding string in get_onboarding_message() for the pre-activation case, where the composite is not yet live.
A typed formatter in app/services/user_data_insights/data_formatter_service.py. Today buzz_factory has no formatter, so follow-up turns fall through to _format_generic_for_analysis(), which JSON-dumps the payload against a 2000-token budget and truncates. A score breakdown truncated mid-structure produces confident nonsense, so this is worth doing rather than deferring.

Structural note. The rollup ladder in chat_api.py is roughly 500 lines of inline prompt strings inside one function. Adding a branch follows precedent but deepens that hotspot, and app.api.routers.chat_api is in the mypy ignore_errors baseline so a new file there gets no type checking. Extracting per-module prompt builders into app/services/user_data_insights/ matches how every other domain in this repo is organised and would give the new code full checking. Worth raising at breakdown; not a blocker.

Seam 2: the on-demand tool

For “why is my buzz score 62” asked in normal conversation.

A BUZZ_TOOLS module following the app/agents/questionnaire/tools.py template, which is both the cleanest example in the repo and already Buzz-Factory-adjacent:

module docstring saying when Arti should reach for it
private _lean_* helpers that shrink the payload before it reaches the model
@tool async def with a docstring full of example user phrasings
token = state["token"], then APIClient._make_request("GET", "/buzz-factory/v2/buzz-score", token=token)
json.dumps(...) on success, json.dumps({"error": ...}) on failure
logger.info("🔧 TOOL: ...")
trailing BUZZ_TOOLS = [...]

Register it in CHAT_TOOLS (app/agents/chat/tools.py) and announce it in both catalogues in app/services/ai/prompt_service.py: get_tool_index_context() (the lean one, gated by LEAN_CHAT_CONTEXT) and get_full_tool_capabilities_context(). Both already carry a Buzz Factory line listing the questionnaire tools; extend it rather than adding a new section.

Authentication

Unchanged from SERVICE_AUTHENTICATION.md. Two schemes over the same Authorization: Bearer header:

Caller	Token	Notes
Agent tools acting for an artist	The user’s JWT from `state["token"]`	The user id in this service is the email address, taken from the `emailAddress` claim.
Service-to-service reads	`Bearer service:<SERVICE_AUTH_TOKEN>`	`get_flexible_auth()` returns `user_id == "service_user"`. Bypasses the credit check.

The score endpoint is a per-artist read, so the on-demand tool uses the user’s JWT. It sits behind isLogged on the genesis-web side and is additionally feature-flagged, so the tool must handle a 403 as “not available for this artist yet” rather than as an error.

Voice

The existing buzz_factory rollup prompt cannot be reused as-is.

Its response structure opens with “Celebration”, asks for “genuine enthusiasm”, instructs the model to “make them feel proud”, and closes on “be celebratory of what they’ve accomplished”. That is correct for a gamification hub built on badges and levels.

The Buzz Score is a different instrument and commits to the opposite register:

The score’s stated commitments	What that rules out
“A falling score is a diagnosis, not a scolding”	Framing a drop as a failure, or as motivation
“We don’t hand out participation points”	Celebrating movement that did not happen
A dash means “we can’t see this yet”, never “you have no resonance”	Reading a `null` as a deficiency
The coach can say do less of one thing	Advice that only ever adds work
“If your action is high and the market is quiet, the honest message is keep going, let’s talk strategy, never post more”	Prescribing more output when Action is already at the ceiling

The last row is the whole point of the feature. An artist doing everything right into a quiet market is the case the score exists to describe, and telling that artist to post more is the specific failure it was built to prevent.

Two prompt rules follow directly from the contract:

overTargetRatio above zero means say less, not more. Nine posts against a maximum of seven bought nothing. Arti should say so.
A dash and a zero are different sentences. reason: "platform_disconnected" is “we can’t see TikTok”. A genuine 0 is “this is flat”. Never collapse them.

Testing

app/tests/unit/, following test_buzz_factory_rollup.py. That file’s shape is worth copying: it asserts on the onboarding strings directly, and hand-builds moduleContext dicts to document the contract genesis-web produces, naming the producing service in a comment.

Use unittest.mock.patch and AsyncMock on APIClient._make_request for the tool, and monkeypatch.setenv for env, per test_brand_hub_client.py.

conftest.py already provides test_user_context, which carries buzzProgress.

Cases worth having:

a live score with all three slices renders every slice
a dash renders as “cannot see” language, not as a zero
pre-activation renders Intention and Action while the composite stays absent
overTargetRatio above zero produces do-less guidance
a 403 from the endpoint degrades gracefully

Source files

genesis-web/docs/proposals/buzz-score-feasibility.md
genesis-web/docs/architecture/buzz-score-architecture.md
genesis-web/docs/architecture/buzz-score-contract.md
genesis-web/docs/proposals/buzz-score-parameters.md
genesis-web/docs/proposals/buzz-score-validation-harness.md
genesis-web/docs/proposals/buzz-score-epic-breakdown.md
genesis-train/docs/BUZZ_SCORE_INTEGRATION.md

Buzz Score: Technical Feasibility Read

Purpose

Verdict summary

AC1: Score service and contract

AC7 rules out a constants file

Contract shape

Null-renormalization is already house law

AC2: Action slice

The curve is confirmed

Data for content and release cadence is ready

taskFollowThrough is blocked on two things

The prohibition is already load-bearing

AC3: Resonance slice

The time series is ready

Available metrics per platform

Three gaps

The one formula ambiguity

Coverage threshold

AC4: Intention slice

What exists

What must be built

The seed-entry trap

Recency is available at document level

The decay and the write gate compound

The 60 versus 70 contradiction

AC5: Surfacing

Coordination flag, wider than the brief states

AC6: Recompute cadence and history

AC7: Validation harness

Open items

Dependencies

Buzz Score: Cross-Repo Architecture

Purpose

Service boundary

Why genesis-train does not compute the score

The scoring core is pure functions

Configuration

Why not a constants file

BuzzScoreConfig

Signal collectors

The two reuse traps

BuzzScoreSnapshot

Compute path

Why 23:00 and not earlier

Change detection

Read path

Failure modes

genesis-train integration

Voice conflict

Testing

Buzz Score: Service API and Data Contract

Purpose

Endpoint

Response

Worked example

Field reference

composite

Slice

Sub-signal

Slice status

Reason vocabulary

Bands

Pre-activation (AC5)

overTargetRatio

configVersion

Errors

Contract test

Open item affecting this contract

Buzz Score: Parameter Registry

Purpose

How these are stored

Status vocabulary

The registry

Composition

Action slice

Resonance slice

Intention slice

Parameters the appendix must settle

Changing a parameter

Buzz Score: Validation Harness Runbook

`taskFollowThrough` is blocked on two things

`BuzzScoreConfig`

`BuzzScoreSnapshot`

`composite`

`overTargetRatio`

`configVersion`

`artists.csv`

`distribution.md`

`coverage.md`

BS-1: `BuzzScoreConfig` model, service, and admin surface

BS-6: `BuzzScoreSnapshot` model and persistence

BS-7: `BuzzScoreScheduler`