Collapse the sprawling, partly-stale docs/sync-and-op-log/ tree into a
small authoritative set and make the sync-correctness invariant
partly lint-enforced instead of convention-only.
Docs:
- Delete superseded/duplicate/provably-stale design, plan, and
background-research docs (quick-reference, the architecture-diagrams
monolith, the "Hybrid Manifest" docs describing code that does not
exist, completed long-term plans, LLM-synthesis analyses).
- Salvage load-bearing decision history into the surviving docs before
deletion: rejected-alternatives rationale -> operation-log-architecture
("Why this architecture"); vector-clock pruning incident history ->
vector-clocks.md; archive-payload optimization -> architecture E.7.
- Add contributor-sync-model.md as the single-invariant entry point
(one user intent = one op; replayed/remote ops must not re-trigger
effects), with a decision table mapping to the enforcing linters.
- Repoint external/internal cross-refs; add CONTRIBUTING.md + CLAUDE.md
pointers; record the migration in a dated docs/plans/ design doc.
Enforcement (new eslint-local-rules):
- no-actions-in-effects (error): effects must inject LOCAL_ACTIONS /
ALL_ACTIONS, never the raw @ngrx/effects Actions stream.
- no-multi-entity-effect (warn, heuristic): flags a literal returned
array of >=2 action-creator calls; docstring + valid-case specs pin
exactly which shapes are and are not detected.
- run-specs.js runner wired into `npm run lint` via test:lint-rules;
refuses to run under test-framework globals and counts RuleTester.run
invocations so a spec that asserts nothing fails instead of passing.
- Correct the ALL_ACTIONS JSDoc in local-actions.token.ts to match
reality (archive-operation-handler uses LOCAL_ACTIONS).
Reviewed via parallel multi-agent review; findings W1/W2/W4 and a
dangling doc anchor addressed.
Add back the "why/symptom" tails that were over-trimmed: selector-based
effects fire on every store change, multi-entity meta-reducer example,
TODAY_TAG.taskIds ordering-only role, store.dispatch non-blocking
behavior, and SYNC_IMPORT "by design" framing. Rules stay one-liners
but now carry enough context for Claude to recognize when they apply.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop the architecture overview (derivable from code and already
covered in docs/sync-and-op-log/ and ARCHITECTURE-DECISIONS.md),
collapse the long sync invariants into one-liners with pointers,
and dedupe the anti-patterns table against the rule lists. Move
the SuperSync docker-compose block and E2E iteration tips into
e2e/CLAUDE.md where the rest of the E2E reference lives. Tighten
the new docs/documentation-guide.md by dropping content that
duplicates docs/wiki/0.00-Wiki-Structure-and-Organization.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a documentation-update rule to CLAUDE.md and extract the
detailed guidance into docs/documentation-guide.md, mirroring the
styling-guide pattern. Defaults wiki edits to Reference (3.XX) notes
and points to 0.00-Wiki-Structure-and-Organization.md as required
reading.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces ad-hoc `Date.now() - _dateService.startOfNextDayDiff` arithmetic
scattered across services with a small set of offset-aware helpers on
DateService, and makes the raw field private so TypeScript prevents
future regressions.
Public surface added to DateService:
- getLogicalTodayDate(): Date — offset-aware "today"
- getLogicalTomorrowMs(): number — logical today + 1 calendar day,
DST-safe via setDate (naive +24h stayed on the same local date
during fall-back transitions)
- getStartOfNextDayDiffMs(): number — read-only accessor for the
service-boundary case where pure utilities need the raw offset
The raw `startOfNextDayDiff` field is now `private`; TypeScript
catches both member access and destructuring from outside.
Migrated call sites (all semantic-identical except the DST fix):
- planner.service.ts: tomorrow$ and ensureDayLoaded
- add-tasks-for-tomorrow.service.ts: addAllDueToday/Tomorrow
(+ offset-aware spec coverage)
- daily-summary.component.ts: isIncludeYesterday
- global-config.effects.ts + app-state.effects.ts: setTodayString
payloads now read via the accessor
Preserved for sync-replay determinism:
- isTodayWithOffset pure util in src/app/util/is-today.util.ts
- reducers/selectors continue to take startOfNextDayDiffMs as an
explicit argument from action payloads
Deferred with an in-file TODO: task-due.effects.ts:170 — the effect
is selector-driven (replay-sensitive per CLAUDE.md #8) and its spec is
xdescribe'd, so verification is impossible in this pass.
Documented in CLAUDE.md (Important Development Notes #14 + an
anti-patterns row).
A broader audit surfaced 10 pre-existing sites elsewhere in the
codebase that bypass the logical clock (planner daysToShow$,
argument-less getDbDateStr in pipes, simple-counter streak, plugin
counter). Those are tracked separately and not part of this refactor.
Remove task titles from reminder dialog trigger, reminder worker
postMessage, and mobile notification success logs. Add log privacy
comment to Log class and anti-pattern entry to CLAUDE.md.
Co-authored-by: Rob Williamson <rob@robwilliamson.com>
Extract styling rules, CSS variable reference, and design token
patterns into docs/styling-guide.md for a consistent design language.
CLAUDE.md now points to the guide for all styling changes.
Remove references to deleted docs/ai/ files, update stale comments about
protectedClientIds and pruning-aware comparison to reflect current REPLACE
semantics, fix MAX=30→20 heading, client_0..29→19 comment, use ?? over ||,
preserve lastSeq in server clean-slate path to prevent sequence reuse, and
add clarifying comments for mock limitations and validation guards.
- Fix client/server comparison divergence: remove isVectorClockEmpty
short-circuit that caused {} vs {a:0} to return LESS_THAN on client
but EQUAL on shared impl. Now delegates all comparisons to shared.
- Align server value cap with client: raise from 10M to MAX_SAFE_INTEGER
to prevent silent clock entry stripping on long-term usage.
- Make client validation require integers (Number.isInteger) matching
server-side validation.
- Add deterministic tie-breaking (localeCompare) to pruning sort for
equal counter values.
- Fix stale comments: MAX references and CLAUDE.md DoS cap (5x→2.5x).
Lower the cap to leave headroom for future increases and surface
size-related edge cases earlier. All pruning logic is MAX-agnostic
so this is a safe constant change with documentation updates.
At MAX=10, pruning triggered frequently enough (11+ unique client IDs from
reinstalls/new browsers) to require 4 defense layers compensating for
information loss: pruning-aware comparison, protected client IDs with
migration, isLikelyPruningArtifact heuristic, and same-client check.
At MAX=30, pruning almost never triggers (needs 31+ unique client IDs).
A 30-entry clock is ~500 bytes — negligible bandwidth. This allows removing
most defense layers while keeping two cheap backward-compat checks for old
10-entry pruned data still on servers.
Removed:
- Pruning-aware mode in compareVectorClocks (standard comparison now)
- Protected client IDs mechanism (storage, migration, preservation)
- selectProtectedClientIds function
- Clock normalization in SyncImportFilterService
Kept temporarily (backward compat with old 10-entry data):
- isLikelyPruningArtifact with LEGACY_MAX=10
- Same-client check (always mathematically correct)
The sanitizeVectorClock() DoS cap was changed to 5x MAX (50 entries) but
comments in CLAUDE.md, vector-clocks.md, sync.types.ts, and
validation.service.ts still referenced the old 3x MAX (30) value.
- Remove limitVectorClockSize from ConflictResolutionService (same
infinite loop risk as SupersededOperationResolverService)
- Include retry-exceeded ops in permanentRejectionCount so sync status
accurately reflects data loss
- Fix stale JSDoc (100 -> 30 entries) in sanitizeVectorClock
- Remove dead getProtectedClientIds mocks from spec files
- Extract _getEntityKey helper, remove redundant guards, optimize
Object.keys calls in server pruning log
* fix(sync): prevent infinite loop when concurrent modification resolution keeps failing
When vector clock pruning makes it impossible to create a dominating clock
(e.g., entity clock has MAX entries and client ID isn't among them), the cycle
"upload → CONFLICT_CONCURRENT → merge clocks → upload → reject again" repeats
endlessly. This adds a per-entity retry counter (MAX_CONCURRENT_RESOLUTION_ATTEMPTS=3)
that permanently rejects ops after exceeding the limit, breaking the sync loop.
The counter resets when a sync cycle completes with no rejections (healthy state).
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* fix(sync): move vector clock pruning after conflict detection to fix root cause
The infinite sync loop happens because it's mathematically impossible to build
a dominating clock with MAX_VECTOR_CLOCK_SIZE entries when the entity's clock
already has MAX entries and the client's ID isn't among them. The merged clock
needs MAX+1 entries (all entity clock IDs + client ID), but client-side pruning
drops one entity clock ID. The server's pruning-aware comparison then sees the
dropped key as non-shared and returns CONCURRENT instead of GREATER_THAN.
Fix: Move limitVectorClockSize from validation (before comparison) to
processOperation (after comparison, before storage). The full unpruned clock
is now used for conflict detection — all entity clock IDs are present so
bOnlyCount=0 → GREATER_THAN. Storage still gets the pruned clock.
Client-side: Stop pruning in SupersededOperationResolverService. The server
handles pruning after conflict detection.
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* fix(sync): tighten vector clock sanitize limit from 100 to 3x MAX_VECTOR_CLOCK_SIZE
The old sanitize cap of 100 entries was unnecessarily wide. Since conflict
resolution clocks are at most ~12-15 entries (entity clock MAX=10 + client ID
+ a few merged), cap at 3x MAX (30) for DoS protection while leaving ample
room for legitimate clocks.
Also update server-side pruning tests to use realistic clock sizes (20 entries
instead of 50) to stay within the new sanitize limit.
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* docs(sync): document vector clock pruning invariant and infinite loop fix
- Add "Pruning and the Pruning-Aware Comparison" section to vector-clocks.md
explaining the critical invariant: server prunes AFTER comparison, not before
- Add rule 13 to CLAUDE.md to prevent future regressions
- Update conflict resolution key files table with rejected-ops-handler and
superseded-operation-resolver services
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* docs(sync): update last-updated date in conflict resolution docs
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* test(sync): update pruning tests to reflect server-side pruning design
Client no longer prunes vector clocks during conflict resolution — the
server handles pruning after conflict detection. Tests now verify the
merged clock is sent unpruned with all keys preserved.
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
* test(sync): fix client-side pruning tests and add server-side regression test
- Update 7 SupersededOperationResolverService tests to verify client
does NOT prune (server handles pruning after conflict detection)
- Remove redundant `newClock` alias in superseded-operation-resolver
- Add regression test: MAX+1 entry clock accepted as GREATER_THAN
when it dominates a MAX entry entity clock (the core infinite loop fix)
https://claude.ai/code/session_016RAxms5dTouU98wFNQaAcv
---------
Co-authored-by: Claude <noreply@anthropic.com>
docker-compose.e2e.yaml was failing when used standalone because the
supersync service only had a port override without a base definition.
Split into separate files so e2e:docker:webdav works without errors.
- Update CLAUDE.md to reference /src/app/op-log/persistence/ instead
of deleted /src/app/pfapi/ directory
- Fix boolean coercion in archive-migration.service.ts (same pattern
as bug fixed in 183bf2c18 for LegacyPfDbService)
- Replace deprecated .toPromise() with firstValueFrom() in
archive.service.ts for RxJS 8 compatibility
- Add null checks in simple-counter.reducer.ts to prevent crashes when
entity doesn't exist (fixes "Cannot read properties of undefined")
- Add missing entityIds to updateAllSimpleCounters action - was causing
operation log to skip persistence
- Add try-catch in operation-log-upload.service.ts to show alert when
storage quota exceeded (413 error)
- Fix supersync-network-failure.spec.ts test timing - route interception
must happen before task creation
- Add documentation to CLAUDE.md for running supersync tests with
real-time output using --reporter=line
- Fix CLAUDE.md path reference from docs/op-log/ to docs/sync-and-op-log/
- Rewrite section 2c in architecture diagrams to reflect actual implementation:
- Was: UUIDv7 timestamp replay (removed feature)
- Now: Vector clock filtering with clean slate semantics
- Update service reference from removed _replayLocalSyncedOpsAfterImport()
to SyncImportFilterService.filterOpsInvalidatedBySyncImport()
- Clarify that CONCURRENT ops are dropped, not replayed
Move scattered architecture docs into centralized locations:
- Move operation-log docs from src/app/core/persistence/operation-log/docs/
to docs/op-log/
- Flatten docs/sync/sync/ nested structure to docs/sync/
- Move supersync-encryption-architecture.md from docs/ai/ to docs/sync/
- Copy pfapi sync README to docs/sync/pfapi-sync-overview.md
- Update all cross-references to use new paths
This improves discoverability and keeps architecture documentation
separate from source code.
SYNC_IMPORT and BACKUP_IMPORT now represent a complete fresh start:
- All operations without knowledge of the import are dropped
- CONCURRENT ops from "unknown clients" are no longer preserved
- Local synced ops are NOT replayed after import
This ensures a true "restore to point in time" semantic where all
clients start fresh from the imported state, with no concurrent
work preserved.
Changes:
- Simplify SyncImportFilterService to filter ALL CONCURRENT/LESS_THAN ops
- Remove _replayLocalSyncedOpsAfterImport() method and related code
- Remove _checkOperationEntitiesExist() helper method
- Update tests to expect new behavior
- Document semantics in CLAUDE.md
Document the pattern of yielding to the event loop after bulk NgRx
dispatches to prevent state updates from being lost during rapid
dispatch sequences (50+ operations).
Selector-based effects (like preventParentAndSubTaskInTodayList$) were
firing during operation replay because they subscribe directly to store
selectors rather than actions. LOCAL_ACTIONS filtering only works for
action-based effects.
This caused duplicate operations to be captured during hydration, growing
the operation queue unnecessarily and impacting performance.
- Add HydrationStateService to track when remote ops are being applied
- Wrap OperationApplierService.applyOperations() with hydration state
- Filter preventParentAndSubTaskInTodayList$ during hydration
- Document selector-based effects anti-pattern in CLAUDE.md
Establish general rule: effects should NEVER run for remote operations.
Side effects happen exactly once on the originating client.
- Create ArchiveOperationHandler service for remote archive side effects
- Integrate handler into OperationApplierService (called after dispatch)
- Change archive.effects.ts to use LOCAL_ACTIONS only
- Update CLAUDE.md with the general rule about effects
- Add Section 8 to architecture diagrams documenting the pattern
For archive operations:
- moveToArchive: local writes BEFORE dispatch, remote via handler AFTER
- restoreTask: local via effect, remote via handler
- flushYoungToOld: local via effect, remote via handler
Tasks created without explicit dueDay don't appear in TODAY view
due to recent selector changes. Add sd:today short syntax to ensure
tasks have dueDay set and appear correctly in tests.
- Add clientId validation before persisting operations
- Track compaction failures and notify user after 3 consecutive failures
- Add hydration recovery notification when both hydration and recovery fail
- Wrap conflict resolution in try-catch for atomicity
- Add HYDRATION_FAILED, COMPACTION_FAILED, CONFLICT_RESOLUTION_FAILED translations
- Update CLAUDE.md: only edit en.json for translations
- Keep only the most useful commands:
- e2e:playwright - run all tests with minimal output
- e2e:playwright:file - run single file with detailed output
- e2e:playwright:ui/debug/headed/report - existing useful commands
- Remove complexity: test-summary.js, minimal config, redundant commands
- Use line reporter by default for cleaner output
- Update CLAUDE.md documentation
BREAKING CHANGE: Removed e2e:playwright:quick, e2e:playwright:failures, and e2e:playwright:summary commands
- Add npm run e2e:playwright:file command for running individual test files
- Update CLAUDE.md documentation with all Playwright commands
- Example usage: npm run e2e:playwright:file tests/work-view/work-view.spec.ts
- Add 'npm run checkFile <file>' to run prettier and lint on a single file
- Add 'npm run prettier:file <file>' for formatting individual files
- Add 'npm run lint:file <file>' for linting individual files
- Add 'npm run test:file <file>' for running tests on individual spec files
- Create wrapper scripts that show minimal output on success, full output on errors
- Update CLAUDE.md to emphasize using checkFile command frequently
- Add 25-second timeout for test execution to prevent hanging
* feat/merge-issue-provider-logic: (42 commits)
docs: add comment explaining GitLab issue ID format and remove debug logs
fix: extract numeric issue ID from malformed GitLab issue IDs
debug: add logging to GitLab issueLink to debug URL construction
fix: update all references from searchIssues$ to searchIssues Promise method
fix: update all references from issueLink$ to issueLink Promise method
fix: correct GitLab issue URL format
fix: change ISSUE_REFRESH_MAP to use issueProviderId as key
outline
refactor: convert pollTimer$ to simple pollInterval number
refactor: convert searchIssues$ to return Promise instead of Observable
refactor: convert getById$ to return Promise instead of Observable
refactor: convert issueLink$ to return Promise instead of Observable
refactor: convert testConnection$ to return Promise instead of Observable
feat(issue): further improve
refactor: improve typing for comment parameters in issue-content component
feat(issue): further simplify and make some conditions work as they should
refactor(issue): merge IssueFieldConfig field and getValue into unified value property
refactor(issue): use proper issue interface types instead of any casts
feat(issue): more adjustments
feat(issue): more adjustments
...
