@vue-skuilder/db 0.2.37 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/{contentSource-D_E7JaxR.d.ts → contentSource-2zVmcjKA.d.ts} +6 -1
  2. package/dist/core/index.cjs +155 -100
  3. package/dist/core/index.cjs.map +1 -1
  4. package/dist/core/index.d.ts +5 -5
  5. package/dist/core/navigators/Pipeline.mjs +8 -0
  6. package/dist/core/navigators/Pipeline.mjs.map +1 -1
  7. package/dist/core/versionStamps.mjs +1 -1
  8. package/dist/{dataLayerProvider-BDshhSp_.d.ts → dataLayerProvider-rGyLQ93v.d.ts} +1 -1
  9. package/dist/diagnostics/index.d.ts +3 -3
  10. package/dist/impl/common/BaseUserDB.mjs +61 -34
  11. package/dist/impl/common/BaseUserDB.mjs.map +1 -1
  12. package/dist/impl/couch/CourseSyncService.mjs +23 -1
  13. package/dist/impl/couch/CourseSyncService.mjs.map +1 -1
  14. package/dist/impl/couch/courseDB.mjs +4 -0
  15. package/dist/impl/couch/courseDB.mjs.map +1 -1
  16. package/dist/impl/couch/index.cjs +177 -101
  17. package/dist/impl/couch/index.cjs.map +1 -1
  18. package/dist/impl/couch/index.d.ts +5 -3
  19. package/dist/impl/couch/updateQueue.mjs +69 -46
  20. package/dist/impl/couch/updateQueue.mjs.map +1 -1
  21. package/dist/impl/static/index.cjs +151 -100
  22. package/dist/impl/static/index.cjs.map +1 -1
  23. package/dist/impl/static/index.d.ts +4 -4
  24. package/dist/{index-BLDpFYG3.d.ts → index-C745YB_6.d.ts} +1 -1
  25. package/dist/index.cjs +187 -102
  26. package/dist/index.cjs.map +1 -1
  27. package/dist/index.d.ts +23 -10
  28. package/dist/index.mjs +2 -1
  29. package/dist/study/SessionController.mjs +4 -0
  30. package/dist/study/SessionController.mjs.map +1 -1
  31. package/dist/{types-DChCz22D.d.ts → types-DF0JuPbs.d.ts} +1 -1
  32. package/dist/{types-legacy-fT5Y1Wuy.d.ts → types-legacy-DdVjg81H.d.ts} +1 -1
  33. package/dist/util/packer/index.d.ts +3 -3
  34. package/dist/util/perfMarks.mjs +30 -0
  35. package/dist/util/perfMarks.mjs.map +1 -0
  36. package/docs/session-lifecycle-and-replan.md +71 -58
  37. package/package.json +3 -3
  38. package/src/core/interfaces/courseDB.ts +6 -0
  39. package/src/core/navigators/Pipeline.ts +8 -0
  40. package/src/impl/common/BaseUserDB.ts +74 -46
  41. package/src/impl/couch/CourseSyncService.ts +19 -2
  42. package/src/impl/couch/courseDB.ts +5 -0
  43. package/src/impl/couch/updateQueue.ts +86 -82
  44. package/src/study/SessionController.ts +4 -0
  45. package/src/util/index.ts +1 -0
  46. package/src/util/perfMarks.ts +35 -0
  47. package/tests/impl/updateQueue.test.ts +57 -0
@@ -7,11 +7,11 @@
7
7
  > the former `agent/session-pipeline-perf` assessment and should be trimmed
8
8
  > before this ships as public framework documentation.
9
9
  >
10
- > **Perf work is parked (2026-05).** The felt mid-session jank (the synchronous
11
- > wedge-breaker firing when the queue bottomed out) is resolved by the cache work
12
- > recorded below. The `[perf]` timing instrumentation is commented out in place
13
- > (search `[perf] parked` in the source); uncomment to re-measure. Remaining
14
- > threads (cold spin-up, possibly-remote reads) are documented but not pursued.
10
+ > **Perf status (2026-11).** The 2026-05 mid-session jank is resolved (cache
11
+ > work, below). The 2026-11 runtime-perf work resolved the course-DB side of
12
+ > session start: sessions bind to the local replica when one exists, and far
13
+ > fewer remote calls when one doesn't. Open: user-DB reads and main-thread work
14
+ > during replans (see *Open threads*).
15
15
 
