refactor: agentic comment cleanup

go/cmd/particleprocessorworker/main.go

@@ -38,13 +38,9 @@ func createClient(ctx context.Context) *firestore.Client {
 	return client
 }
 
-// The purpose of the particle processor worker is to listen for new particles
-// across all streams and perform side effects such as
-//   - generate transcript if the particle is of type media
-//   - send mobile notifications if a client is offline
-//   - update the parent stream's `last_child_created_at`
-//   - generate vector embedding
-//   - synthesize and decide whether ai should generate a particle as a response
+// Listens for new particles and runs per-particle side effects: transcripts,
+// transcode, parent stream's last_child_created_at, freemium usage, and push
+// notifications for offline recipients.
 func main() {
 	ctx := context.Background()
 
@@ -80,9 +76,8 @@ func main() {
 	humanSvc := human.NewService(db.Pool())
 	networkReader := network.NewReader(db.Pool())
 	pushTokenSvc := pushnotify.NewService(db.Pool())
-	// EXPO_ACCESS_TOKEN is required: with Enhanced Security enabled on the Expo
-	// project, sends without it fail; without it, anyone holding one of our
-	// push tokens could spam our users via the public Expo endpoint.
+	// EXPO_ACCESS_TOKEN is required: Enhanced Security is on for our Expo
+	// project (otherwise anyone holding one of our push tokens could spam users).
 	expoClient := pushnotify.NewExpoClient(utils.MustGetEnv("EXPO_ACCESS_TOKEN"))
 	notifier := pushnotify.NewNotifier(networkReader, pushTokenSvc, pusherClient, expoClient)
 
@@ -127,8 +122,8 @@ func main() {
 
 			slog.Debug("processing particle", "particleID", particleID, "data", change.Doc.Data())
 
-			// --- Perform side effects ---
-			// All of them do not stop us from marking the particle as processed.
+			// Side effects below are best-effort — failures don't prevent
+			// marking the particle as processed.
 			parentDoc := loadParentParticle(ctx, change.Doc)
 			updateParentLastChildCreatedAt(ctx, change.Doc, parentDoc)
 			transcript := transcribeMediaParticle(ctx, depotSvc, speechSvc, change.Doc)
@@ -143,9 +138,8 @@ func main() {
 	}
 }
 
-// transcribeMediaParticle transcribes a media particle, writes the structured
-// transcript to Firestore, and returns the raw transcript text. Returns "" for
-// non-media particles or on any error (errors are logged internally).
+// Writes the structured transcript to Firestore and returns the raw text;
+// returns "" for non-media particles or on any error (logged internally).
 func transcribeMediaParticle(ctx context.Context, depotSvc depot.Service, speechSvc speech.SpeechService, doc *firestore.DocumentSnapshot) string {
 	var mediaParticle particle.FirestoreMediaParticle
 	err := doc.DataTo(&mediaParticle)
@@ -227,10 +221,9 @@ func toFirestoreTranscript(result *speech.TranscriptResult) particle.FirestoreTr
 	}
 }
 
-// recordFreemiumUsage bumps the network's daily message counter for non-container
-// particles. Idempotent via the surrounding processed_particles guard: the worker
-// only reaches this path on first-seen particles, so a crash/restart won't
-// double-count.
+// Bumps the network's daily message counter for non-container particles.
+// The surrounding processed_particles guard keeps this idempotent across
+// crashes/restarts.
 func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *firestore.DocumentSnapshot) {
 	rawType, err := doc.DataAt("type")
 	if err != nil {
@@ -247,7 +240,7 @@ func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *f
 		slog.Error("invalid particle type", "error", err, "particleID", doc.Ref.ID)
 		return
 	}
-	// Containers (stream/folder) don't count as "messages" for the daily cap.
+	// Containers don't count toward the daily message cap.
 	if particleType == particle.TypeStream || particleType == particle.TypeFolder {
 		return
 	}
@@ -263,8 +256,7 @@ func recordFreemiumUsage(ctx context.Context, billingSvc billing.Service, doc *f
 	}
 }
 
-// loadParentParticle fetches the immediate parent particle doc for `doc`.
-// Returns nil (and logs) if the path doesn't have a parent or the read fails.
+// Returns nil (and logs) if the path has no parent or the read fails.
 func loadParentParticle(ctx context.Context, doc *firestore.DocumentSnapshot) *firestore.DocumentSnapshot {
 	parentChildrenCollectionRef := doc.Ref.Parent
 	if parentChildrenCollectionRef == nil {
@@ -283,9 +275,8 @@ func loadParentParticle(ctx context.Context, doc *firestore.DocumentSnapshot) *f
 	return parentParticleDoc
 }
 
-// updateParentLastChildCreatedAt updates the parent stream's last_child_created_at
-// to the child's actual created_at timestamp, so it stays directly comparable with
-// playback markers (which also store child created_at values).
+// Sets last_child_created_at to the child's created_at so it stays directly
+// comparable with playback markers (which also store child created_at values).
 func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.DocumentSnapshot, parent *firestore.DocumentSnapshot) {
 	if parent == nil {
 		return
@@ -307,7 +298,6 @@ func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.Document
 		return
 	}
 
-	// Read the child's created_at — this is the same value that playback markers store
 	childCreatedAt, err := doc.DataAt("created_at")
 	if err != nil {
 		slog.Error("failed to read child created_at", "error", err, "particleID", doc.Ref.ID)
@@ -325,10 +315,9 @@ func updateParentLastChildCreatedAt(ctx context.Context, doc *firestore.Document
 	}
 }
 
-// notifyForParticle dispatches a push notification for a newly-created particle.
-// Skips containers (streams/folders) and particles whose parent isn't a stream
-// (notifications are only sent for stream messages today). The transcript arg
-// is used as the preview body for media particles when available.
+// Skips containers and particles whose parent isn't a stream — notifications
+// are scoped to stream messages today. The transcript arg becomes the preview
+// body for media particles when available.
 func notifyForParticle(
 	ctx context.Context,
 	notifier *pushnotify.Notifier,
@@ -405,11 +394,8 @@ func notifyForParticle(
 	}
 }
 
-// previewForParticle builds the visible notification body. Kept short — push
-// previews truncate aggressively on lockscreens. For media, prefers the
-// transcript text (already computed by transcribeMediaParticle in the same
-// processing step) and falls back to the generic "Sent a ..." line if speech
-// recognition produced nothing.
+// Builds the notification body. Kept short — lockscreens truncate aggressively.
+// Media prefers transcript text and falls back to a generic "Sent a …" line.
 func previewForParticle(pType particle.ParticleType, doc *firestore.DocumentSnapshot, transcript string) string {
 	switch pType {
 	case particle.TypeText: