ronin-skillforce 0.0.0-stage → 0.1.0

package/studio/src/lib/repo/events.js

@@ -0,0 +1,239 @@
+/**
+ * Pure event vocabulary and row builders (D-01/D-02/D-03/D-05).
+ *
+ * No adapter, repo or I/O lives here: the repository validates through these helpers and the
+ * adapter only ever sees plain columns. Keeping the enum and the meta rules pure makes the
+ * frozen Wave 2 contract testable without storage.
+ */
+import { dayKey } from '../course.js';
+
+/** Closed meaningful-event enum, in the frozen D-01 order. */
+export const EVENT_KINDS = Object.freeze([
+  'quiz_completed',
+  'recall_completed',
+  'answer_sent_for_review',
+  'workspace_run',
+  'exercise_completed',
+  'capstone_checkpoint',
+]);
+
+/** Grouping surfaces (D-03). `import` is reserved for non-meaningful import bookkeeping. */
+export const EVENT_SURFACES = Object.freeze(['quiz', 'recall', 'tutor', 'workspace', 'capstone', 'import']);
+
+/** The one legal surface per meaningful kind. */
+export const KIND_SURFACE = Object.freeze({
+  quiz_completed: 'quiz',
+  recall_completed: 'recall',
+  answer_sent_for_review: 'tutor',
+  workspace_run: 'workspace',
+  exercise_completed: 'workspace',
+  capstone_checkpoint: 'capstone',
+});
+
+/** Closed allowlist of tables a revision may reference (D-06, T-05-08). */
+export const REVISION_FEEDBACK_TABLES = Object.freeze([
+  'chat_messages',
+  'run_results',
+  'capstone_submissions',
+  'quiz_attempts',
+]);
+
+/** Frozen revision link kinds (D-06). */
+export const REVISION_LINK_KINDS = Object.freeze(['explicit', 'inferred']);
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isRevisionLinkKind(value) {
+  return REVISION_LINK_KINDS.includes(value);
+}
+
+/**
+ * Throw before any adapter call when a caller-supplied table name is outside the allowlist.
+ * @param {string} table
+ * @returns {string}
+ */
+export function validateRevisionTable(table) {
+  if (!REVISION_FEEDBACK_TABLES.includes(table)) {
+    throw new Error(`Unknown revision table: ${table}`);
+  }
+  return table;
+}
+
+/**
+ * Build the exact `revision_links` row columns (D-06).
+ * @param {{ surface: string, courseId?: string|null, lessonId?: string|null, attemptTable?: string|null, attemptId?: string|null, feedbackTable: string, feedbackId: string, revisedTable: string, revisedId: string, linkKind: string }} input
+ * @returns {object}
+ */
+export function buildRevisionLink({
+  surface,
+  courseId = null,
+  lessonId = null,
+  attemptTable = null,
+  attemptId = null,
+  feedbackTable,
+  feedbackId,
+  revisedTable,
+  revisedId,
+  linkKind,
+} = {}) {
+  if (!EVENT_SURFACES.includes(surface)) throw new Error(`Unknown revision surface: ${surface}`);
+  if (!isRevisionLinkKind(linkKind)) throw new Error(`Unknown revision link kind: ${linkKind}`);
+  validateRevisionTable(feedbackTable);
+  validateRevisionTable(revisedTable);
+  if (attemptTable != null) validateRevisionTable(attemptTable);
+  return {
+    surface,
+    course_id: courseId ?? null,
+    lesson_id: lessonId ?? null,
+    attempt_table: attemptTable ?? null,
+    attempt_id: attemptId ?? null,
+    feedback_table: feedbackTable,
+    feedback_id: feedbackId,
+    revised_table: revisedTable,
+    revised_id: revisedId,
+    link_kind: linkKind,
+  };
+}
+
+/**
+ * @param {string} kind
+ * @returns {string}
+ */
+export function validateEventKind(kind) {
+  if (!EVENT_KINDS.includes(kind)) throw new Error(`Unknown event kind: ${kind}`);
+  return kind;
+}
+
+/**
+ * @param {string} kind
+ * @param {string} surface
+ * @returns {string}
+ */
+export function validateEventSurface(kind, surface) {
+  validateEventKind(kind);
+  if (!EVENT_SURFACES.includes(surface)) throw new Error(`Unknown event surface: ${surface}`);
+  if (surface !== KIND_SURFACE[kind]) {
+    throw new Error(`Event kind "${kind}" must use surface "${KIND_SURFACE[kind]}"`);
+  }
+  return surface;
+}
+
+/**
+ * Unwrap the inner checks array. `CodeWorkspace` always sends `{ checks, snapshot }`, while CLI
+ * imports and legacy rows may send a bare array (P1).
+ * @param {any} checks
+ * @returns {any[]}
+ */
+export function checksList(checks) {
+  if (Array.isArray(checks)) return checks;
+  if (checks && Array.isArray(checks.checks)) return checks.checks;
+  return [];
+}
+
+const NUMBER = Object.freeze({ type: 'number' });
+
+function enumSpec(values) {
+  return Object.freeze({ type: 'enum', values: Object.freeze(values) });
+}
+
+/** Allowed meta keys and value shapes per kind (D-05). */
+export const META_WHITELIST = Object.freeze({
+  quiz_completed: Object.freeze({ total: NUMBER, score: NUMBER, answered: NUMBER }),
+  recall_completed: Object.freeze({ grade: Object.freeze({ type: 'number', min: 0, max: 3 }) }),
+  answer_sent_for_review: Object.freeze({ mode: enumSpec(['check_answer', 'review']) }),
+  workspace_run: Object.freeze({
+    runner: enumSpec(['browser', 'local']),
+    checks_total: NUMBER,
+    exit_code: NUMBER,
+  }),
+  exercise_completed: Object.freeze({
+    runner: enumSpec(['browser', 'local']),
+    checks_total: NUMBER,
+    checks_passed: NUMBER,
+  }),
+  capstone_checkpoint: Object.freeze({
+    source: enumSpec(['in_app', 'external']),
+    attempt: NUMBER,
+  }),
+});
+
+const META_MAX_LENGTH = 512;
+
+/**
+ * Drop null/undefined keys so optional scores and exit codes never reach validation.
+ * @param {Record<string, any>|null|undefined} meta
+ * @returns {Record<string, any>}
+ */
+export function compactMeta(meta = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(meta || {})) {
+    if (value !== null && value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Reject any meta that could carry learner content: unknown keys, non-finite numbers, arrays,
+ * free strings, booleans and anything over the 512-character serialized cap (D-05/P8).
+ * @param {string} kind
+ * @param {Record<string, any>} meta already compacted by `compactMeta`
+ * @returns {Record<string, any>}
+ */
+export function validateMeta(kind, meta = {}) {
+  validateEventKind(kind);
+  const whitelist = META_WHITELIST[kind];
+  const serialized = JSON.stringify(meta ?? {});
+  if (serialized.length > META_MAX_LENGTH) {
+    throw new Error(`Event meta exceeds ${META_MAX_LENGTH} characters`);
+  }
+  for (const [key, value] of Object.entries(meta || {})) {
+    if (!Object.prototype.hasOwnProperty.call(whitelist, key)) {
+      throw new Error(`Unknown meta key "${key}" for event kind "${kind}"`);
+    }
+    const spec = whitelist[key];
+    if (Array.isArray(value)) throw new Error(`Meta "${key}" must not be an array`);
+    if (spec.type === 'number') {
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Meta "${key}" must be a finite number`);
+      }
+      if (spec.min !== undefined && value < spec.min) throw new Error(`Meta "${key}" is below ${spec.min}`);
+      if (spec.max !== undefined && value > spec.max) throw new Error(`Meta "${key}" is above ${spec.max}`);
+    } else if (spec.type === 'enum') {
+      if (typeof value !== 'string' || !spec.values.includes(value)) {
+        throw new Error(`Meta "${key}" must be one of: ${spec.values.join(', ')}`);
+      }
+    } else {
+      throw new Error(`Meta "${key}" has an unsupported type`);
+    }
+  }
+  return meta;
+}
+
+/**
+ * @param {{ kind: string, surface: string, courseId?: string|null, lessonId?: string|null, refId?: string|null, meta?: object, now?: Date|string }} input
+ * @returns {{ day: string, kind: string, surface: string, course_id: string|null, lesson_id: string|null, ref_id: string|null, meta_json: string }}
+ */
+export function buildEventRow({
+  kind,
+  surface,
+  courseId = null,
+  lessonId = null,
+  refId = null,
+  meta = {},
+  now = new Date(),
+} = {}) {
+  validateEventSurface(kind, surface);
+  const compact = compactMeta(meta);
+  validateMeta(kind, compact);
+  return {
+    day: dayKey(now),
+    kind,
+    surface,
+    course_id: courseId ?? null,
+    lesson_id: lessonId ?? null,
+    ref_id: refId ?? null,
+    meta_json: JSON.stringify(compact),
+  };
+}

package/studio/src/lib/repo/idb-adapter.js

@@ -0,0 +1,226 @@
+/**
+ * IndexedDB StorageAdapter.
+ *
+ * One object store per table in schema.js, one index per indexed field. All filtering is done
+ * in JS after a getAll so the semantics are byte-for-byte identical to the memory and (future)
+ * remote adapters — the indexes exist for the SQLite/D1 side and for future query optimisation.
+ *
+ * When IndexedDB is unavailable (private mode, locked-down webview, vitest without
+ * fake-indexeddb) every method transparently delegates to the in-memory adapter and
+ * `info().kind` reports 'memory'.
+ */
+import { TABLE_NAMES, SCHEMA_VERSION, tableSpec, assertIndexedField } from './schema.js';
+import { createMemoryAdapter, validateDump, APP_ID } from './memory-adapter.js';
+
+const DB_NAME = 'professor-studio';
+/** The IndexedDB database name (DELETE it to remove the browser copy — STORE-03). */
+export const IDB_DB_NAME = DB_NAME;
+// v1 = the seed db.js (courses/cards/meta); v2 = the normalized schema; v3 adds the CLI-import
+// `external_id` indexes; v4 adds the capstone tables (Phase 33); v5 adds the beta-loop tables
+// `learning_events`, `revision_links` and `beta_profile` (Phase 5); v6 adds the interactive-exercise
+// tables `exercises` and `exercise_attempts`. Bumping the version is what makes `onupgradeneeded`
+// run for browsers that already have an older database — otherwise the new stores/indexes would
+// never be created and `exportAll`/`list` would throw `NotFoundError`.
+export const DB_VERSION = 6;
+
+/**
+ * Bring an open (upgrading) database in line with schema.js: create missing stores AND add any
+ * missing index to stores that already exist. Runs inside the `onupgradeneeded` versionchange
+ * transaction, so it must handle both fresh databases and upgrades from any older version.
+ */
+function createStores(db, tx) {
+  for (const table of TABLE_NAMES) {
+    const spec = tableSpec(table);
+    let os;
+    if (!db.objectStoreNames.contains(table)) {
+      os = db.createObjectStore(table, { keyPath: spec.id });
+    } else {
+      // Existing store: keep it and its rows, only backfill indexes added since it was created.
+      os = tx.objectStore(table);
+    }
+    for (const field of spec.indexes) {
+      if (!os.indexNames.contains(field)) os.createIndex(field, field, { unique: false });
+    }
+  }
+  if (db.objectStoreNames.contains('meta')) db.deleteObjectStore('meta'); // legacy seed store
+}
+
+function openDb(dbName) {
+  if (typeof indexedDB === 'undefined') return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let req;
+    try {
+      req = indexedDB.open(dbName, DB_VERSION);
+    } catch {
+      resolve(null);
+      return;
+    }
+    req.onupgradeneeded = () => {
+      try {
+        createStores(req.result, req.transaction);
+      } catch {
+        // migration failure aborts the open; onerror resolves null and we fall back to memory
+      }
+    };
+    req.onsuccess = () => {
+      const db = req.result;
+      db.onversionchange = () => db.close();
+      resolve(db);
+    };
+    req.onerror = () => resolve(null);
+    req.onblocked = () => resolve(null);
+  });
+}
+
+function requestToPromise(req) {
+  return new Promise((resolve, reject) => {
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function txDone(tx) {
+  return new Promise((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+    tx.onabort = () => reject(tx.error);
+  });
+}
+
+/**
+ * @param {{ dbName?: string }} [opts]
+ * @returns {import('./remote-adapter.js').StorageAdapter & { label: string }}
+ */
+export function createIdbAdapter({ dbName = DB_NAME } = {}) {
+  const fallback = createMemoryAdapter();
+  let persistent = false;
+  let persistRequested = false;
+
+  const ready = openDb(dbName).then(async (db) => {
+    if (!db) return null;
+    try {
+      const storage = globalThis.navigator?.storage;
+      if (storage && !persistRequested) {
+        persistRequested = true;
+        persistent = (await storage.persist?.()) ?? (await storage.persisted?.()) ?? false;
+      }
+    } catch {
+      persistent = false;
+    }
+    return db;
+  });
+
+  async function getAll(table) {
+    const db = await ready;
+    if (!db) return fallback.list(table, { includeDeleted: true });
+    const tx = db.transaction(table, 'readonly');
+    const rows = (await requestToPromise(tx.objectStore(table).getAll())) || [];
+    await txDone(tx);
+    return rows;
+  }
+
+  return {
+    label: 'indexeddb',
+    async get(table, id) {
+      const db = await ready;
+      if (!db) return fallback.get(table, id);
+      const tx = db.transaction(table, 'readonly');
+      const row = await requestToPromise(tx.objectStore(table).get(id));
+      await txDone(tx);
+      return row ?? null;
+    },
+    async put(table, row) {
+      const db = await ready;
+      if (!db) return fallback.put(table, row);
+      if (row?.[tableSpec(table).id] === undefined) throw new Error(`Row for "${table}" is missing its id`);
+      const tx = db.transaction(table, 'readwrite');
+      tx.objectStore(table).put(row);
+      await txDone(tx);
+      return { ...row };
+    },
+    async putMany(table, rows) {
+      const db = await ready;
+      if (!db) return fallback.putMany(table, rows);
+      const tx = db.transaction(table, 'readwrite');
+      const os = tx.objectStore(table);
+      for (const row of rows || []) os.put(row);
+      await txDone(tx);
+      return (rows || []).map((r) => ({ ...r }));
+    },
+    async list(table, opts = {}) {
+      if (opts.where) for (const f of Object.keys(opts.where)) assertIndexedField(table, f);
+      const rows = await getAll(table);
+      return filterRows(rows, opts);
+    },
+    async softDelete(table, id) {
+      const db = await ready;
+      if (!db) return fallback.softDelete(table, id);
+      const tx = db.transaction(table, 'readwrite');
+      const os = tx.objectStore(table);
+      const row = await requestToPromise(os.get(id));
+      if (!row) {
+        await txDone(tx);
+        return null;
+      }
+      const next = { ...row, deleted_at: new Date().toISOString() };
+      os.put(next);
+      await txDone(tx);
+      return next;
+    },
+    async exportAll() {
+      const tables = {};
+      for (const table of TABLE_NAMES) tables[table] = await getAll(table);
+      return {
+        app: APP_ID,
+        version: 1,
+        schemaVersion: SCHEMA_VERSION,
+        exportedAt: new Date().toISOString(),
+        tables,
+      };
+    },
+    async importAll(dump) {
+      validateDump(dump);
+      const db = await ready;
+      if (!db) return fallback.importAll(dump);
+      let imported = 0;
+      for (const table of TABLE_NAMES) {
+        const rows = dump.tables[table] || [];
+        if (!rows.length) continue;
+        const tx = db.transaction(table, 'readwrite');
+        const os = tx.objectStore(table);
+        for (const row of rows) os.put(row);
+        await txDone(tx);
+        imported += rows.length;
+      }
+      return { imported };
+    },
+    async info() {
+      const db = await ready;
+      return db ? { kind: 'indexeddb', persistent } : { kind: 'memory', persistent: false };
+    },
+    async clearAll() {
+      const db = await ready;
+      if (!db) return fallback.clearAll();
+      for (const table of TABLE_NAMES) {
+        const tx = db.transaction(table, 'readwrite');
+        tx.objectStore(table).clear();
+        await txDone(tx);
+      }
+      return { cleared: true };
+    },
+  };
+}
+
+/** Shared list filtering — identical across adapters. */
+export function filterRows(rows, { where, includeDeleted = false, orderBy, limit } = {}) {
+  let out = rows || [];
+  if (where) for (const key of Object.keys(where)) out = out.filter((r) => r[key] === where[key]);
+  if (!includeDeleted) out = out.filter((r) => !r.deleted_at);
+  if (orderBy) {
+    const field = typeof orderBy === 'string' ? orderBy : orderBy.field;
+    const dir = typeof orderBy === 'string' ? 1 : orderBy.dir === 'desc' ? -1 : 1;
+    out = [...out].sort((a, b) => (a[field] === b[field] ? 0 : (a[field] > b[field] ? 1 : -1) * dir));
+  }
+  if (typeof limit === 'number') out = out.slice(0, limit);
+  return out.map((r) => ({ ...r }));
+}