16
16
  This document maps how `SessionController` drives content selection through the
17
17
  navigation `Pipeline` during a study session: what runs at session start, when
@@ -334,51 +334,51 @@ sits on one of two clocks:
334
334
 
335
335
  The cache work above optimized the *least* time-sensitive stage (background
336
336
  replan) — correctly, since that is what keeps us out of the wedge. The *most*
337
- time-sensitive stage (cold spin-up, dominated by the ELO view reindex) is
338
- essentially untouched.
339
-
340
- ### Open / parked threads (running notes)
341
-
342
- - **Cold spin-up (~4.6s, blocking)** dominated by the first `elo` view reindex
343
- (`getCardsByELO below~2490ms`). Most time-sensitive, least touched. A cheap
344
- micro-fix worth trying: fire a throwaway `db.query('elo', {limit:1})` early
345
- (e.g. on the study-hub view) to keep the IndexedDB index warm before
346
- `/study/practice`.
347
- - **Reads may be hitting REMOTE CouchDB, not the local replica** — the leading
348
- hypothesis for the remaining costs (see next subsection). If true, this is one
349
- root cause behind spin-up + per-card hydration + `regDoc`, not three.
350
- - **Per-card hydration `cardDoc+tags` = 0.8-2.1s each**, a persistent band (not
351
- just at startup). Entirely `getCourseDoc` + `getAppliedTagsBatch`. On a *local*
352
- PouchDB these should be tens of ms — hence the remote-reads suspicion.
353
- - **`getPendingReviews` ~ 768ms**, recomputed fresh on every replan (SRSgen).
354
- Candidate to incrementalize, but reviews mutate as cards are answered, so
355
- correctness needs care.
356
- - **`regDoc ~ 444ms`** — a single registration-doc read inside
357
- `getCardsCenteredAtELO`. Same "reads may be remote" smell.
358
-
359
- ### The likely root cause: reads may not be local
360
-
361
- `CourseDB` picks local-vs-remote **once, at construction**: `this.db = localDB ??
362
- remoteDB`, where `localDB` is non-null only if `CourseSyncService` sync state is
363
- exactly `'ready'` at that instant. Miss that window (cold first visit:
364
- replication + view-warming takes seconds) and the whole session's pipeline reads
365
- go to the remote handle and **never re-bind** after sync finishes.
366
-
367
- The "remote" CouchDB in dev is `localhost:5984`, so the cost is *not* network
368
- latency — it is **per-request work the CouchDB server does**: MapReduce view-index
369
- maintenance. The log fingerprints it: the same `elo` view queried back-to-back
370
- reads `below=2490ms` then `above=111ms` — cold reindex then warm, not latency
371
- (which would tax both equally). What invalidates the index? *This session's own
372
- ELO writes* — every answered card writes a card-ELO doc, bumping `update_seq`. A
373
- local sync replica is one-shot, read-only and pre-warmed, so local reads never
374
- trigger a reindex.
375
-
376
- To confirm: add a one-line `CourseDB` constructor log (`db=local|remote`); split
377
- the hydration timer into `cardDoc` (`.get`, no view) vs `tags`
378
- (`getAppliedTagsBatch`, a view query) — if `tags` carries the 1-2s it's the
379
- reindex story. The fix is then *not* micro-optimizing reads but guaranteeing the
380
- session runs against a ready local replica (await `'ready'`; re-bind or
381
- lazy-resolve `this.db`; reuse hydration handles).
337
+ time-sensitive stage, cold spin-up, was the 2026-11 work's target (next
338
+ section); the figures in this table are 2026-05's.
339
+
340
+ ### Course-DB reads: local vs remote (resolved 2026-11)
341
+
342
+ The 2026-05 notes suspected session reads were going to remote CouchDB instead of
343
+ the synced replica. Confirmed, and fixed for the course DB (fw #1197, 0.2.37):
344
+
345
+ - **Replica ready at load.** `CourseSyncService` writes `_local/sync-complete`
346
+ when a sync finishes; on later page loads `ensureSynced` hands out the on-disk
347
+ replica at once from that marker and refreshes it in the background (an
348
+ epoch mismatch only drops the marker; the next load rebuilds).
349
+ - **Rebinding between sessions.** `PouchDataLayerProvider` keeps one `CourseDB`
350
+ per course and replaces it when the replica becomes ready, so the *next*
351
+ session on the same page reads locally. A running session keeps the handle it
352
+ was built with (`CourseDB` still binds at construction).
353
+ - **Fewer remote calls without a replica:** one memoized remote handle per
354
+ course with `skip_setup`, `CourseConfig` cached, tag stubs and applied tags
355
+ read through `CourseDB.db` (local when available), strategy docs fetched once.
356
+ Cold preparation went from ~21 requests to 10; with a replica, 2.
357
+
358
+ Production (2026-11-06): cold guest preparation 8.7 s → 3.6 s (remote, mobile
359
+ network); returning device 2.5 s, bound local. Whether a session ran local is
360
+ now visible: `sk:pipeline-run`'s `binding` (below).
361
+
362
+ ### Open threads
363
+
364
+ - **User-DB reads.** A replan's generators used to scan the user's scheduled
365
+ cards three times (`getActiveCards` from ELO and Prescribed,
366
+ `getReviewstoDate` from SRS); they now share one in-flight scan
367
+ (`BaseUserDB.scanScheduledCards`, 2026-11). It still reads the remote handle
368
+ for a logged-in user: scheduled reviews are written to the server and reach
369
+ the local mirror by live sync, so a local read could return a review that was
370
+ just completed. Reading locally would need writes to land locally first. The
371
+ remote range also accumulates tombstones (one per completed review), which
372
+ the scan walks until compaction.
373
+ - **Main-thread work during replans** (filters, tag hydration, scoring) on
374
+ slower devices. Yield points between stages are the cheap first step;
375
+ attribute with a real-device trace first.
376
+ - **A session can't start before its first plan.** Preparation (~2.5–4 s)
377
+ starts when `StudySession.vue` mounts. Consumers with a lead-in (a lesson, a
378
+ hub) could prepare a `SessionController` earlier and hand it in; no seam for
379
+ that yet.
380
+ - **First sync on a new device** (download, IndexedDB writes, view warming)
381
+ runs on the main thread, alongside whatever session starts meanwhile.
382
382
 
383
383
  ### Still-true structural notes
384
384
 
@@ -393,22 +393,35 @@ lazy-resolve `this.db`; reuse hydration handles).
393
393
  3. **Initial fetch is inflated to ~220** (`defaultBatchLimit + initialReviewCap`),
