ece94f47 - Align the schema-array and zap-ingest TSDoc with the schema docs and handbook

[TaprootFreak]

EN:
Eight doc comments and one handbook line described behaviour the code does not have, all of them follow-ups to #109 and all comment or prose lines only. Two still claimed that MESSAGE_SCHEMA_SQL and CONVERSATION_SCHEMA_SQL "match" their docs/schema files, although those omit the DO $unwrap$ boot repair by design. The array in db-change.ts carries the log_db_change trigger body that on UPDATE collapses an unchanged, unredacted bytea column to a reference, while its comment named only the one-time view_key rewrite. The zap-ingest comments and the handbook now state the same rule with the same bounds: a repeated identical outcome:reason is normally not written again, that is not a guarantee, and a changed decision always writes a new row.

DE:
Acht Doc-Kommentare und eine Handbuch-Zeile beschrieben ein Verhalten, das der Code nicht hat, alle als Nachtrag zu #109 und alle nur Kommentar- oder Fliesstext. Zwei behaupteten noch, MESSAGE_SCHEMA_SQL und CONVERSATION_SCHEMA_SQL würden ihren docs/schema-Dateien „entsprechen", obwohl diese den DO $unwrap$-Boot-Repair bewusst auslassen. Das Array in db-change.ts trägt den log_db_change-Triggerkörper, der beim UPDATE eine unveränderte, nicht redigierte bytea-Spalte auf einen Verweis zusammenzieht, während sein Kommentar nur die einmalige view_key-Umschreibung nannte. Die Zap-Ingest-Kommentare und das Handbuch nennen jetzt dieselbe Regel mit denselben Grenzen: ein wiederholtes identisches outcome:reason wird normalerweise nicht erneut geschrieben, das ist keine Garantie, und eine geänderte Entscheidung schreibt immer eine neue Zeile.

Details

What changed

File	Symbol	Why it was wrong
src/lib/message-store.ts	MESSAGE_SCHEMA_SQL	Said it matches docs/schema/message.sql, which omits the DO $unwrap$ boot repair by design
src/lib/conversation-store.ts	CONVERSATION_SCHEMA_SQL	Same, for docs/schema/conversation.sql
src/lib/db-change.ts	DB_CHANGE_SCHEMA_SQL	Named only the one-time view_key rewrite, and left out that the bytea reference is written on UPDATE only and only for a column that is both unchanged and unredacted
src/lib/nostr/zap-index.ts	zapDecisions	Did not record the asymmetry with deleteById: both store adapters forget the receipt id when the message goes away, this map does not
src/lib/nostr/zap-index.ts	persistZapIngest	Read as an unconditional skip, although the memory is set only after the write resolves
src/lib/nostr/zap-index.ts	indexZapReceipt	Claimed no further row is ever written for a known receipt, then claimed at most one per decision — both false
src/lib/nostr/zap-index.ts	indexOpenZapReceipts	Claimed a steady state writes nothing at all, and lost the conditional about the first tick after a restart
src/lib/nostr/zap-index.ts	ingestOneReceipt	Did not say which decisions short-circuit it, nor that every other reason is re-validated
docs/handbook/functions.md	Ingest dedupe	Stated the rule unconditionally, contradicting the corrected comments

Four commits, because the first three attempts were wrong in different directions

The first version said re-validating a known receipt writes no further ingest row. persistZapIngest skips only when the same outcome:reason recurs, so a changed decision does write another row — the repository's own test, persists again when a non-terminal decision later becomes indexed, asserts exactly two rows for that transition.

Correcting that overshot into a second false claim: that the same outcome:reason is persisted at most once per receipt id per store instance. It is not. persistZapIngest sets the memory only after recordZapIngest resolves, startNostrWorker fires each tick with setInterval without awaiting the previous one, and a failed write leaves the memory untouched. Nothing in the database enforces it either: recordZapIngest is a plain INSERT and the index on receipt_id is not unique. Two overlapping ticks or a retry can produce a second identical row.

The same round also found that the rewrite had dropped the handbook's "may" about the first tick after a restart. That hedge carries weight: the tick returns early when there are no relay urls or no event ids, and listLatest only covers currently recent notes, so a receipt whose message has aged out is never queried again at all.

The fourth commit brings the handbook and persistZapIngest in line, so the file no longer contradicts itself.

One asymmetry worth knowing

The decision memory lives in the process, not in the database, so it outlives the state it mirrors. When deleteById removes a message, both store adapters forget the receipt id and would record it again; this map does not.

It is not reachable today, and the reasoning is worth recording: the tick asks relays only for the note event ids returned by listLatest, which excludes deleted and soft-deleted rows in both adapters, and indexZapReceipt has no caller outside the tick. Two independent reviews tried to refute this and found no path. It would become reachable the moment the queried set included deleted or hidden posts, and then a zap would be skipped silently.

Verification on the pushed head

bun run typecheck        PASS
bun run lint             PASS
bun run handbook:check   PASS
bun run e2e:check        PASS
bun run test             PASS (86 files, 1434 tests)
bun run build            PASS

No executable code, schema or test changed in this pull request.

[TaprootFreak]

EN:
One review round brought both Grok gates (quality and logic) to approved with zero findings on head b55d606, CI is green, and the PR stays in draft only because the mandatory Codex gate is unavailable on this host.

DE:
Eine Review-Runde hat beide Grok-Gates (Qualität und Logik) auf Head b55d606 mit null Funden auf approved gebracht, die CI ist grün, und der PR bleibt nur deshalb Draft, weil das Pflicht-Gate Codex auf diesem Host nicht verfügbar ist.

Details

• Inner review (spec conformance): approved.
• Quality gate: approved, 0 findings — TSDoc accurate against docs/schema/message.sql (lines 9-14) and docs/schema/conversation.sql (lines 4-9), consistent with the handbook Returns bullets, commit and PR body conform.
• Logic gate: approved, 0 findings — comment-only diff, statements verified against the arrays' last statements.
• Local: typecheck, lint, handbook:check green; CI green.
• Codex gate: unavailable (CLI not installed on the review host).