Implement ADR-010 (Reporting as an Admin Operation) + ADR-011 (Telemetry & Usage Tracking)

[seanspeaks]

Tracking issue for implementing the two accepted ADRs merged in #612:

• docs/architecture-decisions/010-reporting-as-admin-operation.md
• docs/architecture-decisions/011-integration-telemetry-and-usage-tracking.md

These are decisions, not code. This issue breaks them into phased implementation work. ADR-010 delivers value on today's structural generics before the larger ADR-011 lift; ADR-011 only gates the usage columns and trend snapshots.

---

Phase 1 — Reporting on the admin-operation runner (ADR-010 core)

Highest value, no new external dependencies.

• ReportBase mirroring AdminScriptBase; reports: [] registration in the app definition (core built-ins + adopter-defined).
• Report registry + discovery (GET /api/v2/reports lists registered reports, not a hardcoded array).
• Run reports through the ADR-005 runner (admin auth, sync/async) rather than the standalone router.
• Isolated admin execution store — separate table or scope:'admin' discriminator; repository-level guarantee that user-context queries never return admin records and vice versa. Extends ScriptExecutionRepository, not the integration-scoped Process model. (Open decision: separate table vs discriminator.)
• Port feat(reporting): read-only integrations reporting API in core #607's integrations report to be the first built-in report definition.
• Add the cross-integration usage-comparison built-in — structural columns only for now (status/type/module/error/mapping counts, timestamps), which run on existing generics.

Phase 2 — Run modes & persistence (ADR-010)

• live / recorded / snapshot run modes; mode selects the persistence path.
• Snapshot series (retained point-in-time results) → trend reads.
• Artifact storage for non-JSON output (object storage + signed URLs + previous-runs listing), derived from the FreshBooks-frigg pattern.
• Timeout-aware requeue for deployment-wide scans (getRemainingTimeInMillis → resume next step) so heavy reports leave the request path.

Phase 3 — Telemetry & feature-usage tracking (ADR-011)

Unblocks the usage columns + trends.

• OTel-based TelemetryService abstraction; exporter config in app definition; no-op default.
• Free auto-instrumentation at framework seams (instantiation identifiers; USER_ACTION/CRON/QUEUE/WEBHOOK handlers; api-module requests; queues/webhooks/sync).
• Dev-defined custom metrics via the same abstraction.
• Usage-counter contract: canonical registry + per-integration Definition.usage declaration; single emission path. (Open decision: strict vs advisory canonical registry.)
• Durable usage rollup store (own repository triad) + read contract (totals for comparison, series for trends); reports never query an external APM.
• Adopter North Star metric (derived-from-trace or directly emitted).
• Light up the usage-comparison report's usage columns + snapshot trends on the rollup.

---

Open design decisions to settle deliberately (not silently in a PR)

• Admin execution store: separate table vs scope discriminator.
• Canonical usage-counter registry: strict (reject unknown) vs advisory (blessed set).
• Whether integration data migrations (devtools Migrator) eventually ride the same runner (out of scope for ADR-010, revisit later).

Housekeeping

• Docs-only ADR PRs should skip release/prerelease labels (docs(adr): ADR-010 Reporting as an Admin Operation + ADR-011 Telemetry & Usage Tracking #612 cut v2.0.0-next.99 unnecessarily).

🤖 Generated with Claude Code