394
394
  compounding (2) at spin-up.
395
395
 
396
- ### Instrumentation (parked)
396
+ ### Instrumentation
397
397
 
398
- The `[perf]` timing logs across `Pipeline`, `SessionController`,
398
+ **Timing marks (stable, shipped; fw #1198).** User Timing entries that tools
399
+ read with `performance.getEntriesByType('mark' | 'measure')` or Lighthouse's
400
+ `user-timings`:
401
+
402
+ | Name | Where | Detail |
403
+ |------|-------|--------|
404
+ | `sk:session-prepare-start`, `sk:session-prepared`, measure `sk:session-prepare` | `SessionController.prepareSession` | — |
405
+ | measure `sk:pipeline-run` (every run) | `Pipeline.getWeightedCards` | stage ms; `binding`: `local` / `remote` / `unknown` (`CourseDBInterface.readsLocal`) |
406
+ | `sk:course-sync-replicated`, `sk:course-sync-ready`, `sk:course-sync-refreshed` | `CourseSyncService` | `ready`'s `from`: `marker` / `sync` |
407
+ | `sk:first-card` | common-ui `StudySession` | card ID |
408
+
409
+ Helpers: `perfMark` / `perfMeasure` (`db/src/util/perfMarks.ts`), which never
410
+ throw.
411
+
412
+ **Parked logs.** The `[perf]` timing logs across `Pipeline`, `SessionController`,
399
413
  `CardHydrationService`, `elo`/`srs` generators, and `courseDB` are commented out
400
- in place — search **`[perf] parked`**. Uncomment to re-measure. The pre-existing
401
- `[Pipeline:timing]` summary line is kept (it predates this effort). Two
402
- provenance fields added during the dig — `awaitedReplan` and `wedgeRuns` on the
403
- `nextCard` log — are the instruments to re-enable first if the wedge question is
404
- revisited.
414
+ in place — search **`[perf] parked`**. Uncomment to re-measure. The
415
+ `[Pipeline:timing]` summary line stays. Two provenance fields on the `nextCard`
416
+ log — `awaitedReplan` and `wedgeRuns` — are the instruments to re-enable first if
417
+ the wedge question is revisited.
405
418
 
406
419
  ## File reference
407
420
 
408
421
  | File | Relevant region |
409
422
  |------|-----------------|
410
423
  | `db/src/study/SessionController.ts` | queues, `requestReplan`, `_runReplan`, `nextCard` triggers, wedge-breaker |
411
- | `db/src/impl/couch/courseDB.ts` | `getWeightedCards`, `setEphemeralHints`, `createNavigator` (no cache) |
424
+ | `db/src/impl/couch/courseDB.ts` | `getWeightedCards`, `setEphemeralHints`, `createNavigator`, `readsLocal` |
412
425
  | `db/src/core/navigators/Pipeline.ts` | `getWeightedCards` (fetchLimit=500), `applyHints`, `hydrateTags`, `buildContext` |
413
426
  | `db/src/core/navigators/generators/types.ts` | `ReplanHints`, `GeneratorResult` |
414
427
  | `db/src/study/SourceMixer.ts` | `QuotaRoundRobinMixer` |
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "publishConfig": {
14
14
  "access": "public"
15
15
  },
16
- "version": "0.2.37",
16
+ "version": "0.3.1",
17
17
  "description": "Database layer for vue-skuilder",
18
18
  "main": "dist/index.cjs",
19
19
  "module": "dist/index.mjs",
@@ -69,7 +69,7 @@
69
69
  },
