Create a machine-readable collector and event-schema registry

[JacobLinCool]

Summary

Create one language-neutral, machine-readable catalog for collector configuration and event schemas.

The catalog is the authoritative metadata source for Android, Web authoring, Python analysis, future Swift support, documentation, and the event-rule builder. It is not a runtime plugin mechanism: clients only run collectors compiled into their build and reject unknown required collectors.

Requirements

Canonical catalog

• Define the catalog in canonical JSON with a checked-in schema and deterministic ordering.
• For every collector identity, define:
  • stable collector ID and payload/schema identity;
  • configuration fields, types, bounds, defaults, and physical units;
  • payload types and typed event fields;
  • nullability/optionality, enums, units, precision, and semantic descriptions;
  • wall, continuous-monotonic, boot-session, or source-clock basis;
  • required Android access/permissions and participant disclosure;
  • privacy classification and prohibited inferences;
  • Android/iOS availability and minimum platform constraints;
  • event-rate, encoded-event-size, daily-volume, and configuration bounds.
• Include lifecycle and intervention event schemas used by rules and analysis where they are valid inputs.
• Treat any change in field meaning, unit, precision, clock basis, or interpretation as a new collector or payload schema identity. Do not silently mutate semantics in place.

Generated and verified consumers

• Generate Kotlin, TypeScript, Python, and later Swift schema artifacts from the catalog, or prove their complete semantic equivalence in CI.
• Drive Web editor controls, validation, consent/disclosure summaries, the data dictionary, Parquet decoding, and Add a declarative cross-collector event rule engine #4's allowed rule fields/operators from the same metadata.
• Generate a platform capability/parity matrix from catalog data.
• Give every consumer a deterministic catalog digest/version and fail CI when generated artifacts are stale.
• Preserve Protocol v1 canonicalization requirements; generated defaults or display strings must not introduce alternate wire encodings.

Closed-world runtime model

• Keep collector implementations compiled and explicitly registered in each client.
• Reject unknown required collectors during configuration import/enrollment.
• Do not add dynamic code loading, reflection-based plugins, downloaded schemas that change runtime capability, or a generic “unknown payload” execution path.
• An optional unsupported collector may be represented only if Protocol v1 explicitly defines that behavior; it must never be silently substituted with another collector.

Acceptance criteria

• A single catalog change deterministically updates or invalidates all Kotlin, TypeScript, Python, documentation, and fixture consumers.
• Web field choices and Add a declarative cross-collector event rule engine #4 operators cannot reference a field/type/unit absent from the catalog.
• Python/Parquet decoding uses declared schemas and never infers types from observed strings.
• CI detects stale generated files, duplicate identities, semantic-breaking in-place edits, invalid bounds, inconsistent platform availability, and mismatched units.
• A configuration naming an unknown required collector fails before consent or study storage is created.
• The catalog cannot cause a client to load or execute code not present in the application build.
• Existing collectors and lifecycle events are fully represented before the registry becomes the source of truth.

Documentation

Document the catalog format, identity/versioning rules, generator workflow, collector implementation guide, platform parity matrix, data dictionary generation, and rule/analysis integration.

Dependencies

Blocked by #8, which defines Protocol v1 canonical JSON, integer encoding, platform targeting, and unknown-field behavior.