feat: telemetry agent — internal/usage rolling counters + Counts payload (CA-400 phase 2)

* New internal/usage package: RollingDayCounter primitive (clock-injectable,
  ResetForTest seam) with package-level QueriesCounter / ArtifactsCounter,
  both 30-day windows
* QA ask call site (qa/pipeline.go) increments QueriesCounter alongside
  existing qa.CountAsk() (preserves qa_asks_total_14d field; no consolidation)
* New markArtifactReady wrapper in graphql layer: instruments three resolver
  paths (knowledge_generation_shared.go, knowledge_generation_cliff_notes.go,
  knowledge_generation_architecture_diagram.go). Each preserves its existing
  error policy (log-and-continue / return-error). Seed (SupersedeArtifact) and
  deepening paths intentionally bypass the wrapper.
* TelemetryCounts() exposes "queries_30d" and "artifacts_generated_30d" keys
  to the collector via the existing Counts JSON blob (no ping struct change).
* TELEMETRY.md: two new rows in the collected-fields table disclosing the
  process-local + resets-on-restart caveat.
* docs/admin/telemetry-collector-qa-fields.md: sample SQL for the new keys
  with the 48h freshness-gate rationale (CA-400 Decision 6).
* Makefile: new check-telemetry-disclosure target enforcing the grep gate.

Plan: thoughts/shared/plans/active-2026-05-14-deliver-telemetry-metrics-expansion.md
Ticket: CA-400

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jstuart0

Makefile

@@ -4,7 +4,8 @@
 	dev dev-web dev-go dev-worker clean migrate help integration-test test-integration smoke-test phase-gate ci \
 	test-livingwiki-integration test-livingwiki-smoke test-scripts \
 	benchmark-comprehension-fake benchmark-comprehension-local benchmark-comprehension-report \
-	benchmark-report-quality-live
+	benchmark-report-quality-live \
+	check-telemetry-disclosure
 
 GO_BIN = bin/sourcebridge
 GO_MIGRATE_BIN = bin/migrate
@@ -87,6 +88,13 @@ lint-worker:
 lint-vscode:
 	cd plugins/vscode && npx eslint src --ext ts
 
+# Telemetry disclosure gate: verify that every key shipped in the Counts
+# blob is documented in TELEMETRY.md. Add a grep line for each new key.
+check-telemetry-disclosure:
+	@grep -q '`queries_30d`' TELEMETRY.md || (echo "TELEMETRY.md missing queries_30d disclosure"; exit 1)
+	@grep -q '`artifacts_generated_30d`' TELEMETRY.md || (echo "TELEMETRY.md missing artifacts_generated_30d disclosure"; exit 1)
+	@echo "telemetry disclosure: ok"
+
 # Package the VS Code extension as a VSIX. The output file lands in
 # plugins/vscode/ and is gitignored. Use `install-vscode` to drop it
 # into your local VS Code afterward.

TELEMETRY.md

@@ -21,6 +21,8 @@ information is ever collected.
 | `trash_purges_total` | `120` | Cumulative count of rows purged by the retention worker |
 | `trash_size_gauge` | `17` | Most recent sampled count of items currently in the trash |
 | `qa_asks_total_14d` | `342` | Rolling 14-day count of server-side QA (`/api/v1/ask`, `ask` mutation, MCP `ask_question`) invocations on this install. Zero when server-side QA is disabled. |
+| `queries_30d` | `342` | Rolling 30-day count of QA invocations (every `Orchestrator.Ask`) on this install. **Process-local; resets to zero when the agent process restarts; reported as the in-process sum at the moment of the ping.** Zero on fresh processes; grows over the next 30 days. |
+| `artifacts_generated_30d` | `17` | Rolling 30-day count of knowledge artifacts (cliff notes, architecture diagram, learning path, code tour, workflow story) that transitioned from GENERATING to READY via user-requested generation. **Excludes** field-guide seed artifacts and cliff-note section deepening (initialization/refresh, not new generation). **Process-local; resets to zero on agent process restart.** |
 | `qa_server_side` feature flag | `["qa_server_side"]` | Present in the `features` array when `SOURCEBRIDGE_QA_SERVER_SIDE_ENABLED=true`. Lets the public dashboard track orchestrator adoption. |
 | `clustering_enabled` | `true` | True when the `subsystem_clustering` capability is active on this installation. |
 | `cluster_count` | `12` | Number of clusters for the largest indexed repository. Zero when clustering has not run or no repos are indexed. |

