From aa35614840b05404f4476d424be5422a843c43ca Mon Sep 17 00:00:00 2001
From: null <koga.industries@gmail.com>
Date: Wed, 8 Jul 2026 23:25:34 -0500
Subject: [PATCH] =?UTF-8?q?docs(manual):=20batch=206=20review=20=E2=80=94?=
 =?UTF-8?q?=20handler=20types=20table=20was=20imprecise=20(mixed=20onCreat?=
 =?UTF-8?q?e/onWritten/onUpdate)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Cloud Functions Handler types table had a single row labelled
'Firestore onCreate / onDocumentWritten' that mixed three distinct
trigger types:
  - onDocumentCreated: onAnswerWritten, onMessageWritten,
    notifyOnDateMatch, onDateHistoryCreated, onDateReflectionWritten,
    onRestoreRequested
  - onDocumentUpdated: onCoupleLeave, onAnswerRevealed,
    onDateReflectionRevealed, onRestoreFulfilled
  - onDocumentWritten (fires on both create and update):
    onEntitlementChanged, onGameSessionUpdate, onThisOrThatPartFinished,
    onWheelPartFinished, onHowWellPartFinished, onDesireSyncPartFinished

The old row put onEntitlementChanged in a separate 'Firestore onUpdate'
row, but the source actually uses onDocumentWritten (which fires on
both create and update). Replaced the two rows with three precise
rows - one per trigger type - and listed the actual handler in each.

Also moved onUserDelete from the Firestore row to the new
'Auth onDelete' row (which was already there but unused) so each
handler appears in exactly one place.

Other Batch 6 claims verified clean:
- Every export name in the table (createInviteCallable,
  acceptInviteCallable, syncEntitlement, submitOutcomeCallable,
  leaveCoupleCallable, checkDeviceIntegrity,
  assignDailyQuestionCallable, wrapReleaseKeyCallable,
  sendGentleReminderCallable, sendThinkingOfYouCallable,
  assignDailyQuestion, scheduledOutcomesReminder,
  sendDailyQuestionProactiveReminder, sendReengagementReminder,
  sendStreakReminder, unlockDueMemoryCapsules,
  sendChallengeDayReminders, aggregateOutcomeStats) exists in the
  source and is re-exported from functions/src/index.ts.
- revenueCatWebhook is in source but its export is commented out in
  index.ts (the not-deployed note is correct).
---
 docs/Engineering_Reference_Manual.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/Engineering_Reference_Manual.md b/docs/Engineering_Reference_Manual.md
index de5fd320..ad673632 100644
--- a/docs/Engineering_Reference_Manual.md
+++ b/docs/Engineering_Reference_Manual.md
@@ -821,9 +821,10 @@ Every function module follows the same shape:
 | --- | --- | --- |
 | HTTPS onRequest | (none deployed) | The old `revenueCatWebhook` onRequest handler is in source but **not exported from `index.ts`** - see [Billing](#billing) for the enable steps. The unauthenticated `health` endpoint was removed in an earlier security review. |
 | HTTPS onCall | `createInviteCallable`, `acceptInviteCallable`, `syncEntitlement`, `submitOutcomeCallable`, `leaveCoupleCallable`, `checkDeviceIntegrity`, `assignDailyQuestionCallable`, `wrapReleaseKeyCallable`, `sendGentleReminderCallable`, `sendThinkingOfYouCallable` | Caller must be authenticated. Errors throw `HttpsError`. All v2 → `us-central1` via global `options.ts`. |
-| Firestore onCreate / onDocumentWritten | `onAnswerWritten`, `onAnswerRevealed`, `onMessageWritten`, `onCoupleLeave`, `onUserDelete` (v1), `onGameSessionUpdate`, `onThisOrThatPartFinished`, `onWheelPartFinished`, `onHowWellPartFinished`, `onDesireSyncPartFinished`, `notifyOnDateMatch` (under `createDateMatch.ts`), `onDateReflectionWritten`, `onDateReflectionRevealed`, `onDateHistoryCreated`, `onRestoreRequested`, `onRestoreFulfilled` | Event-driven; best-effort. `onUserDelete` is intentionally v1 (gen 2 has no `auth.user().onDelete`). |
-| Firestore onUpdate | `onEntitlementChanged` | Fires when `users/{uid}/entitlements/premium` changes; sends a partner-facing FCM when the user gains premium. It does NOT mirror premium state to the user root doc. |
-| Auth onDelete | `onUserDelete` | Auth user deletion cascade (v1). |
+| Firestore onDocumentCreated | `onAnswerWritten`, `onMessageWritten`, `notifyOnDateMatch` (under `createDateMatch.ts`), `onDateHistoryCreated`, `onDateReflectionWritten`, `onRestoreRequested` | Create-only; one delivery per new doc. |
+| Firestore onDocumentUpdated | `onCoupleLeave`, `onAnswerRevealed`, `onDateReflectionRevealed`, `onRestoreFulfilled` | Update-only; fires when the matched doc changes. |
+| Firestore onDocumentWritten (create+update) | `onEntitlementChanged`, `onGameSessionUpdate`, `onThisOrThatPartFinished`, `onWheelPartFinished`, `onHowWellPartFinished`, `onDesireSyncPartFinished` | Fires on both create and update; the handler distinguishes via `event.data.before`/`after` or by reading the doc state. |
+| Auth onDelete | `onUserDelete` (v1) | Auth user deletion cascade. Intentionally v1 (gen 2 has no `auth.user().onDelete`). |
 | Pub/Sub schedule | `assignDailyQuestion`, `scheduledOutcomesReminder`, `sendDailyQuestionProactiveReminder`, `sendReengagementReminder`, `sendStreakReminder`, `unlockDueMemoryCapsules`, `sendChallengeDayReminders`, `aggregateOutcomeStats` | Cron expression; timezone is `America/Chicago` only where explicitly set (all the daily-cron senders do). |
 
 ### Per-module responsibilities