Error Reporting Spec — v0.1

Normative spec derived from docs/rfcs/RFC-001-error-reporting-framework.md. Implementação: foundation/reporter + engines/sdk/koder_kit (KoderErrorReporter).

---

Scope

Applies to all Koder modules on all platforms: Flutter mobile, Flutter desktop, TV (JS/React), web apps, Go backend services, and any future SDK binding.

---

1 — MUST: expose "Report a problem" in Settings

Every module that has a user-facing Settings screen must expose a "Report a problem" / "Reportar um problema" action. This action opens the manual report flow provided by KoderReportButton from engines/sdk/koder_kit.

This button is always visible, regardless of any other error reporting toggle.

---

2 — MUST: expose "Automatic error reporting" toggle in Settings

Every user-facing module must expose an "Automatic error reporting" / "Relatório automático de erros" toggle.

Default OFF: the toggle must be inactive by default on every fresh install. The absence of a stored preference means disabled:

// Dart / Flutter
final enabled = prefs.getBool('error_reporting') ?? false;  // absent == OFF

// Go services — operator-controlled, not user-controlled
enabled := os.Getenv("KODER_ERROR_REPORTING") == "true"

// Web / TV
const enabled = localStorage.getItem('error_reporting') === 'true';

The toggle lives in Settings → Privacy → Error Reporting.

---

3 — MUST: expose granular child toggles when auto-report is ON

When auto-report is enabled, two additional opt-in toggles MUST be shown (both default OFF):

• "Include navigation history" — enables Group E (breadcrumbs).
• "Include device state" — enables Group F (memory, battery, storage).

final breadcrumbs = prefs.getBool('error_reporting_breadcrumbs') ?? false;
final deviceState = prefs.getBool('error_reporting_device_state') ?? false;

Child toggles are hidden when the parent toggle is OFF.

---

4 — MUST: use engines/sdk/koder_kit — never implement locally

Before implementing any error reporting logic, check engines/sdk/koder_kit for KoderErrorReporter and KoderReportButton. All modules use these; no module reimplements capture, sanitization, or submission logic locally.

---

5 — MUST: submit only to foundation/reporter

All reports go to https://reporter.koder.dev/api/v1/reports. No module submits error data to any other endpoint.

---

6 — Data groups and capture policy

Always captured (Groups A–D)

No user consent required beyond accepting the app's privacy policy.

Group	Content
A — Report identity	report_id, reported_at, occurred_at, report_type
B — Module identity	app_slug, app_version, build_number, distribution_channel, build_type
C — Platform	platform, os_version, device_class, device_model_hash, architecture, locale, timezone_offset
D — Error context	error_id, error_category, severity, stack_trace (sanitized), error_message_raw, is_fatal, recurrence_in_session, fingerprint

Opt-in (Groups E–F)

Requires the corresponding child toggle to be ON.

Group	Content	Toggle key
E — Breadcrumbs	current_route, breadcrumbs, last_action, app_uptime_seconds	error_reporting_breadcrumbs
F — Device state	network_state, memory_available_mb, storage_available_mb, battery_level, battery_charging, app_in_foreground	error_reporting_device_state

Manual only (Group G)

Never sent automatically. Only via explicit user action in the report dialog.

Field	Consent required
user_description	Implicit (user typed and tapped Send)
user_contact_email	Explicit (user filled in optional field)
screenshot_data	Explicit (separate "Attach screenshot" tap + consent dialog)

---

7 — Privacy: what is NEVER captured

The following are unconditionally prohibited. The SDK enforces this; foundation/reporter applies a second PII scrub as a defense-in-depth layer.

Category	Examples
User identity data	Names, emails, phone numbers, CPF, RG
User-generated content	Audio recordings, video, documents, messages, transcriptions
Input events	Keyboard events, key sequences, clipboard contents
Session replay	Screen recordings, video of UI, gesture sequences
Media device access	Microphone, camera — the reporter SDK has no API access to these
Contact/calendar data	Address book, calendar entries, call history
Real device identifiers	IMEI, Android ID, IDFA, serial number
Raw IP addresses	Discarded server-side after GeoIP resolution
Absolute paths with usernames	Sanitized to relative paths before transmission
Tokens and credentials	Scrubbed by regex before transmission

---

8 — Stack trace sanitization (mandatory)

Applied by the SDK before serialization:

1. Absolute paths → relative: /home/username/... → koder/...
2. Query parameters stripped from any URL in the trace.
3. Regex redaction: email addresses, phone numbers, long UUIDs in user-visible positions.
4. Local variable values are NOT included unless the module explicitly enables variable capture (requires a separate spec amendment).

---

9 — Backend services (kdb, koder-jet, koder-id, etc.)

Groups A, B, C (minus mobile-specific fields), and D apply. Groups E/F are replaced by:

Field	Description
request_id	Trace ID of the request that failed
operation	HTTP method + path template
http_status	Integer
upstream_dependency	Service name that caused the failure
retry_count	Integer
response_time_ms	Integer

The toggle for backend services is an env var / koder.toml entry, not a user-facing UI toggle. Default is OFF. The operator (not the user) decides.

---

10 — Deterministic audit checks

/k-housekeep verifies per module:

1. Settings screen contains a widget/key referencing error_reporting preference.
2. prefs.getBool('error_reporting') ?? false (or equivalent absent-means-off pattern) is the sole read point — no hard-coded true default.
3. KoderReportButton is present in Settings regardless of the auto-report toggle state.
4. No module captures keyboard events, screen content, media device streams, or raw device identifiers.
5. All report submissions target https://reporter.koder.dev/api/v1.

---

File: meta/docs/stack/specs/errors/reporting.kmd

Trigger: read this spec before implementing error reporting, the "Report a problem" button, auto-report toggles, or any data capture related to errors in any Koder module.