cli/serve.go

@@ -43,6 +43,7 @@ import (
 	"github.com/sourcebridge/sourcebridge/internal/settings/livingwiki"
 	"github.com/sourcebridge/sourcebridge/internal/telemetry"
 	"github.com/sourcebridge/sourcebridge/internal/trash"
+	"github.com/sourcebridge/sourcebridge/internal/usage"
 	"github.com/sourcebridge/sourcebridge/internal/version"
 	"github.com/sourcebridge/sourcebridge/internal/worker"
 	"github.com/sourcebridge/sourcebridge/internal/worker/llmcall"
@@ -1436,6 +1437,12 @@ func (p *telemetryCountProvider) TelemetryCounts() (repos, users int, features [
 		counts[k] = v
 	}
 
+	// Merge in rolling 30-day usage counters (queries + artifacts generated).
+	// Process-local; resets to zero on agent restart.
+	for k, v := range usage.Counters() {
+		counts[k] = v
+	}
+
 	if qa.ServerSideEnabled() {
 		features = append(features, "qa_server_side")
 	}

cli/serve_telemetry_test.go

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 SourceBridge Contributors
+
+package cli
+
+import (
+	"testing"
+
+	"github.com/sourcebridge/sourcebridge/internal/graph"
+	"github.com/sourcebridge/sourcebridge/internal/usage"
+)
+
+// TestTelemetryCountsIncludesUsageKeys verifies that TelemetryCounts returns
+// both "queries_30d" and "artifacts_generated_30d" keys in its Counts map,
+// and that the values reflect the package-level rolling counters.
+func TestTelemetryCountsIncludesUsageKeys(t *testing.T) {
+	t.Cleanup(usage.ResetCountersForTest)
+
+	usage.QueriesCounter.Inc()
+	usage.ArtifactsCounter.Inc()
+	usage.ArtifactsCounter.Inc()
+
+	p := &telemetryCountProvider{store: graph.NewStore()}
+	_, _, _, counts := p.TelemetryCounts()
+
+	if counts == nil {
+		t.Fatal("TelemetryCounts returned nil counts map")
+	}
+	if got, ok := counts["queries_30d"]; !ok {
+		t.Fatal("counts map missing key 'queries_30d'")
+	} else if got != 1 {
+		t.Fatalf("queries_30d: expected 1, got %d", got)
+	}
+	if got, ok := counts["artifacts_generated_30d"]; !ok {
+		t.Fatal("counts map missing key 'artifacts_generated_30d'")
+	} else if got != 2 {
+		t.Fatalf("artifacts_generated_30d: expected 2, got %d", got)
+	}
+}

docs/admin/telemetry-collector-qa-fields.md

@@ -51,6 +51,47 @@ The first query is the "how many operators flipped the flag"
 adoption metric. The second is the activity metric — together they
 tell the story of a rollout.
 
+## 5. CA-400: 30-day rolling counters for queries and artifacts
+
+CA-400 (Phase 2) added two new keys to the `counts` blob:
+
+- `queries_30d` — rolling 30-day count of QA invocations
+  (`Orchestrator.Ask`). Process-local; resets on agent restart.
+- `artifacts_generated_30d` — rolling 30-day count of knowledge
+  artifacts (cliff notes, architecture diagram, learning path, code
+  tour, workflow story) that completed user-requested generation.
+  Excludes seed/deepening paths. Process-local; resets on agent restart.
+
+**Important**: `pings` is a latest-per-install snapshot table. The
+`counts` values on each row reflect the process-local state at the
+moment of that ping. Use a freshness gate (`last_seen > -48 hours`)
+when summing across installs — a 30-day window on `last_seen` would
+incorrectly aggregate 0–59 days of activity per the CA-400 Decision 6
+rationale.
+
+```sql
+-- Total queries (30d ring) across currently-active installs
+-- "Active" = pinged within the last 48 hours (2× the 24h default cadence)
+SELECT COALESCE(
+    SUM(CAST(json_extract(counts, '$.queries_30d') AS INTEGER)), 0
+) AS total_queries_30d
+FROM pings
+WHERE is_test = 0
+  AND last_seen > datetime('now', '-48 hours');
+
+-- Total artifacts generated (30d ring) across currently-active installs
+SELECT COALESCE(
+    SUM(CAST(json_extract(counts, '$.artifacts_generated_30d') AS INTEGER)), 0
+) AS total_artifacts_generated_30d
+FROM pings
+WHERE is_test = 0
+  AND last_seen > datetime('now', '-48 hours');
+```
+
+Installs that have not yet sent the new keys will produce NULL from
+`json_extract`; `COALESCE(..., 0)` handles this gracefully so the
+aggregate is never NULL.
+
 ## 5. `README.md` — document the new keys
 
 Append to whatever section enumerates counts:

internal/api/graphql/knowledge_generation_architecture_diagram.go

@@ -227,7 +227,7 @@ func (s architectureDiagramGenerationService) runGenerationPipeline(
 			return err
 		}
 	}
-	if err := r.Deps.KnowledgeStore.UpdateKnowledgeArtifactStatus(runCtx, artifact.ID, knowledgepkg.StatusReady); err != nil {
+	if err := r.markArtifactReady(runCtx, artifact.ID); err != nil {
 		return err
 	}
 	rt.ReportProgress(1.0, "ready", "AI architecture diagram ready", 0)

internal/api/graphql/knowledge_generation_cliff_notes.go

@@ -432,7 +432,7 @@ func (s cliffNotesGenerationService) runGenerationPipeline(
 		}
 	}
 
-	if err := r.Deps.KnowledgeStore.UpdateKnowledgeArtifactStatus(runCtx, artifact.ID, knowledgepkg.StatusReady); err != nil {
+	if err := r.markArtifactReady(runCtx, artifact.ID); err != nil {
 		slog.Error("failed to mark cliff notes ready", "artifact_id", artifact.ID, "error", err)
 	}
 	if artifactUsesUnderstanding(generationMode) && depth != string(knowledgepkg.DepthSummary) {

internal/api/graphql/knowledge_generation_shared.go

@@ -11,6 +11,7 @@ import (
 	graphstore "github.com/sourcebridge/sourcebridge/internal/graph"
 	knowledgepkg "github.com/sourcebridge/sourcebridge/internal/knowledge"
 	"github.com/sourcebridge/sourcebridge/internal/llm"
+	"github.com/sourcebridge/sourcebridge/internal/usage"
 	"github.com/sourcebridge/sourcebridge/internal/worker"
 )
 
@@ -168,10 +169,27 @@ func runKnowledgePipeline(
 		}
 	}
 
-	if err := r.Deps.KnowledgeStore.UpdateKnowledgeArtifactStatus(runCtx, artifact.ID, knowledgepkg.StatusReady); err != nil {
+	if err := r.markArtifactReady(runCtx, artifact.ID); err != nil {
 		slog.Error("failed to mark "+cfg.artifactLabel+" ready", "artifact_id", artifact.ID, "error", err)
 	}
 	rt.ReportProgress(1.0, "ready", cfg.readyMessage, 0)
 	slog.Info(cfg.artifactLabel+" generation complete", "artifact_id", artifact.ID)
 	return nil
 }
+
+// markArtifactReady transitions an artifact from GENERATING to READY and,
+// on success, increments the rolling 30-day artifacts-generated counter for
+// telemetry. It is the single instrumentation point for user-requested
+// artifact generation.
+//
+// The SupersedeArtifact paths (knowledge_seed.go and cliff-note deepening in
+// knowledge_support.go) are intentionally NOT routed through this wrapper —
+// they represent seed/refresh operations, not new user-requested generation.
+// See Decision 2 in the CA-400 plan for the full rationale.
+func (r *Resolver) markArtifactReady(ctx context.Context, artifactID string) error {
+	if err := r.Deps.KnowledgeStore.UpdateKnowledgeArtifactStatus(ctx, artifactID, knowledgepkg.StatusReady); err != nil {
+		return err
+	}
+	usage.ArtifactsCounter.Inc()
+	return nil
+}

internal/api/graphql/mark_artifact_ready_test.go

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 SourceBridge Contributors
+
+package graphql
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sourcebridge/sourcebridge/internal/appdeps"
+	knowledgepkg "github.com/sourcebridge/sourcebridge/internal/knowledge"
+	"github.com/sourcebridge/sourcebridge/internal/usage"
+)
+
+// TestMarkArtifactReady_IncrementsCounter verifies that a successful call to
+// markArtifactReady increments ArtifactsCounter by exactly 1, and that a
+// failed call (store returns an error for an unknown ID) does NOT increment
+// the counter.
+func TestMarkArtifactReady_IncrementsCounter(t *testing.T) {
+	t.Cleanup(usage.ResetCountersForTest)
+
+	mem := knowledgepkg.NewMemStore()
+	r := &Resolver{Deps: &appdeps.AppDeps{KnowledgeStore: mem}}
+
+	// Seed an artifact so UpdateKnowledgeArtifactStatus has something to update.
+	artifact := &knowledgepkg.Artifact{
+		ID:     "art-001",
+		Status: knowledgepkg.StatusGenerating,
+	}
+	if _, err := mem.StoreKnowledgeArtifact(context.Background(), artifact); err != nil {
+		t.Fatalf("StoreKnowledgeArtifact: %v", err)
+	}
+
+	// Happy path: markArtifactReady should succeed and increment the counter.
+	if err := r.markArtifactReady(context.Background(), artifact.ID); err != nil {
+		t.Fatalf("markArtifactReady: unexpected error: %v", err)
+	}
+	if got := usage.ArtifactsCounter.Total(); got != 1 {
+		t.Fatalf("after success: expected ArtifactsCounter.Total() == 1, got %d", got)
+	}
+
+	// Verify the artifact is actually in READY state.
+	stored := mem.GetKnowledgeArtifact(context.Background(), artifact.ID)
+	if stored == nil {
+		t.Fatal("GetKnowledgeArtifact: returned nil after markArtifactReady")
+	}
+	if stored.Status != knowledgepkg.StatusReady {
+		t.Fatalf("artifact status: expected %q, got %q", knowledgepkg.StatusReady, stored.Status)
+	}
+
+	// Failure path: a non-existent artifact ID should return an error and
+	// must NOT increment the counter.
+	if err := r.markArtifactReady(context.Background(), "does-not-exist"); err == nil {
+		t.Fatal("markArtifactReady on unknown ID: expected error, got nil")
+	}
+	if got := usage.ArtifactsCounter.Total(); got != 1 {
+		t.Fatalf("after failure: expected ArtifactsCounter.Total() == 1 (unchanged), got %d", got)
+	}
+}

internal/qa/pipeline.go

@@ -15,6 +15,7 @@ import (
 	commonv1 "github.com/sourcebridge/sourcebridge/gen/go/common/v1"
 	reasoningv1 "github.com/sourcebridge/sourcebridge/gen/go/reasoning/v1"
 	"github.com/sourcebridge/sourcebridge/internal/llm/resolution"
+	"github.com/sourcebridge/sourcebridge/internal/usage"
 	"github.com/sourcebridge/sourcebridge/internal/worker"
 )
 
@@ -405,6 +406,7 @@ func (o *Orchestrator) Ask(ctx context.Context, in AskInput) (*AskResult, error)
 	// error path). Counter is process-local and read by the dashboard
 	// ping at most once per 24h.
 	CountAsk()
+	usage.QueriesCounter.Inc()
 
 	started := time.Now()
 	result := &AskResult{