Address capture review documentation

Author: jspahn80134

server/scripts/capture_events_schema.sql

@@ -153,10 +153,13 @@ CREATE INDEX IF NOT EXISTS events_data_gin_idx
 
 COMMENT ON TABLE public.events IS
     'CodeChat dissertation capture events. Course, group, assignment, condition, and task context are joined during analysis from participant/date mappings.';
+COMMENT ON COLUMN public.events.event_id IS 'Opaque stable per-event ID for correlation and future deduplication; not used for event ordering.';
+COMMENT ON COLUMN public.events.sequence_number IS 'Client-local event order within one VS Code extension session, useful for ordering and detecting gaps.';
 COMMENT ON COLUMN public.events.user_id IS 'Pseudonymous participant UUID generated or supplied by the VS Code extension.';
 COMMENT ON COLUMN public.events.session_id IS 'Capture session UUID emitted by the VS Code extension.';
 COMMENT ON COLUMN public.events.file_hash IS 'SHA-256 hash of the local file path; raw local paths are not stored.';
 COMMENT ON COLUMN public.events."timestamp" IS 'Server receive/record timestamp in UTC.';
+COMMENT ON COLUMN public.events.client_tz_offset_min IS 'Client timezone offset in minutes, used with timestamp to derive local time of day without storing location or full timezone name.';
 COMMENT ON COLUMN public.events.data IS 'Event-specific JSON payload. Known telemetry metadata lives in typed columns.';
 
 -- Least-privilege deployment guidance:
@@ -165,11 +168,13 @@ COMMENT ON COLUMN public.events.data IS 'Event-specific JSON payload. Known tele
 -- password/database/user names, a database administrator can grant only the
 -- permissions needed for capture inserts:
 --
+-- ```sql
 -- CREATE ROLE codechat_capture_writer LOGIN PASSWORD 'replace-with-secret';
 -- GRANT CONNECT ON DATABASE codechat_capture TO codechat_capture_writer;
 -- GRANT USAGE ON SCHEMA public TO codechat_capture_writer;
 -- GRANT INSERT ON public.events TO codechat_capture_writer;
 -- GRANT USAGE ON SEQUENCE public.events_id_seq TO codechat_capture_writer;
+-- ```
 --
 -- Do not grant SELECT, UPDATE, DELETE, CREATE, or ownership privileges to the
 -- writer account used in `capture_config.json`.

server/src/capture.rs

@@ -47,11 +47,17 @@
 // * `user_id` – pseudonymous participant UUID. Course, group, assignment, and
 //   study condition are intentionally joined later from researcher-managed
 //   participant/date mappings instead of being configured by students.
-// * `session_id`, `event_id`, `sequence_number`, `schema_version` – event
-//   integrity and versioning metadata.
+// * `event_id` – opaque stable per-event ID for correlation and future
+//   deduplication across capture transports or retries.
+// * `sequence_number` – ordered, session-local event counter for reconstructing
+//   event order and detecting gaps.
+// * `session_id`, `schema_version` – session grouping and payload versioning
+//   metadata.
 // * `file_hash` – privacy-preserving SHA-256 hash of the local file path.
 // * `event_type` – coarse event type (see `CaptureEventType` below).
 // * `timestamp` – server receive/record timestamp (in UTC).
