@vue-skuilder/db 0.2.31 → 0.2.32

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 (45) hide show
  1. package/dist/{contentSource-Doh1aVBJ.d.cts → contentSource-CTQ4kWhR.d.cts} +22 -0
  2. package/dist/{contentSource-DMduBjDC.d.ts → contentSource-JmWYu8IK.d.ts} +22 -0
  3. package/dist/core/index.d.cts +3 -3
  4. package/dist/core/index.d.ts +3 -3
  5. package/dist/core/index.js +50 -3
  6. package/dist/core/index.js.map +1 -1
  7. package/dist/core/index.mjs +50 -3
  8. package/dist/core/index.mjs.map +1 -1
  9. package/dist/{dataLayerProvider-BW1CBAbb.d.cts → dataLayerProvider-DfI_KYAe.d.cts} +1 -1
  10. package/dist/{dataLayerProvider-Cxfe4nSK.d.ts → dataLayerProvider-rlLE2Mf-.d.ts} +1 -1
  11. package/dist/diagnostics/index.d.cts +2 -2
  12. package/dist/diagnostics/index.d.ts +2 -2
  13. package/dist/diagnostics/index.js +12 -0
  14. package/dist/diagnostics/index.js.map +1 -1
  15. package/dist/diagnostics/index.mjs +12 -0
  16. package/dist/diagnostics/index.mjs.map +1 -1
  17. package/dist/impl/couch/index.d.cts +8 -2
  18. package/dist/impl/couch/index.d.ts +8 -2
  19. package/dist/impl/couch/index.js +50 -3
  20. package/dist/impl/couch/index.js.map +1 -1
  21. package/dist/impl/couch/index.mjs +50 -3
  22. package/dist/impl/couch/index.mjs.map +1 -1
  23. package/dist/impl/static/index.d.cts +2 -2
  24. package/dist/impl/static/index.d.ts +2 -2
  25. package/dist/impl/static/index.js +50 -3
  26. package/dist/impl/static/index.js.map +1 -1
  27. package/dist/impl/static/index.mjs +50 -3
  28. package/dist/impl/static/index.mjs.map +1 -1
  29. package/dist/index.d.cts +5 -3
  30. package/dist/index.d.ts +5 -3
  31. package/dist/index.js +63 -4
  32. package/dist/index.js.map +1 -1
  33. package/dist/index.mjs +63 -4
  34. package/dist/index.mjs.map +1 -1
  35. package/package.json +3 -3
  36. package/src/core/navigators/Pipeline.ts +13 -2
  37. package/src/core/navigators/PipelineAssembler.ts +2 -0
  38. package/src/core/navigators/PipelineDebugger.ts +12 -0
  39. package/src/core/navigators/defaults.ts +4 -1
  40. package/src/core/types/studySession.ts +11 -1
  41. package/src/core/versionStamps.ts +66 -0
  42. package/src/diagnostics/text.ts +13 -0
  43. package/src/factory.ts +6 -0
  44. package/src/study/SessionController.ts +3 -0
  45. package/tsup.config.ts +5 -0
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "0.2.31",
7
+ "version": "0.2.32",
8
8
  "description": "Database layer for vue-skuilder",
9
9
  "main": "dist/index.js",
10
10
  "module": "dist/index.mjs",
@@ -60,7 +60,7 @@
60
60
  },
61
61
  "dependencies": {
62
62
  "@nilock2/pouchdb-authentication": "^1.0.2",
63
- "@vue-skuilder/common": "0.2.31",
63
+ "@vue-skuilder/common": "0.2.32",
64
64
  "cross-fetch": "^4.1.0",
65
65
  "moment": "^2.29.4",
66
66
  "pouchdb": "^9.0.0",
@@ -75,5 +75,5 @@
75
75
  "vite": "^8.0.0",
76
76
  "vitest": "^4.1.0"
77
77
  },
78
- "stableVersion": "0.2.31"
78
+ "stableVersion": "0.2.32"
79
79
  }
