@vue-skuilder/db 0.3.0 → 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.
@@ -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.3.0",
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.3.0",
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.3.0"
90
+ "stableVersion": "0.3.1"
91
91
  }
@@ -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) {
@@ -1180,6 +1199,7 @@ Currently logged-in as ${this._username}.`
1180
1199
  const deletePromises = duplicateDocIds.map(async (docId) => {
1181
1200
  try {
1182
1201
  const doc = await this.remoteDB.get(docId);
1202
+ this._scheduledGeneration++;
1183
1203
  await this.writeDB.remove(doc);
1184
1204
  log(`Successfully removed duplicate review: ${docId}`);
1185
1205
  } catch (error) {
@@ -1357,9 +1377,11 @@ Currently logged-in as ${this._username}.`
1357
1377
  scheduledFor: ScheduledCard['scheduledFor'];
1358
1378
  schedulingAgentId: ScheduledCard['schedulingAgentId'];
1359
1379
  }) {
1380
+ this._scheduledGeneration++;
1360
1381
  return scheduleCardReviewLocal(this.writeDB, review);
1361
1382
  }
1362
1383
  public async removeScheduledCardReview(reviewId: string): Promise<void> {
1384
+ this._scheduledGeneration++;
1363
1385
  return removeScheduledCardReviewLocal(this.writeDB, reviewId);
1364
1386
  }
1365
1387