[VS-NfD] Add a dedup window so Yjs sync does not flood the trail #223

New Issue

fable-5 · 2026-07-30T01:43:53+02:00

fable-5 commented

2026-07-30 01:43:53 +02:00

Plan reference: 20-massnahmenplan.md -> Phase 3, Variante A
ADR: ADR 0023
Effort: M (2 AT)
Depends on: #222

Context

A live editing session produces continuous traffic; one event per message
is both useless as evidence and a performance problem. One session plus one
page within N minutes is one read.

Current state

The live document is pages.ydoc_state plus a page_updates log; collab
persistence is debounced (~2 s) and sessions are long-lived
(apps/collab/src/persistence.ts, session registry in
apps/collab/src/session-registry.ts).

Acceptance criteria

Deduplication key (session + page + channel) and window length are
configurable, with a documented default.
The first access in a window is always recorded, and the record
states that it represents a window, not a single request — so the
evidence is not misread.
Reconnects within a window do not create a second event; a new
session does, even for the same user.
Load evidence: a realistic editing session produces a bounded number
of events (measured figure recorded in the PR).
The window is documented in ADR 0023 and #228, because it defines
what the trail can and cannot prove.

Out of scope

Buffered writing for a high-volume all-reads variant (Variant B).

**Plan reference:** `20-massnahmenplan.md` -> Phase 3, Variante A **ADR:** ADR 0023 **Effort:** M (2 AT) **Depends on:** #222 ## Context A live editing session produces continuous traffic; one event per message is both useless as evidence and a performance problem. One session plus one page within N minutes is one read. ## Current state - The live document is `pages.ydoc_state` plus a `page_updates` log; collab persistence is debounced (~2 s) and sessions are long-lived (`apps/collab/src/persistence.ts`, session registry in `apps/collab/src/session-registry.ts`). ## Acceptance criteria - [ ] Deduplication key (session + page + channel) and window length are configurable, with a documented default. - [ ] The **first** access in a window is always recorded, and the record states that it represents a window, not a single request — so the evidence is not misread. - [ ] Reconnects within a window do not create a second event; a new session does, even for the same user. - [ ] Load evidence: a realistic editing session produces a bounded number of events (measured figure recorded in the PR). - [ ] The window is documented in ADR 0023 and #228, because it defines what the trail can and cannot prove. ## Out of scope Buffered writing for a high-volume all-reads variant (Variant B).

fable-5 added this to the M29 — VS-NfD: read-access audit trail milestone 2026-07-30 01:43:53 +02:00

fable-5 added the

vs-nfd

area:storage

effort:M

labels 2026-07-30 01:43:53 +02:00

fable-5 referenced this issue

2026-07-31 12:25:52 +02:00

#223: dedup window for the read trail #279

fable-5 referenced this issue

2026-07-31 12:25:53 +02:00

#224: read-trail storage - partitioning, retention, admin query path #280

fable-5 referenced this issue from a commit

2026-07-31 12:53:38 +02:00

#223: dedup window for the read trail

fable-5 referenced this issue from a commit

2026-07-31 12:53:38 +02:00

#224: read-trail storage — partitioning, retention, admin query path

fable-5 commented

2026-07-31 12:59:07 +02:00

Implemented in PR #279 (commit fd4fd60), contained in the merged chain (PR #281, run 596 green; own run 592 failed only on runner infra). Aligned dedup windows via unique (dedup_key, window_bucket) - race-free insert-or-skip; readTrail.dedupWindowMinutes default 5, documented in the hardening guide; rows carry windowSeconds so the evidence states it represents a window. Load evidence: 30 collab-token renewals inside one window = exactly 1 event (test), bounding a live session at ~12 events/hour/page. Reconnect/new-session/channel-separation/window-rollover each tested (6 tests). ADR 0023 and the security documentation state what the trail can and cannot prove.

Implemented in PR #279 (commit fd4fd60), contained in the merged chain (PR #281, run 596 green; own run 592 failed only on runner infra). Aligned dedup windows via unique (dedup_key, window_bucket) - race-free insert-or-skip; readTrail.dedupWindowMinutes default 5, documented in the hardening guide; rows carry windowSeconds so the evidence states it represents a window. Load evidence: 30 collab-token renewals inside one window = exactly 1 event (test), bounding a live session at ~12 events/hour/page. Reconnect/new-session/channel-separation/window-rollover each tested (6 tests). ADR 0023 and the security documentation state what the trail can and cannot prove.

fable-5 closed this issue

2026-07-31 12:59:07 +02:00

Sign in to join this conversation.