@@ -295,6 +295,12 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
295
295
  */
296
296
  private _cachedOrchestration: OrchestrationContext | null = null;
297
297
 
298
+ /**
299
+ * Hash of the strategy docs this pipeline was assembled from (see
300
+ * versionStamps.ts), set by whoever builds it. Stamped on every run.
301
+ */
302
+ strategyHash?: string;
303
+
298
304
  /**
299
305
  * Persistent tag cache. Maps cardId → tag names.
300
306
  *
@@ -586,7 +592,8 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
586
592
 
587
593
  // Capture run for debug API
588
594
  try {
589
- const courseName = await this.course?.getCourseConfig().then((c) => c.name).catch(() => undefined);
595
+ const courseConfig = await this.course?.getCourseConfig().catch(() => undefined);
596
+ const courseName = courseConfig?.name;
590
597
  // Pass the full post-filter sorted array; buildRunReport retains all
591
598
  // selected cards plus the top-N highest-scoring near-misses and
592
599
  // summarizes the discarded tail (see DISCARDED_KEEP_TOP). This keeps
@@ -607,7 +614,11 @@ export class Pipeline extends ContentNavigator implements PipelineForecaster {
607
614
  scoredCards,
608
615
  regulators
609
616
  );
610
- captureRun(report);
617
+ const versions = {
618
+ ...(this.strategyHash ? { strategies: this.strategyHash } : {}),
619
+ ...(courseConfig?.contentVersion ? { content: courseConfig.contentVersion } : {}),
620
+ };
621
+ captureRun({ ...report, ...(Object.keys(versions).length ? { versions } : {}) });
611
622
  } catch (e) {
612
623
  logger.debug(`[Pipeline] Failed to capture debug run: ${e}`);
613
624
  }
@@ -9,6 +9,7 @@ import type { CourseDBInterface } from '../interfaces/courseDB';
9
9
  import type { UserDBInterface } from '../interfaces/userDB';
10
10
  import CompositeGenerator from './generators/CompositeGenerator';
11
11
  import { planPipeline } from './pipelinePlan';
12
+ import { strategyHash } from '../versionStamps';
12
13
 
13
14
  // ============================================================================
14
15
  // PIPELINE ASSEMBLER
@@ -162,6 +163,7 @@ export class PipelineAssembler {
162
163
 
163
164
  // Build pipeline
164
165
  const pipeline = new Pipeline(generator, filters, user, course);
166
+ pipeline.strategyHash = strategyHash(strategies);
165
167
 
166
168
  logger.debug(
167
169
  `[PipelineAssembler] Assembled pipeline with ${generatorStrategies.length} generator(s) and ${filters.length} filter(s)`
@@ -78,6 +78,12 @@ export interface FilterImpact {
78
78
  removed: number;
79
79
  }
80
80
 
81
+ /** A run's version stamps. Either may be absent: no strategy hash, or no content version set. */
82
+ export interface RunVersions {
83
+ strategies?: string;
84
+ content?: string;
85
+ }
86
+
81
87
  /** One card as retained in a {@link PipelineRunReport}. */