70
70
  "dependencies": {
71
71
  "@nilock2/pouchdb-authentication": "^1.0.2",
72
- "@vue-skuilder/common": "0.2.37",
72
+ "@vue-skuilder/common": "0.3.1",
73
73
  "cross-fetch": "^4.1.0",
74
74
  "moment": "^2.29.4",
75
75
  "pouchdb": "^9.0.0",
@@ -87,5 +87,5 @@
87
87
  "vite": "^8.0.0",
88
88
  "vitest": "^4.1.0"
89
89
  },
90
- "stableVersion": "0.2.37"
90
+ "stableVersion": "0.3.1"
91
91
  }
@@ -27,6 +27,12 @@ export interface CourseInfo {
27
27
  }
28
28
 
29
29
  export interface CourseDBInterface extends NavigationStrategyManager, StudyContentSource {
30
+ /**
31
+ * Whether reads go to a local replica rather than the server. Optional: only
32
+ * implementations with both (couch) report it; perf marks read it.
33
+ */
34
+ readonly readsLocal?: boolean;
35
+
30
36
  /**
31
37
  * Get course config
32
38
  */
@@ -7,6 +7,7 @@ import type { CardFilter, FilterContext } from './filters/types';
7
7
  import type { CardGenerator, GeneratorContext } from './generators/types';
8
8
  import type { GeneratorResult } from './generators/types';
9
9
  import { logger } from '../../util/logger';
10
+ import { perfMeasure } from '../../util/perfMarks';
10
11
  import { createOrchestrationContext, OrchestrationContext } from '../orchestration';
11
12
  import { captureRun, buildRunReport, registerPipelineForDebug, type GeneratorSummary, type FilterImpact } from './PipelineDebugger';
12
13
  import { diversityRerank } from './diversityRerank';
@@ -572,6 +573,13 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
572
573
  `(context=${(tContext - t0).toFixed(0)} generate=${(tGenerate - tContext).toFixed(0)} ` +
573
574
  `hydrate=${(tHydrate - tGenerate).toFixed(0)} filter=${(tFilter - tHydrate).toFixed(0)})`
574
575
  );
576
+ perfMeasure('sk:pipeline-run', t0, tFilter, {
577
+ context: Math.round(tContext - t0),
578
+ generate: Math.round(tGenerate - tContext),
579
+ hydrate: Math.round(tHydrate - tGenerate),
580
+ filter: Math.round(tFilter - tHydrate),
581
+ binding: this.course?.readsLocal === undefined ? 'unknown' : this.course.readsLocal ? 'local' : 'remote',
582
+ });
575
583
 
576
584
  // Toggle execution summary logging:
577
585
  const topScores = result.slice(0, 3).map((c) => c.score);
