Spec: Runtime Adoption Telemetry

User Input

IP-105 outcome: project-level adoption telemetry through apps/api, not OTel dashboards alone. Primary adoption view belongs to apps/backoffice under M4.5; this milestone must preserve that boundary and coordinate with IP-138/IP-139/IP-140/IP-142.

V1 product stats track happy-path value events only:

• cli.auth.login.completed
• cli.artifact.pull.completed
• cli.scaffold.setup.completed
• cli.scaffold.update.applied
• cli.harness.report.submitted

ProjectUsage is the adoption/reporting aggregate and maps 1:n to observed repositories. Better Auth bearer/device authorization is the canonical operator identity flow; git identity is metadata/fallback. Developer/operator identity is audit/contact context, not a KPI.

Initial Situation

The API has authenticated baseline metadata endpoints. The database currently contains Better Auth tables only. The CLI has clear moments where value events happen, but no product telemetry contract, emitter, ingestion endpoint, persistence schema, idempotency/noise filtering, or docs-backed operator contract.

Issue

Without a product telemetry foundation, adoption decisions would either rely on OTel/debug data or speculative backoffice UI work. That would blur product usage, system observability, and individual developer tracking.

Solution

Add a typed telemetry ingestion foundation across packages/contract, apps/api, packages/db, and apps/cli. The CLI observes safe facts and emits best-effort events only after successful happy-path work. The API validates, filters, and persists product events under ProjectUsage, ObservedRepository, and CliUsageEvent concepts. Backoffice presentation remains M4.5.

Child Coverage

Non-Goals

• Backoffice dashboards or ranking UI.
• Developer scorecards, comparisons, or KPIs.
• OTel replacement.
• Product stats for setup started, baseline resolved, update checked, failures, retries, background tool checks, or debug traces.
• Perfect project-to-repository mapping in the CLI.

Acceptance Criteria

• packages/contract exposes a typed telemetry ingestion API and schemas for the five approved event names.
• Telemetry payloads include timestamp, CLI version, safe source/environment flags, optional baseline/channel/version, observed repository facts, optional authenticated operator identity, and git identity only as metadata/fallback.
• packages/db defines product telemetry persistence tables for project_usage, observed_repository, and cli_usage_event, plus explicit migration status.
• apps/api validates and persists telemetry through Effect services/layers and rejects or filters noisy/non-approved product events.
• CLI emits events best-effort after successful auth login, control-plane artifact pull, scaffold setup, update apply, and harness report submission.
• Telemetry failures do not break successful local CLI operations.
• Localhost/dev, CI/publish validation, debug reads, retries/cache misses, and duplicate submissions do not inflate adoption stats.
• Docs preserve the M4.5 boundary: backoffice owns primary adoption view later.

Constraints

• apps/api is the authenticated control plane and persistence owner.
• CLI observes facts; API/backoffice aggregate into ProjectUsage.
• Better Auth operator identity is canonical when available.
• Git remotes and git identity require sanitization and must not leak credentials.
• Effect backend changes must use typed errors, visible requirements, layers, and @effect/vitest.

Technical Notes

• Current API contract only has health and baseline groups.
• Current DB schema only has Better Auth tables.
• Current local static token auth maps to cli-operator.
• M4 may store operatorId as the authenticated actor supplied by current auth.

Validation Plan

• Contract schema/API tests for accepted/rejected telemetry events.
• API tests for auth, happy-path persistence, duplicate/noise filtering, and non-approved event rejection.
• CLI tests for best-effort emission after successful commands and no emission on failed/no-op operations.
• git diff --check, bun run check, bun run check-types, targeted tests, and full test if feasible.

Decision Log

Open Questions