82
88
  export interface RunReportCard {
83
89
  cardId: string;
@@ -159,6 +165,12 @@ export interface PipelineRunReport {
159
165
  /** The regulator stage's readings: each class's pressure and the multiplier it got. */
160
166
  regulators?: RegulatorReading[];
161
167
 
168
+ /**
169
+ * What this run ran on (see versionStamps.ts): the hash of the strategy docs
170
+ * the pipeline was assembled from, and the course's content version.
171
+ */
172
+ versions?: RunVersions;
173
+
162
174
  /**
163
175
  * Summary of the discarded tail of the candidate pool — cards that were
164
176
  * generated and scored but neither selected nor retained in `cards`.
@@ -6,6 +6,7 @@ import SRSNavigator from './generators/srs';
6
6
  import EloDistanceFilter, { DEFAULT_ELO_DISTANCE_CONFIG } from './filters/eloDistance';
7
7
  import type { ContentNavigationStrategyData } from '../types/contentNavigationStrategy';
8
8
  import { DocType } from '../types/types-legacy';
9
+ import { DEFAULT_STRATEGY_HASH } from '../versionStamps';
9
10
  import type { CourseDBInterface, UserDBInterface } from '../interfaces';
10
11
 
11
12
  /**
@@ -104,5 +105,7 @@ export function createDefaultPipeline(
104
105
  createDefaultEloDistanceStrategy(courseId)
105
106
  );
106
107
 
107
- return new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
108
+ const pipeline = new Pipeline(compositeGenerator, [eloDistanceFilter], user, course);
109
+ pipeline.strategyHash = DEFAULT_STRATEGY_HASH;
110
+ return pipeline;
108
111
  }
@@ -1,6 +1,6 @@
1
1
  import { DocType, DocTypePrefixes } from './types-legacy';
2
2
  import type { ReplanHints } from '../navigators/generators/types';
3
- import type { GeneratorSummary, FilterImpact } from '../navigators/PipelineDebugger';
3
+ import type { GeneratorSummary, FilterImpact, RunVersions } from '../navigators/PipelineDebugger';
4
4
  import type { RegulatorReading } from '../navigators/regulators';
5
5
  import type { StrategyContribution } from '../navigators';
6
6
 
@@ -38,6 +38,14 @@ export interface StudySessionDoc {
38
38
  initHints?: ReplanHints | null;
39
39
  };
40
40
 
41
+ /**
42
+ * The code this session ran on: the framework's version (`'dev'` when run
43
+ * from source) and the host app's, if it reported one (`appVersion` in the
44
+ * data-layer config). Strategy and content versions are stamped per run.
45
+ * Absent on sessions recorded before this shipped.
46
+ */
47
+ versions?: { framework: string; app?: string };
48
+
41
49
  /** Queue depths after the bootstrap run, before the first draw. */
42
50
  initialQueues: { supplyQ: number; failedQ: number };
43
51
 
@@ -122,6 +130,8 @@ export interface StudySessionRunSummary {
122
130
  };
123
131
  /** The regulator stage's readings: review mass and intake, each with its multiplier (0.2.29+). */
124
132
  regulators?: RegulatorReading[];
133
+ /** What the run ran on: the strategy docs' hash and the course's content version. */
134
+ versions?: RunVersions;
125
135
  }
126
136
 
127
137
  /** A card as persisted on a run. `origin` is as counted in `newSelected`/`reviewsSelected`. */
@@ -0,0 +1,66 @@
1
+ import type { ContentNavigationStrategyData } from './types/contentNavigationStrategy';
2
+
3
+ // ============================================================================
4
+ // VERSION STAMPS
5
+ // ============================================================================
6
+ //
7
+ // What a study session ran on, written into its records so a change shows up
8
+ // in them: framework and app releases on the session doc, the strategy docs
9
+ // and the content version on each pipeline run (either can change mid-session).
10
+ //
11
+ // ============================================================================
12
+
13
+ declare const __SKUILDER_DB_VERSION__: string | undefined;
14
+
15
+ /** This build's @vue-skuilder/db version, set at build time; `'dev'` when run from source. */
16
+ export const FRAMEWORK_VERSION: string =
17
+ typeof __SKUILDER_DB_VERSION__ === 'string' ? __SKUILDER_DB_VERSION__ : 'dev';
18
+
19
+ let hostAppVersion: string | undefined;
20
+
21
+ /** Record the host app's version (the data layer's `appVersion` option). */
22
+ export function setAppVersion(version: string): void {
23
+ hostAppVersion = version;
24
+ }
25
+
26
+ /** What a session stamps: the framework's version, and the app's if it reported one. */
27
+ export function sessionVersions(): { framework: string; app?: string } {
28
+ return { framework: FRAMEWORK_VERSION, ...(hostAppVersion ? { app: hostAppVersion } : {}) };
29
+ }
30
+
31
+ /** Stamp for a pipeline built without strategy docs (the built-in default). */
32
+ export const DEFAULT_STRATEGY_HASH = 'default';
33
+
34
+ /** JSON with object keys sorted, so equal docs stringify equally. */
35
+ function stableStringify(value: unknown): string {
36
+ if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
37
+ if (value && typeof value === 'object') {
38
+ const entries = Object.entries(value as Record<string, unknown>)
39
+ .filter(([, v]) => v !== undefined)
40
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
41
+ return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
42
+ }
43
+ return JSON.stringify(value);
44
+ }
45
+
46
+ /**
47
+ * A short hash of a course's strategy docs: 8 hex chars, FNV-1a over their
48
+ * content (not `_rev`, which a redeploy of the same content also changes).
49
+ * Equal for equal strategy sets, whatever order they load in.
50
+ */
51
+ export function strategyHash(strategies: readonly ContentNavigationStrategyData[]): string {
52
+ if (strategies.length === 0) return DEFAULT_STRATEGY_HASH;
53
+ const text = strategies
54
+ .map((s) => {
55
+ const { _rev: _ignored, ...rest } = s as ContentNavigationStrategyData & { _rev?: string };
56
+ return stableStringify(rest);
57
+ })
58
+ .sort()
59
+ .join('\n');
60
+ let h = 0x811c9dc5;
61
+ for (let i = 0; i < text.length; i++) {
62
+ h ^= text.charCodeAt(i);
63
+ h = Math.imul(h, 0x01000193);
64
+ }
65
+ return (h >>> 0).toString(16).padStart(8, '0');
66
+ }
@@ -85,6 +85,11 @@ export function runText(run: StudySessionRunSummary): string {
85
85
  (run.generatedCount > 0 && run.finalCount === 0 ? ' ⚠ nothing survived' : '')
86
86
  );
87
87
  if (typeof run.userElo === 'number') L.push(` userElo: ${Math.round(run.userElo)}`);
88
+ if (run.versions) {
89
+ L.push(
90
+ ` versions: strategies ${run.versions.strategies ?? '—'} · content ${run.versions.content ?? '—'}`
91
+ );
92
+ }
88
93
  if (run.generators?.length) {
89
94
  L.push(' generators:');
90
95
  for (const g of run.generators) {
@@ -181,6 +186,8 @@ export function sessionText(
181
186
  L.push(' (gate: not ready yet; signal: preference). regulators: the pressure on each class,');
182
187
  L.push(' review mass (due reviews by value) and intake (hours since a new card).');
183
188
  L.push(' hints: the ReplanHints the navigator was told (_label = replan reason).');
189
+ L.push(" versions: the strategy docs' hash and the content version the run ran on; the");
190
+ L.push(" headline's are the framework and app versions. A change between runs marks a deploy.");
184
191
  L.push(' selection: the chosen cards and top runners-up. "next new in line" / "top-generated');
185
192
  L.push(' new (sunk)": the unselected new cards worth explaining, with each score change.');
186
193
  L.push(' Each card reads (origin, source). origin: review = a scheduled review, new = anything');
@@ -194,6 +201,12 @@ export function sessionText(
194
201
  L.push('## Headline');
195
202
  L.push(`- status: ${doc.status}`);
196
203
  L.push(`- start: ${doc.startTime}${doc.endTime ? ` · end: ${doc.endTime}` : ''}`);
204
+ if (doc.versions) {
205
+ L.push(
206
+ `- versions: framework ${doc.versions.framework}` +
207
+ (doc.versions.app ? ` · app ${doc.versions.app}` : '')
208
+ );
209
+ }
197
210
  L.push(
198
211
  `- clock: ${s.durationSeconds ?? '—'}s of ${doc.plannedSeconds}s planned` +
199
212
  (doc.tally ? ` · ${doc.tally.secondsRemaining}s remaining` : '')
package/src/factory.ts CHANGED
@@ -5,6 +5,7 @@ import { BaseUser } from './impl/common';
5
5
  import { logger } from './util/logger';
6
6
  import { StaticCourseManifest } from './util/packer/types';
7
7
  import { initializeNavigatorRegistry } from './core/navigators';
8
+ import { setAppVersion } from './core/versionStamps';
8
9
 
9
10
  const NOT_SET = 'NOT_SET' as const;
10
11
 
@@ -30,6 +31,8 @@ export interface DataLayerConfig {
30
31
  options: {
31
32
  staticContentPath?: string; // Path to static content JSON files
32
33
  localStoragePrefix?: string; // Prefix for IndexedDB storage names
34
+ /** The host app's version (e.g. a git SHA), stamped on every study session it records. */
35
+ appVersion?: string;
33
36
  manifests?: Record<string, StaticCourseManifest>; // Course manifests for static mode
34
37
  COUCHDB_SERVER_URL?: string;
35
38
  COUCHDB_SERVER_PROTOCOL?: string;
@@ -71,6 +74,9 @@ export async function initializeDataLayer(config: DataLayerConfig): Promise<Data
71
74
  if (config.options.localStoragePrefix) {
72
75
  ENV.LOCAL_STORAGE_PREFIX = config.options.localStoragePrefix;
73
76
  }
77
+ if (config.options.appVersion) {
78
+ setAppVersion(config.options.appVersion);
79
+ }
74
80
 
75
81
  if (config.type === 'couch') {
76
82
  if (!config.options.COUCHDB_SERVER_URL || !config.options.COUCHDB_SERVER_PROTOCOL) {
@@ -39,6 +39,7 @@ import type { PipelineRunReport, RunReportCard } from '@db/core/navigators';
39
39
  import { ReplanHints } from '@db/core/navigators/generators/types';
40
40
  import { mergeHints } from '@db/core/navigators/Pipeline';
41
41
  import type { RegulatorReading } from '@db/core/navigators/regulators';
42
+ import { sessionVersions } from '@db/core/versionStamps';
42
43
  import { SourceMixer, QuotaRoundRobinMixer, SourceBatch } from './SourceMixer';
43
44
  import { captureMixerRun } from './MixerDebugger';
44
45
  import { startSessionTracking, recordCardPresentation, snapshotQueues, endSessionTracking, clearStaleSessionDebugState } from './SessionDebugger';
@@ -649,6 +650,7 @@ export class SessionController<TView = unknown> extends Loggable {
649
650
  cards: persistedRunCards(run),
650
651
  ...(run.unselectedNew ? { unselectedNew: persistedUnselectedNew(run.unselectedNew) } : {}),
651
652
  ...(run.regulators ? { regulators: run.regulators.map(persistedReading) } : {}),
653
+ ...(run.versions ? { versions: run.versions } : {}),
652
654
  });
653
655
  }
654
656
  }
@@ -689,6 +691,7 @@ export class SessionController<TView = unknown> extends Loggable {
689
691
  sourceCount: this.sources.length,
690
692
  initHints: this._sessionHints,
691
693
  },
694
+ versions: sessionVersions(),
692
695
  initialQueues: { supplyQ: this.supplyQ.length, failedQ: this.failedQ.length },
693
696
  runs: [...this._runLog],
694
697
  stateAtStart: await this._captureState('start'),
package/tsup.config.ts CHANGED
@@ -1,5 +1,8 @@
1
+ import { readFileSync } from 'node:fs';
1
2
  import { defineConfig } from 'tsup';
2
3
 
4
+ const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf-8'));
5
+
3
6
  export default defineConfig({
4
7
  entry: [
5
8
  'src/index.ts',
@@ -15,6 +18,8 @@ export default defineConfig({
15
18
  splitting: false,
16
19
  sourcemap: true,
17
20
  clean: true,
21
+ // Session records stamp the framework version (core/versionStamps.ts).
22
+ define: { __SKUILDER_DB_VERSION__: JSON.stringify(version) },
18
23
  outExtension: ({ format }) => ({
19
24
  js: format === 'esm' ? '.mjs' : '.js',
20
25
  }),