@@ -127,6 +127,9 @@ export class BaseUser implements UserDBInterface, DocumentUpdater {
127
127
  private updateQueue!: UpdateQueue;
128
128
 
129
129
  private _hydration: UserHydrationStatus = { state: 'not-required' };
130
+ /** See scanScheduledCards. Bumped by every write to scheduled reviews. */
131
+ private _scheduledScan: { generation: number; scan: Promise<ScheduledCard[]> } | null = null;
132
+ private _scheduledGeneration = 0;
130
133
  /** In-flight hydration, so concurrent callers can wait for a real answer. */
131
134
  private _hydrationPromise: Promise<void> | null = null;
132
135
  /**
@@ -441,20 +444,42 @@ Currently logged-in as ${this._username}.`
441
444
  *
442
445
  */
443
446
  public async getActiveCards() {
444
- const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
447
+ return (await this.scanScheduledCards()).map((doc) => ({
448
+ courseID: doc.courseId,
449
+ cardID: doc.cardId,
450
+ }));
451
+ }
445
452
 
446
- const reviews = await this.remoteDB.allDocs<ScheduledCard>({
447
- startkey: keys.startkey,
448
- endkey: keys.endkey,
449
- include_docs: true,
450
- });
453
+ /**
454
+ * The user's scheduled reviews (`card_review_*`), all of them: one `allDocs`
455
+ * scan shared by concurrent readers. A pipeline run's generators start
456
+ * together (`CompositeGenerator`), and each used to scan the range itself
457
+ * (`getActiveCards` from ELO and Prescribed, `getReviewstoDate` from SRS).
458
+ * Sharing only an in-flight scan keeps reads as fresh as before; a schedule
459
+ * or removal of a review starts a new scan for anyone reading after it.
460
+ * Docs are shared between callers: copy before mutating.
461
+ */
462
+ private scanScheduledCards(): Promise<ScheduledCard[]> {
463
+ const inFlight = this._scheduledScan;
464
+ if (inFlight && inFlight.generation === this._scheduledGeneration) return inFlight.scan;
451
465
 
452
- return reviews.rows.map((r) => {
453
- return {
454
- courseID: r.doc!.courseId,
455
- cardID: r.doc!.cardId,
456
- };
457
- });
466
+ const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
467
+ const entry = {
468
+ generation: this._scheduledGeneration,
469
+ scan: this.remoteDB
470
+ .allDocs<ScheduledCard>({
471
+ startkey: keys.startkey,
472
+ endkey: keys.endkey,
473
+ include_docs: true,
474
+ })
475
+ .then((res) => res.rows.map((row) => row.doc!)),
476
+ };
477
+ this._scheduledScan = entry;
478
+ const done = () => {
479
+ if (this._scheduledScan === entry) this._scheduledScan = null;
480
+ };
481
+ entry.scan.then(done, done);
482
+ return entry.scan;
458
483
  }
459
484
 
460
485
  public async getActivityRecords(): Promise<ActivityRecord[]> {
@@ -541,34 +566,28 @@ Currently logged-in as ${this._username}.`
541
566
  }
542
567
 
543
568
  private async getReviewstoDate(targetDate: Moment, course_id?: string) {
544
- const keys = getStartAndEndKeys(DocTypePrefixes[DocType.SCHEDULED_CARD]);
545
-
546
- const reviews = await this.remoteDB.allDocs<ScheduledCard>({
547
- startkey: keys.startkey,
548
- endkey: keys.endkey,
549
- include_docs: true,
550
- });
569
+ const reviews = await this.scanScheduledCards();
551
570
 
552
571
  log(
553
572
  `Fetching ${this._username}'s scheduled reviews${
554
573
  course_id ? ` for course ${course_id}` : ''
555
574
  }.`
556
575
  );
557
- return reviews.rows
558
- .filter((r) => {
559
- if (r.id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD])) {
576
+ return reviews
577
+ .filter((doc) => {
578
+ if (doc._id.startsWith(DocTypePrefixes[DocType.SCHEDULED_CARD])) {
560
579
  const date = moment.utc(
561
- r.id.substr(DocTypePrefixes[DocType.SCHEDULED_CARD].length),
580
+ doc._id.substr(DocTypePrefixes[DocType.SCHEDULED_CARD].length),
562
581
  REVIEW_TIME_FORMAT
563
582
  );
564
583
  if (targetDate.isAfter(date)) {
565
- if (course_id === undefined || r.doc!.courseId === course_id) {
584
+ if (course_id === undefined || doc.courseId === course_id) {
566
585
  return true;
567
586
  }
568
587
  }
569
588
  }
570
589
  })
571
- .map((r) => r.doc!);
590
+ .map((doc) => ({ ...doc }));
572
591
  }
573
592
 
574
593
  public async getReviewsForcast(daysCount: number, course_id?: string) {
@@ -1063,27 +1082,24 @@ Currently logged-in as ${this._username}.`
1063
1082
  // stringify the current record to make it writable to couchdb
1064
1083
  record.timeStamp = moment.utc(record.timeStamp).toString() as unknown as Moment;
1065
1084
 
1066
- try {
1067
- const cardHistory = await this.update<CardHistory<T>>(
1068
- cardHistoryID,
1069
- function (h: CardHistory<T>) {
1070
- h.records.push(record);
1071
- h.bestInterval = h.bestInterval || 0;
1072
- // Scheduling (SpacedRepetition.newQuestionInterval) re-derives
1073
- // lapses/streak from `records` on every call, so these persisted
1074
- // fields are informational — kept current so the stored doc reads
1075
- // truthfully when inspected outside a session.
1076
- if (areQuestionRecords(h)) {
1077
- h.lapses = getLapses(h.records);
1078
- h.streak = getStreak(h.records);
1079
- } else {
1080
- h.lapses = h.lapses || 0;
1081
- h.streak = h.streak || 0;
1082
- }
1083
- return h;
1084
- }
1085
- );
1086
-
1085
+ const append = (h: CardHistory<T>): CardHistory<T> => {
1086
+ h.records.push(record);
1087
+ h.bestInterval = h.bestInterval || 0;
1088
+ // Scheduling (SpacedRepetition.newQuestionInterval) re-derives
1089
+ // lapses/streak from `records` on every call, so these persisted
1090
+ // fields are informational — kept current so the stored doc reads
1091
+ // truthfully when inspected outside a session.
1092
+ if (areQuestionRecords(h)) {
1093
+ h.lapses = getLapses(h.records);
1094
+ h.streak = getStreak(h.records);
1095
+ } else {
1096
+ h.lapses = h.lapses || 0;
1097
+ h.streak = h.streak || 0;
1098
+ }
1099
+ return h;
1100
+ };
1101
+ const appendToExisting = async () => {
1102
+ const cardHistory = await this.update<CardHistory<T>>(cardHistoryID, append);
1087
1103
  // Convert timestamps to moment objects
1088
1104
  cardHistory.records = cardHistory.records.map<T>((record) => {
1089
1105
  const ret: T = {
@@ -1093,6 +1109,10 @@ Currently logged-in as ${this._username}.`
1093
1109
  return ret;
1094
1110
  });
1095
1111
  return cardHistory;
1112
+ };
1113
+
1114
+ try {
1115
+ return await appendToExisting();
1096
1116
  } catch (e) {
1097
1117
  const reason = e as PouchError;
1098
1118
  if (reason.status === 404) {
@@ -1109,6 +1129,11 @@ Currently logged-in as ${this._username}.`
1109
1129
  const putResult = await this.writeDB.put<CardHistory<T>>(initCardHistory);
1110
1130
  return { ...initCardHistory, _rev: putResult.rev };
1111
1131
  } catch (creationError) {
1132
+ // Another record for this card created the doc first (two first
1133
+ // records in flight at once): it exists now, so append to it.
1134
+ if ((creationError as PouchError).name === 'conflict') {
1135
+ return appendToExisting();
1136
+ }
1112
1137
  throw new Error(
1113
1138
  `Failed to create CardHistory for ${cardHistoryID}. Reason: ${creationError}`
1114
1139
  );
@@ -1174,6 +1199,7 @@ Currently logged-in as ${this._username}.`
1174
1199
  const deletePromises = duplicateDocIds.map(async (docId) => {
1175
1200
  try {
1176
1201
  const doc = await this.remoteDB.get(docId);
1202
+ this._scheduledGeneration++;
1177
1203
  await this.writeDB.remove(doc);
1178
1204
  log(`Successfully removed duplicate review: ${docId}`);
1179
1205
  } catch (error) {
@@ -1351,9 +1377,11 @@ Currently logged-in as ${this._username}.`
1351
1377
  scheduledFor: ScheduledCard['scheduledFor'];
1352
1378
  schedulingAgentId: ScheduledCard['schedulingAgentId'];
1353
1379
  }) {
1380
+ this._scheduledGeneration++;
1354
1381
  return scheduleCardReviewLocal(this.writeDB, review);
1355
1382
  }
1356
1383
  public async removeScheduledCardReview(reviewId: string): Promise<void> {
1384
+ this._scheduledGeneration++;
1357
1385
  return removeScheduledCardReviewLocal(this.writeDB, reviewId);
1358
1386
  }
1359
1387
 
@@ -1,6 +1,7 @@
1
1
  import pouch from './pouchdb-setup';
2
2
  import { getCourseDB } from '.';
3
3
  import { logger } from '../../util/logger';
4
+ import { perfMark } from '../../util/perfMarks';
4
5
  import type { CourseConfig } from '@vue-skuilder/common';
5
6
 
6
7
  // ============================================================================
@@ -236,6 +237,7 @@ export class CourseSyncService {
236
237
  entry.localDB = localDB;
237
238
  entry.status = { state: 'ready' };
238
239
  entry.readyPromise = null;
240
+ perfMark('sk:course-sync-ready', { courseId, from: 'marker' });
239
241
  logger.info(
240
242
  `[CourseSyncService] Using this device's replica of course ${courseId}; refreshing in the background`
241
243
  );
@@ -286,6 +288,12 @@ export class CourseSyncService {
286
288
  syncTimeMs,
287
289
  viewWarmTimeMs,
288
290
  };
291
+ perfMark('sk:course-sync-refreshed', {
292
+ courseId,
293
+ docs: result.docs_written,
294
+ syncTimeMs,
295
+ viewWarmTimeMs,
296
+ });
289
297
  logger.info(
290
298
  `[CourseSyncService] Background refresh of course ${courseId}: ` +
291
299
  `${result.docs_written} docs in ${syncTimeMs}ms, views ${viewWarmTimeMs}ms`
@@ -420,6 +428,11 @@ export class CourseSyncService {
420
428
 
421
429
  const result = await this.replicate(remoteDB, localDB);
422
430
  const syncTimeMs = Date.now() - syncStart;
431
+ perfMark('sk:course-sync-replicated', {
432
+ courseId,
433
+ docs: result.docs_written,
434
+ ms: syncTimeMs,
435
+ });
423
436
 
424
437
  logger.info(
425
438
  `[CourseSyncService] Replication complete for course ${courseId}: ` +
@@ -445,6 +458,7 @@ export class CourseSyncService {
445
458
  syncTimeMs,
446
459
  viewWarmTimeMs,
447
460
  };
461
+ perfMark('sk:course-sync-ready', { courseId, from: 'sync', viewWarmTimeMs });
448
462
  } catch (e) {
449
463
  const errorMsg = e instanceof Error ? e.message : String(e);
450
464
  logger.error(
@@ -552,8 +566,11 @@ export class CourseSyncService {
552
566
  try {
553
567
  localEpoch = await localDB.get<{ epoch: number }>('db-epoch');
554
568
  } catch {
555
- // Local doesn't have the epoch doc — stale
556
- return true;
569
+ // No epoch doc locally: a DB never written to (this device's first
570
+ // sync) has nothing to be stale; anything else (e.g. an interrupted
571
+ // earlier sync) is.
572
+ const info = await localDB.info();
573
+ return info.doc_count > 0 || !!info.update_seq;
557
574
  }
558
575
 
559
576
  return remoteEpoch.epoch !== localEpoch.epoch;
@@ -134,6 +134,11 @@ export class CourseDB implements CourseDBInterface {
134
134
  * values may be stale, so read-modify-write cycles must go through
135
135
  * the remote DB to avoid conflicts).
136
136
  */
137
+ /** Reads go to this device's replica (perf marks report it as the session's binding). */
138
+ public get readsLocal(): boolean {
139
+ return this.db !== this.remoteDB;
140
+ }
141
+
137
142
  constructor(id: string, userLookup: () => Promise<UserDBInterface>, localDB?: PouchDB.Database) {
138
143
  this.id = id;
139
144
  const remote = getCourseDB(this.id);