Define session status model (#14)

Define a product-level session status model for notes.

- Normalize listener metadata and STT chunk status into sessionStatus
- Store aggregate session status in the notes database for list views
- Treat starting sessions as recording rather than finalizing
- Avoid sync STT ledger reads while building note summaries

Validation:
- npm run desktop:check
- git diff --check HEAD~2..HEAD

Author: qyinm

apps/desktop/main.cjs

@@ -32,7 +32,7 @@ const {
 const APP_DISPLAY_NAME = "MirrorNote";
 const ELECTRON_SETTINGS_FILE_NAME = "electron-settings.json";
 const NOTES_DATABASE_FILE_NAME = "notes.sqlite";
-const NOTES_DATABASE_SCHEMA_VERSION = 3;
+const NOTES_DATABASE_SCHEMA_VERSION = 4;
 const MENU_BAR_ICON_SIZE = 18;
 const MENU_BAR_ICON_IDLE_FILE_NAME = "menu-bar-icon-source.png";
 const MENU_BAR_ICON_RECORDING_BRIGHT_FILE_NAME = "menu-bar-icon-recording-bright.png";
@@ -1358,6 +1358,77 @@ function listenerSessionFromMetadata(metadata, noteId) {
   };
 }
 
+function normalizeAppSessionStatus(input = {}) {
+  const listenerSession = input.listenerSession && typeof input.listenerSession === "object"
+    ? input.listenerSession
+    : null;
+  const sttChunks = Array.isArray(input.sttChunks) ? input.sttChunks : [];
+  const latestChunks = sttChunks.some((chunk) => optionalNonEmptyString(chunk?.chunkID))
+    ? latestSTTChunks(sttChunks)
+    : sttChunks;
+  const runningChunkCount = latestChunks.filter((chunk) => chunk.status === "queued" || chunk.status === "running").length;
+  const failedChunkCount = latestChunks.filter((chunk) => chunk.status === "failed").length;
+  const retryableChunkCount = latestChunks.filter((chunk) => isRetryableSTTChunkStatus(chunk.status)).length;
+  const base = {
+    detail: null,
+    retryableChunkCount,
+    failedChunkCount,
+    runningChunkCount,
+  };
+  const listenerState = normalizeListenerSessionState(listenerSession?.state);
+  const listenerError = optionalNonEmptyString(listenerSession?.error);
+  const listenerDetail = listenerError || optionalNonEmptyString(listenerSession?.detail);
+
+  if (listenerState === "failed") {
+    return { ...base, state: "failed", detail: listenerDetail };
+  }
+  if (listenerState === "recovering") {
+    return { ...base, state: "recoverable", detail: listenerDetail || "Session needs recovery." };
+  }
+  if (listenerState === "starting" || listenerState === "recording") {
+    return {
+      ...base,
+      state: listenerError ? "degraded" : "recording",
+      detail: listenerDetail,
+    };
+  }
+  if (listenerState === "stopping") {
+    return { ...base, state: "finalizing", detail: listenerDetail };
+  }
+  if (runningChunkCount > 0) {
+    return { ...base, state: "transcribing", detail: "Transcription is running." };
+  }
+  if (failedChunkCount > 0) {
+    return {
+      ...base,
+      state: "recoverable",
+      detail: `${failedChunkCount} STT ${failedChunkCount === 1 ? "chunk needs" : "chunks need"} retry.`,
+    };
+  }
+  if (listenerState === "completed" || latestChunks.some((chunk) => chunk.status === "completed")) {
+    return { ...base, state: "completed", detail: listenerDetail };
+  }
+  return null;
+}
+
+function normalizeStoredAppSessionStatus(value) {
+  const raw = typeof value === "string" ? parseMetadataJSON(value) : value;
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const state = optionalNonEmptyString(raw.state);
+  if (!["recording", "degraded", "finalizing", "transcribing", "failed", "completed", "recoverable"].includes(state)) {
+    return null;
+  }
+  return {
+    state,
+    detail: optionalNonEmptyString(raw.detail),
+    retryableChunkCount: Number.isFinite(Number(raw.retryableChunkCount)) ? Number(raw.retryableChunkCount) : 0,
+    failedChunkCount: Number.isFinite(Number(raw.failedChunkCount)) ? Number(raw.failedChunkCount) : 0,
+    runningChunkCount: Number.isFinite(Number(raw.runningChunkCount)) ? Number(raw.runningChunkCount) : 0,
+  };
+}
+
 async function writeListenerSessionState(noteId, patch) {
   if (!noteId) {
     return;
@@ -1635,6 +1706,14 @@ function applyNotesDatabaseMigrations(database) {
         `);
       },
     },
+    {
+      version: 4,
+      up: (db) => {
+        db.exec(`
+          ALTER TABLE notes ADD COLUMN session_status_json TEXT;
+        `);
+      },
+    },
   ];
 
   for (const migration of migrations) {
@@ -1798,6 +1877,9 @@ async function loadBundleSnapshot(directoryName) {
     ? metadata.transcriptSegmentCount
     : transcriptSegments.length;
 
+  const listenerSession = listenerSessionFromMetadata(metadata, directoryName);
+  const sttChunks = latestSTTChunks(parseSTTChunkLedgerJSONL(await readTextIfExists(path.join(directoryPath, STT_CHUNK_LEDGER_FILE_NAME))));
+
   const summary = {
     id: directoryName,
     title: displayTitleFromBundle(directoryName, metadata, markdown),
@@ -1814,7 +1896,8 @@ async function loadBundleSnapshot(directoryName) {
     transcriptPath: paths.transcriptPath,
     metadataPath: paths.metadataPath,
     recordingPath: paths.recordingPath,
-    listenerSession: listenerSessionFromMetadata(metadata, directoryName),
+    listenerSession,
+    sessionStatus: normalizeAppSessionStatus({ listenerSession, sttChunks }),
   };
 
   return {
@@ -1828,6 +1911,7 @@ async function loadBundleSnapshot(directoryName) {
 
 function noteSummaryFromRow(row) {
   const metadata = parseMetadataJSON(row.metadata_json);
+  const listenerSession = listenerSessionFromMetadata(metadata, row.id);
   return {
     id: row.id,
     title: row.title,
@@ -1844,7 +1928,8 @@ function noteSummaryFromRow(row) {
     transcriptPath: row.transcript_path,
     metadataPath: row.metadata_path,
     recordingPath: row.recording_path,
-    listenerSession: listenerSessionFromMetadata(metadata, row.id),
+    listenerSession,
+    sessionStatus: normalizeStoredAppSessionStatus(row.session_status_json),
   };
 }
 
@@ -1884,9 +1969,10 @@ function upsertNoteSnapshot(snapshot) {
         recording_path,
         markdown,
         metadata_json,
+        session_status_json,
         created_at,
         updated_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         title = excluded.title,
         started_at = excluded.started_at,
@@ -1902,6 +1988,7 @@ function upsertNoteSnapshot(snapshot) {
         recording_path = excluded.recording_path,
         markdown = excluded.markdown,
         metadata_json = excluded.metadata_json,
+        session_status_json = excluded.session_status_json,
         updated_at = excluded.updated_at
     `).run(
       summary.id,
@@ -1919,6 +2006,7 @@ function upsertNoteSnapshot(snapshot) {
       summary.recordingPath,
       markdown,
       serializeMetadata(metadata),
+      serializeMetadata(summary.sessionStatus),
       createdAt,
       now,
     );
@@ -2431,6 +2519,7 @@ async function readNote(id) {
   });
   const directoryPath = resolveBundleDirectory(row.id);
   const sttChunks = latestSTTChunks(parseSTTChunkLedgerJSONL(await readTextIfExists(path.join(directoryPath, STT_CHUNK_LEDGER_FILE_NAME))));
+  const summary = noteSummaryFromRow(row);
   const speakerLabels = database.prepare(`
     SELECT
       speaker_id,
@@ -2449,7 +2538,8 @@ async function readNote(id) {
   markNoteOpened(id);
 
   return {
-    ...noteSummaryFromRow(row),
+    ...summary,
+    sessionStatus: normalizeAppSessionStatus({ listenerSession: summary.listenerSession, sttChunks }),
     directoryPath,
     markdown: row.markdown,
     metadata: parseMetadataJSON(row.metadata_json),
@@ -4538,6 +4628,7 @@ if (process.env.MIRROR_NOTE_TEST_EXPORTS === "1") {
     mergeSummarySettingsPatch,
     normalizeCustomSummaryTemplate,
     normalizeCustomSummaryTemplates,
+    normalizeAppSessionStatus,
     normalizeListenerSessionState,
     normalizeSummarySettings,
     nativeHelperWorkingDirectory,

apps/desktop/main/native-launch.node-test.cjs

@@ -7,6 +7,7 @@ const {
   latestSTTChunks,
   latestRetryableSTTChunks,
   nativeHelperWorkingDirectory,
+  normalizeAppSessionStatus,
   normalizeListenerSessionState,
   normalizeTranscriptSegments,
   parseSTTChunkLedgerJSONL,
@@ -20,6 +21,55 @@ assert.equal(normalizeListenerSessionState("finalizing"), "stopping");
 assert.equal(normalizeListenerSessionState("completed"), "completed");
 assert.equal(normalizeListenerSessionState("unknown"), null);
 
+assert.deepEqual(normalizeAppSessionStatus({
+  listenerSession: { state: "recording", error: null, detail: null },
+  sttChunks: [],
+}), {
+  state: "recording",
+  detail: null,
+  retryableChunkCount: 0,
+  failedChunkCount: 0,
+  runningChunkCount: 0,
+});
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "recording", error: "System audio unavailable.", detail: null },
+  sttChunks: [],
+}).state, "degraded");
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "starting", error: null, detail: "Preparing local capture." },
+  sttChunks: [],
+}).state, "recording");
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "stopping", error: null, detail: null },
+  sttChunks: [],
+}).state, "finalizing");
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "failed", error: "Capture failed.", detail: null },
+  sttChunks: [],
+}).state, "failed");
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "recovering", error: null, detail: null },
+  sttChunks: [],
+}).state, "recoverable");
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "completed", error: null, detail: null },
+  sttChunks: [{ status: "running" }, { status: "completed" }],
+}).state, "transcribing");
+assert.deepEqual(normalizeAppSessionStatus({
+  listenerSession: { state: "completed", error: null, detail: null },
+  sttChunks: [{ status: "failed" }, { status: "completed" }],
+}), {
+  state: "recoverable",
+  detail: "1 STT chunk needs retry.",
+  retryableChunkCount: 1,
+  failedChunkCount: 1,
+  runningChunkCount: 0,
+});
+assert.equal(normalizeAppSessionStatus({
+  listenerSession: { state: "completed", error: null, detail: null },
+  sttChunks: [{ status: "completed" }],
+}).state, "completed");
+
 const runtimeSegment = {
   id: "seg-1",
   sessionID: "session-a",

apps/desktop/src/types.ts

@@ -8,6 +8,7 @@ export type EditorCommand = "paragraph" | "heading1" | "heading2" | "bullet" | "
 export type NoteActivity = "recording" | "finalizing" | "failed" | null;
 export type TranscriptSource = "microphone" | "system";
 export type ListenerSessionState = "starting" | "recording" | "stopping" | "recovering" | "failed" | "completed";
+export type AppSessionState = "recording" | "degraded" | "finalizing" | "transcribing" | "failed" | "completed" | "recoverable";
 export type STTChunkStatus = "queued" | "running" | "completed" | "failed";
 export type SpeakerLabelingMode = "local" | "disabled";
 export type AppLanguage = "en" | "ko";
@@ -80,6 +81,7 @@ export interface NoteSummary {
   metadataPath: string;
   recordingPath: string;
   listenerSession: ListenerSession | null;
+  sessionStatus: AppSessionStatus | null;
 }
 
 export interface TranscriptSegment {
@@ -106,6 +108,14 @@ export interface ListenerSession {
   error: string | null;
 }
 
+export interface AppSessionStatus {
+  state: AppSessionState;
+  detail: string | null;
+  retryableChunkCount: number;
+  failedChunkCount: number;
+  runningChunkCount: number;
+}
+
 export interface STTChunk {
   sessionID: string | null;
   chunkID: string;