+// * `client_tz_offset_min` – browser/VS Code timezone offset used to derive
+//   local time-of-day without storing location or full timezone identity.
 // * `data` – JSONB payload with event-specific details.
 
 use std::{
@@ -396,8 +402,16 @@ impl CaptureStatus {
 #[derive(Debug, Clone)]
 pub struct CaptureEvent {
     /// Globally unique event identifier, generated by the client or server.
+    ///
+    /// This is an opaque stable ID for correlation and possible future
+    /// deduplication. It is not ordered; use `sequence_number` for event order
+    /// within one extension session.
     pub event_id: Option<String>,
     /// Client-local event order for one extension session.
+    ///
+    /// This is intentionally ordered so analysis can reconstruct event order and
+    /// detect missing events. It is not globally unique; use `event_id` for
+    /// stable event identity.
     pub sequence_number: Option<i64>,
     /// Capture payload schema version.
     pub schema_version: Option<i32>,
@@ -416,8 +430,29 @@ pub struct CaptureEvent {
     /// Server receive/record timestamp, in UTC.
     pub timestamp: DateTime<Utc>,
     /// Client timezone offset in minutes.
+    ///
+    /// Combined with the server UTC timestamp, this supports local time-of-day
+    /// analysis without collecting student location or a full timezone name.
     pub client_tz_offset_min: Option<i32>,
-    /// Event-specific payload, stored as JSON text in the DB.
+    /// Event-specific payload, stored as JSONB in the DB.
+    ///
+    /// Known keys include:
+    ///
+    /// * Capture/settings control: `capture_active`, `capture_control_only`,
+    ///   `changed_by`, `changed_settings`, previous/new consent and recording
+    ///   booleans.
+    /// * Activity/session summaries: `mode`, `closed_by`, `duration_ms`,
+    ///   `duration_seconds`, `from`, `to`.
+    /// * Save/run/compile metadata: `reason`, `lineCount`, `sessionName`,
+    ///   `sessionType`, `taskName`, `taskSource`, `processId`, `exitCode`.
+    /// * Write classification: `source`, `classification_basis`, `diff`,
+    ///   `doc_block_diff`, `doc_block_count_before`, `doc_block_count_after`,
+    ///   `block_kind`, `basis`, `confidence`, `size_band`.
+    /// * Paste evidence: `operation`, `pending_code_paste`.
+    ///
+    /// Future keys should be documented here, tied to an analysis question, and
+    /// privacy-reviewed before capture. Do not store raw source text or raw
+    /// local file paths in this payload.
     pub data: serde_json::Value,
 }
 

server/src/translation.rs

@@ -510,10 +510,6 @@ impl CaptureContext {
             {
                 self.active = active;
             }
-            // Support older wire payloads that stored the session in `data`.
-            if let Some(session_id) = data.get("session_id").and_then(serde_json::Value::as_str) {
-                self.session_id = Some(session_id.to_string());
-            }
             if wire.event_type == CaptureEventType::CodePaste
                 && data
                     .get("pending_code_paste")
@@ -1922,7 +1918,7 @@ mod tests {
             sequence_number: None,
             schema_version: Some(2),
             user_id: "participant".to_string(),
-            session_id: None,
+            session_id: Some("session".to_string()),
             event_source: Some("vscode_extension".to_string()),
             language_id: None,
             file_hash: None,
@@ -1945,7 +1941,6 @@ mod tests {
         context.update_from_wire(&capture_wire(
             CaptureEventType::SessionStart,
             serde_json::json!({
-                "session_id": "session",
                 "capture_active": true,
             }),
         ));

server/src/webserver.rs

@@ -437,10 +437,14 @@ pub struct Credentials {
 #[derive(Debug, Serialize, Deserialize, PartialEq, TS)]
 #[ts(export, optional_fields)]
 pub struct CaptureEventWire {
-    /// Client-generated unique event identifier.
+    /// Client-generated unique event identifier. Unlike `sequence_number`, this
+    /// is an opaque stable ID for correlation and possible future deduplication
+    /// across capture transports or retries.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub event_id: Option<String>,
-    /// Client-local event order for one extension session.
+    /// Client-local event order for one extension session. Unlike `event_id`,
+    /// this is intentionally ordered so analysis can reconstruct event order and
+    /// detect gaps within a session.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub sequence_number: Option<i64>,
     /// Capture payload schema version.
@@ -465,10 +469,21 @@ pub struct CaptureEventWire {
     pub event_type: CaptureEventType,
 
     /// Optional client timezone offset in minutes (JS Date().getTimezoneOffset()).
+    /// Combined with the server UTC timestamp, this allows local time-of-day
+    /// analysis without storing the student's location or full timezone name.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub client_tz_offset_min: Option<i32>,
 
-    /// Arbitrary event-specific data stored as JSON (optional).
+    /// Event-specific data stored as JSON. Known keys include capture controls
+    /// (`capture_active`, `capture_control_only`), activity/session details
+    /// (`mode`, `closed_by`, `duration_ms`, `duration_seconds`, `from`, `to`),
+    /// tool/run/build details (`reason`, `lineCount`, `sessionName`,
+    /// `sessionType`, `taskName`, `taskSource`, `processId`, `exitCode`), write
+    /// classification details (`source`, `classification_basis`, `diff`,
+    /// `doc_block_diff`, `block_kind`, `basis`, `confidence`, `size_band`), and
+    /// paste markers (`operation`, `pending_code_paste`). Add future keys only
+    /// when they support a specific analysis question and do not store source
+    /// text or raw local paths.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[ts(type = "unknown")]
     pub data: Option<serde_json::Value>,