#225: read-trail master switch and purpose limitation #281

fable-5 · 2026-07-31T12:25:54+02:00

fable-5 commented

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

readTrail.enabled, default OFF (works-council rationale): off writes nothing anywhere - no row, no stdout line (tested); the api announces the switch position each boot so an eventless trail is never ambiguous. Written purpose limitation ships as section 7 of the VS-NfD security documentation (what is recorded, why, who may read, how long, what it may NOT be used for); the hardening guide reference configuration sets true and points there. Stacked on #224. Refs #225

fable-5 added 4 commits 2026-07-31 12:25:54 +02:00

#222 : read-access trail for classified pages

CI / Lint, typecheck, test (pull_request) Successful in 6m25s

Details

CI / Build container images (pull_request) Successful in 2m58s

Details

CI / Auth e2e pack (pull_request) Successful in 8m35s

Details

CI / Import/export fidelity gate (pull_request) Successful in 1m7s

Details

CD / Deploy to Test (push) Blocked by required conditions

Details

CD / Smoke tests against Test (push) Blocked by required conditions

Details

CD / Promote to Int (push) Blocked by required conditions

Details

CI / Auth e2e pack (push) Blocked by required conditions

Details

CI / Import/export fidelity gate (push) Blocked by required conditions

Details

CI / Build container images (push) Blocked by required conditions

Details

CI / Lint, typecheck, test (push) Has been cancelled

Details

CD / Build and push images (push) Has been cancelled

Details

05a979bac3

Instrument every full-content read channel for pages with
classification = vs_nfd (ADR 0023, variant A): SPA state fetch and read
rendering, public JSON content, no-JS shell, expanded embeds, public API
GET (incl. the MCP read_page path and write echoes), attachment download
under the #212 effective classification, all export shapes (markdown,
pond ZIP, account data export, queued docx/odt/pdf at enqueue), and
collab-token issuance as the api-side proxy for the WS join.

Events land in the new read_events table (no FKs — evidence survives
page purges and hard user deletions) with actor, session key
(session:/token:/job:/anon), page, pond, channel and the classification
at read time. Recording failures are NOT swallowed: a failed write
aborts the read (hard failure, the deliberate contrast to AuditService —
decision recorded in ADR 0023 and security.md §Logging, together with
the recorded residuals: content fragments and feeds).

One e2e test per channel proves both the event and its absence for
unclassified pages, plus the hard-failure semantics.

Refs #222.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#223 : dedup window for the read trail

CI / Lint, typecheck, test (pull_request) Successful in 6m29s

Details

CI / Auth e2e pack (pull_request) Failing after 5s

Details

CI / Import/export fidelity gate (pull_request) Has been skipped

Details

CI / Build container images (pull_request) Successful in 2m55s

Details

fd4fd60c99

One event per (session, page, channel) within an aligned window of
readTrail.dedupWindowMinutes (default 5): buckets are
floor(epoch / windowSeconds), and a unique (dedup_key, window_bucket)
pair collapses concurrent duplicates race-free at insert time — the
first access in a window is always recorded, a later duplicate lands on
the unique violation and is skipped quietly (a skipped duplicate is not
a gap; only real write failures still abort the read). Each row carries
windowSeconds, so the evidence states it represents a window, never a
request count.

Reconnects within a window stay one event; a new session records again
even for the same user; channels never collapse into each other; the
page-less attachment key uses the documented `-` placeholder. Load
evidence: 30 collab-token renewals inside one window produce exactly one
event (test), bounding a live editing session at ~12 events/hour/page.

Window semantics documented in ADR 0023, the VS-NfD security
documentation (#228) and as a hardening-guide line for the new setting
(care rule: same PR).

Refs #223.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

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

CI / Lint, typecheck, test (pull_request) Successful in 6m30s

Details

CI / Auth e2e pack (pull_request) Failing after 5s

Details

CI / Import/export fidelity gate (pull_request) Has been skipped

Details

CI / Build container images (pull_request) Failing after 2s

Details

2bdb0ec2cf

Convert read_events to monthly RANGE partitions on occurred_at, with a
DEFAULT partition as safety net: a lagging maintenance job must never
turn the trail's hard-failure semantics into an outage for classified
reads. The dedup unique pair (#223) moves to per-partition indexes
(PostgreSQL cannot carry it on the parent); a bucket spanning a month
boundary may record one duplicate — over-recording is acceptable, gaps
are not.

New daily job read-trail-maintenance (job-count fence 9 -> 10) creates
months ahead — each with its dedup index — and applies the trail's own
retention readTrail.retentionDays (default 365, deliberately independent
of audit.retentionDays): whole expired months are DROPped without
scanning, remainders deleted by range, every run audited as
read_trail.pruned (catalogue v1.2; the fence regex now admits an
underscore namespace).

Site-Admin query path GET /admin/system/read-events answers "who read
page X" and "what did user Y read" within a period — API-only by
design, documented. Growth measured and documented in data-model.md:
~1 MB per 1000 events including indexes.

Tests: retention pruning + audited deletion + admin queries on the
shared database; the partitioned shape, per-partition P2002 dedup,
months-ahead creation and DROP-based pruning against a fresh database
built by the real migration chain.

Refs #224.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

#225 : read-trail master switch and written purpose limitation

CI / Lint, typecheck, test (pull_request) Failing after 4s

Details

CI / Auth e2e pack (pull_request) Has been skipped

Details

CI / Import/export fidelity gate (pull_request) Has been skipped

Details

CI / Build container images (pull_request) Has been skipped

Details

5de398c435

New instance switch readTrail.enabled, default OFF: read logging is
employee monitoring in a works council's eyes — an ordinary instance
must not surveil reads. Off means no event is written ANYWHERE (no row,
no stdout line, verified by test); the api announces the switch position
once per boot, so an eventless trail is never ambiguous — a gap reads
as "was off", never "was lost".

The written purpose limitation ships as section 7 of the VS-NfD
security documentation (#228): what is recorded (no content, no titles,
no IPs, no fingerprinting), why (evidence for reads of marked content
only — variant A is the technical anchor of the promise), who may read
it (Site Admin, API-only), for how long (readTrail.retentionDays,
audited pruning), and what it may NOT be used for (no performance or
behaviour monitoring). The hardening guide's reference configuration
turns the trail on (reference value true) and points to that text; the
existing trail suites now enable the switch explicitly.

Refs #225.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

fable-5 force-pushed issue-225-read-trail-switch from 5de398c435 to 7ce6467385

2026-07-31 12:33:08 +02:00

Compare

fable-5 force-pushed issue-225-read-trail-switch from 7ce6467385 to 4af5e6e81f

2026-07-31 12:35:21 +02:00

Compare

fable-5 merged commit 4af5e6e81f into main

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

fable-5 referenced this pull request

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

#223: dedup window for the read trail #279

fable-5 referenced this pull request