pi-mega-compact 0.9.2 → 0.11.0

package/src/intent.test.ts

@@ -0,0 +1,87 @@
+/**
+ * intent.test.ts — S52A rewind-intent queue tests. No network; temp dirs.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openTurnStore, closeAllTurnDbs } from "./store/turns/connection.js";
+import { openIntentQueue } from "./intent.js";
+
+let tmpDir: string;
+let counter = 0;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "mc-intent-"));
+});
+
+afterEach(() => {
+	closeAllTurnDbs();
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function stateDir(): string {
+	return join(tmpDir, `run-${counter++}`);
+}
+
+test("postIntent creates a pending intent", () => {
+	const dir = stateDir();
+	const db = openTurnStore(dir);
+	const q = openIntentQueue(db);
+	const intent = q.postIntent({ conversationId: "conv_a", targetTurnIndex: 3 });
+	assert.equal(intent.conversationId, "conv_a");
+	assert.equal(intent.targetTurnIndex, 3);
+	assert.equal(intent.status, "pending");
+	assert.ok(intent.id.length > 0);
+	assert.ok(intent.createdAt > 0);
+});
+
+test("pendingIntents lists only unconsumed", () => {
+	const dir = stateDir();
+	const db = openTurnStore(dir);
+	const q = openIntentQueue(db);
+	q.postIntent({ conversationId: "c1", targetTurnIndex: 1 });
+	const i2 = q.postIntent({ conversationId: "c2", targetTurnIndex: 2 });
+	assert.equal(q.pendingIntents().length, 2);
+	q.consumeIntent(i2.id);
+	assert.equal(q.pendingIntents().length, 1);
+	assert.equal(q.pendingIntents()[0].conversationId, "c1");
+});
+
+test("consumeIntent marks status consumed (not deleted)", () => {
+	const dir = stateDir();
+	const db = openTurnStore(dir);
+	const q = openIntentQueue(db);
+	const intent = q.postIntent({ conversationId: "c", targetTurnIndex: 0 });
+	q.consumeIntent(intent.id);
+	assert.equal(q.pendingIntents().length, 0);
+	const all = q.allIntents();
+	assert.equal(all.length, 1);
+	assert.equal(all[0].status, "consumed");
+	assert.equal(all[0].id, intent.id);
+});
+
+test("abandonIntent deletes the intent", () => {
+	const dir = stateDir();
+	const db = openTurnStore(dir);
+	const q = openIntentQueue(db);
+	const intent = q.postIntent({ conversationId: "c", targetTurnIndex: 0 });
+	q.abandonIntent(intent.id);
+	assert.equal(q.pendingIntents().length, 0);
+	assert.equal(q.allIntents().length, 0);
+});
+
+test("allIntents returns newest-first + respects limit", () => {
+	const dir = stateDir();
+	const db = openTurnStore(dir);
+	const q = openIntentQueue(db);
+	q.postIntent({ conversationId: "a", targetTurnIndex: 0 });
+	q.postIntent({ conversationId: "b", targetTurnIndex: 0 });
+	q.postIntent({ conversationId: "c", targetTurnIndex: 0 });
+	const all = q.allIntents();
+	assert.equal(all.length, 3);
+	// newest-first: c was posted last
+	assert.equal(all[0].conversationId, "c");
+	assert.equal(q.allIntents(2).length, 2);
+});

package/src/intent.ts

@@ -0,0 +1,115 @@
+/**
+ * intent.ts — S52A host-agnostic rewind-intent queue.
+ *
+ * A thin queue over the S49-pre-created `pending_fork` table. The dashboard
+ * (or any external surface) POSTS a "rewind to turn N" intent; the host polls
+ * pending intents at `before_agent_start` and CONSUMEs them to apply the rewind.
+ * The store never calls back into the host (ledger protocol — the host PUSHES
+ * facts and PULLS views; the store is passive).
+ *
+ * State is encoded on `consumed_at` (NULL = pending, non-NULL = consumed) +
+ * row absence (abandoned = deleted). No schema change to `pending_fork`.
+ *
+ * Pi-agnostic (PREVENT-PI-004: pure node:sqlite). Parameterized (PREVENT-002).
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+/** A rewind intent — "rewind conversation X to turn N". */
+export interface RewindIntent {
+	/** Stable string id (random 16-hex). */
+	id: string;
+	/** Conversation to rewind. */
+	conversationId: string;
+	/** The turn index to rewind to (the parent turn a fork branches from). */
+	targetTurnIndex: number;
+	/** epoch ms the intent was posted. */
+	createdAt: number;
+	/** pending (not yet acted on) | consumed (host applied it). */
+	status: "pending" | "consumed";
+}
+
+/** Input to postIntent (id/createdAt/status are derived). */
+export interface PostIntentInput {
+	conversationId: string;
+	targetTurnIndex: number;
+}
+
+/** Append-only writer for rewind intents (dashboard / external surface). */
+export interface IntentWriter {
+	postIntent(input: PostIntentInput): RewindIntent;
+}
+
+/** Reader for rewind intents (host polls; dashboard inspects). */
+export interface IntentReader {
+	pendingIntents(): RewindIntent[];
+	allIntents(limit?: number): RewindIntent[];
+	consumeIntent(id: string): void;
+	/** Abandon = delete (the intent is withdrawn, never to be applied). */
+	abandonIntent(id: string): void;
+}
+
+/** Open an intent queue over a turns.db handle (from openTurnStore/openTurnDb). */
+export function openIntentQueue(db: DatabaseSync): IntentWriter & IntentReader {
+	function rowToIntent(r: Record<string, unknown>): RewindIntent {
+		return {
+			id: String(r.id),
+			conversationId: String(r.target_conversation_id),
+			targetTurnIndex: Number(r.target_turn_id),
+			createdAt: Number(r.requested_at),
+			status: r.consumed_at == null ? "pending" : "consumed",
+		};
+	}
+
+	return {
+		postIntent(input: PostIntentInput): RewindIntent {
+			const createdAt = Date.now();
+			const res = db
+				.prepare(
+					`INSERT INTO pending_fork
+           (target_conversation_id, target_turn_id, requested_at, consumed_at)
+         VALUES (?, ?, ?, NULL)`,
+				)
+				.run(input.conversationId, input.targetTurnIndex, createdAt);
+			const id = String(Number(res.lastInsertRowid));
+			return {
+				id,
+				conversationId: input.conversationId,
+				targetTurnIndex: input.targetTurnIndex,
+				createdAt,
+				status: "pending",
+			};
+		},
+
+		pendingIntents(): RewindIntent[] {
+			const rows = db
+				.prepare(
+					`SELECT id, target_conversation_id, target_turn_id, requested_at, consumed_at
+           FROM pending_fork WHERE consumed_at IS NULL
+           ORDER BY requested_at ASC`,
+				)
+				.all() as Array<Record<string, unknown>>;
+			return rows.map(rowToIntent);
+		},
+
+		allIntents(limit = 100): RewindIntent[] {
+			const rows = db
+				.prepare(
+					`SELECT id, target_conversation_id, target_turn_id, requested_at, consumed_at
+           FROM pending_fork ORDER BY requested_at DESC, id DESC LIMIT ?`,
+				)
+				.all(limit) as Array<Record<string, unknown>>;
+			return rows.map(rowToIntent);
+		},
+
+		consumeIntent(id: string): void {
+			db.prepare("UPDATE pending_fork SET consumed_at = ? WHERE id = ?").run(
+				Date.now(),
+				id,
+			);
+		},
+
+		abandonIntent(id: string): void {
+			db.prepare("DELETE FROM pending_fork WHERE id = ?").run(id);
+		},
+	};
+}

package/src/metrics/index.ts

@@ -0,0 +1,9 @@
+/**
+ * index.ts — S50 metrics barrel. Re-export only.
+ */
+export {
+	turnMetrics,
+	conversationMetrics,
+	type TurnMetrics,
+	type ConversationMetrics,
+} from "./turns.js";

package/src/metrics/turns.test.ts

@@ -0,0 +1,165 @@
+/**
+ * turns.test.ts — S50C per-turn + per-conversation metrics tests. No network.
+ * Seeds a turns.db (S49 contract store) and a main db (raw_transcript +
+ * checkpoint_epochs) and asserts the rollups match seeded truth.
+ */
+import { test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+	createTurnStore,
+	closeAllTurnDbs,
+	type TurnStore,
+} from "../store/turns/index.js";
+import { openStore } from "../store/sqlite/utils.js";
+import { appendRawTranscript } from "../store/sqlite/raw-transcript.js";
+import { writeCheckpointEpoch } from "../store/sqlite/raw-transcript.js";
+import { turnMetrics, conversationMetrics } from "./turns.js";
+
+let tmpDir: string;
+let counter = 0;
+
+beforeEach(() => {
+	tmpDir = mkdtempSync(join(tmpdir(), "mc-metrics-"));
+});
+
+afterEach(() => {
+	closeAllTurnDbs();
+	rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function stateDir(): string {
+	return join(tmpDir, `run-${counter++}`);
+}
+
+/** Seed one conversation: 2 turns, recall on turn 0, raw messages, one epoch. */
+function seed(dir: string): { store: TurnStore; conv: string } {
+	const store = createTurnStore({ stateDir: dir });
+	const conv = store.ensureConversationId("sess_m");
+	const t0 = store.appendTurn({
+		conversationId: conv,
+		sessionId: "sess_m",
+		turnIndex: 0,
+		role: "assistant",
+		endedAt: Date.now(),
+		ctxTokens: 800,
+		ctxPercent: 0.4,
+	});
+	store.appendRecall({
+		turnId: t0,
+		checkpointId: "cp_1",
+		score: 0.9,
+		source: "checkpoint",
+	});
+	store.appendRecall({
+		turnId: t0,
+		checkpointId: "cp_2",
+		score: 0.8,
+		source: "checkpoint",
+	});
+	store.appendTurn({
+		conversationId: conv,
+		sessionId: "sess_m",
+		turnIndex: 1,
+		role: "assistant",
+		endedAt: Date.now(),
+		ctxTokens: 1200,
+	});
+	store.asAdmin().stampTurnsEpoch("sess_m", "ep_1");
+
+	const main = openStore(dir);
+	// 5 raw messages in the committed range; ep_1's summary is much smaller
+	// (compression ratio < 1). turn_index is set on all of them.
+	const msgs = [
+		{ hash: "h0", turn: 0, bytes: "aaaaaaaa" },
+		{ hash: "h1", turn: 0, bytes: "bbbbbbbb" },
+		{ hash: "h2", turn: 1, bytes: "cccccccc" },
+		{ hash: "h3", turn: 1, bytes: "dddddddd" },
+		{ hash: "h4", turn: 1, bytes: "eeeeeeee" },
+	];
+	for (const m of msgs) {
+		appendRawTranscript(main, {
+			contentHash: m.hash,
+			sessionId: "sess_m",
+			seq: 0,
+			role: "user",
+			contentBytes: m.bytes,
+			toolName: null,
+			messageTimestamp: null,
+			checkpointEpoch: "ep_1",
+			turnIndex: m.turn,
+		});
+	}
+	writeCheckpointEpoch(main, {
+		epochId: "ep_1",
+		sessionId: "sess_m",
+		startedSeq: 0,
+		committedSeq: 3,
+		summaryMessageText: "sum",
+		cutIndex: 3,
+		checkpointId: "cp_x",
+		createdAt: Date.now(),
+	});
+	return { store, conv };
+}
+
+test("turnMetrics returns per-turn recall + dedup + compression", () => {
+	const dir = stateDir();
+	const { store, conv } = seed(dir);
+	const main = openStore(dir);
+	const rows = turnMetrics(store, main, conv);
+	assert.equal(rows.length, 2);
+	const t0 = rows.find((r) => r.turnIndex === 0)!;
+	assert.equal(t0.recallCount, 2);
+	assert.equal(t0.rawMessageCount, 2);
+	assert.equal(t0.dedupUniqueRatio, 1); // PK(content_hash,session_id) → all stored rows unique
+	const t1 = rows.find((r) => r.turnIndex === 1)!;
+	assert.equal(t1.rawMessageCount, 3);
+	assert.equal(t1.epochId, "ep_1");
+	assert.ok(t0.compressionRatio > 0 && t0.compressionRatio < 1); // summary smaller than raw
+	store.close();
+});
+
+test("conversationMetrics aggregates per-turn metrics", () => {
+	const dir = stateDir();
+	const { store, conv } = seed(dir);
+	const main = openStore(dir);
+	const m = conversationMetrics(store, main, conv);
+	assert.equal(m.turnCount, 2);
+	assert.equal(m.totalRecall, 2);
+	assert.equal(m.totalRawMessages, 5);
+	assert.equal(m.epochCount, 1);
+	assert.ok(m.avgDedupUniqueRatio > 0);
+	store.close();
+});
+
+test("metrics tolerate a main db without raw_transcript (reuse host)", () => {
+	const dir = stateDir();
+	const store = createTurnStore({ stateDir: dir });
+	const conv = store.ensureConversationId("sess_n");
+	const t = store.appendTurn({
+		conversationId: conv,
+		sessionId: "sess_n",
+		turnIndex: 0,
+		role: "assistant",
+		endedAt: Date.now(),
+	});
+	store.appendRecall({
+		turnId: t,
+		checkpointId: "cp",
+		score: 0.5,
+		source: "checkpoint",
+	});
+	// Bare in-memory db with NO raw_transcript / checkpoint_epochs tables.
+	const bare = new DatabaseSync(":memory:");
+	const rows = turnMetrics(store, bare, conv);
+	assert.equal(rows.length, 1);
+	assert.equal(rows[0].recallCount, 1);
+	assert.equal(rows[0].rawMessageCount, 0);
+	assert.equal(rows[0].dedupUniqueRatio, 0);
+	assert.equal(rows[0].compressionRatio, 0);
+	store.close();
+});

package/src/metrics/turns.ts

@@ -0,0 +1,201 @@
+/**
+ * turns.ts — S50C per-turn + per-conversation memory-quality rollups.
+ *
+ * Host-agnostic (pi-agnostic): consumes the S49 `TurnStore` interface plus a
+ * main-db `DatabaseSync` handle for raw_transcript / checkpoint_epochs. Pure
+ * read queries — this module NEVER mutates memory, drop ranges, or compaction
+ * (PREVENT-PI-001/002). Parameterized (PREVENT-002). No network (PREVENT-PI-004).
+ *
+ * These are the numbers the S52 dashboard Turns tab renders: per-turn cache-hit
+ * (recall reuse), dedup ratio, and compression ratio, rolled up per turn and
+ * per conversation.
+ */
+import type { DatabaseSync } from "node:sqlite";
+import type { TurnStore } from "../store/turns/types.js";
+
+/** Per-turn memory-quality metrics. Ratios are 0 when their basis is absent. */
+export interface TurnMetrics {
+	/** Per-conversation turn key (the contract TurnEntry is id-less; turnIndex
+	 *  is unique within a conversation). */
+	turnId: number;
+	conversationId: string;
+	sessionId: string;
+	turnIndex: number;
+	epochId: string | null;
+	ctxTokens: number | null;
+	ctxPercent: number | null;
+	/** Checkpoints/summaries injected this turn (turn_recall count). */
+	recallCount: number;
+	/** Raw messages mirrored for this turn (raw_transcript.turn_index count). 0 when dbMirror OFF. */
+	rawMessageCount: number;
+	/** Distinct content_hash / raw rows for this turn → 1 - ratio = dup fraction. */
+	dedupUniqueRatio: number;
+	/** Raw bytes → summary bytes compression for the epoch this turn closed (0 if none). */
+	compressionRatio: number;
+}
+
+/** Per-conversation aggregate of TurnMetrics. */
+export interface ConversationMetrics {
+	conversationId: string;
+	turnCount: number;
+	totalRecall: number;
+	totalRawMessages: number;
+	avgDedupUniqueRatio: number;
+	avgCompressionRatio: number;
+	/** Distinct epochs that compacted this conversation's turns. */
+	epochCount: number;
+}
+
+interface RawAgg {
+	turn_index: number;
+	raw_count: number;
+	unique_count: number;
+}
+
+/** Approximate byte length of a text (utf8). */
+function byteLen(s: string): number {
+	return Buffer.byteLength(s, "utf8");
+}
+
+/**
+ * Per-turn metrics for a conversation. Combines turns.db (turn spine + recall)
+ * with main-db raw_transcript (dedup) + checkpoint_epochs (compression).
+ *
+ * `mainDb` may be a store without raw_transcript/checkpoint_epochs (e.g. a
+ * reuse host that only mirrors turns); in that case dedup/compression = 0 and
+ * rawMessageCount = 0. Detected defensively per-query.
+ */
+export function turnMetrics(
+	store: TurnStore,
+	mainDb: DatabaseSync,
+	conversationId: string,
+): TurnMetrics[] {
+	const turns = store.query({ conversationId, limit: 10000 });
+	if (turns.length === 0) return [];
+
+	const hasRaw = tableExists(mainDb, "raw_transcript");
+	const hasEpoch = tableExists(mainDb, "checkpoint_epochs");
+
+	// Aggregate raw_transcript per turn_index for this session (raw rows + unique
+	// content_hash). Grouped by turn_index; sessions may share turn_index values,
+	// so we scope by session_id below per turn.
+	const rawAggBySessionTurn = new Map<string, RawAgg>();
+	if (hasRaw) {
+		const sessionIds = [...new Set(turns.map((t) => t.sessionId))];
+		const placeholders = sessionIds.map(() => "?").join(",");
+		const rows = mainDb
+			.prepare(
+				`SELECT session_id, turn_index,
+                COUNT(*) AS raw_count,
+                COUNT(DISTINCT content_hash) AS unique_count
+         FROM raw_transcript
+         WHERE session_id IN (${placeholders}) AND turn_index IS NOT NULL
+         GROUP BY session_id, turn_index`,
+			)
+			.all(...sessionIds) as unknown as Array<RawAgg & { session_id: string }>;
+		for (const r of rows) {
+			rawAggBySessionTurn.set(`${r.session_id}::${r.turn_index}`, r);
+		}
+	}
+
+	// Compression ratio per epoch: committed raw bytes → summary bytes. Precomputed
+	// per epoch referenced by any turn.
+	const compressionByEpoch = new Map<string, number>();
+	if (hasEpoch) {
+		const epochIds = turns
+			.map((t) => t.epochId)
+			.filter((e): e is string => e != null);
+		for (const eid of new Set(epochIds)) {
+			const ratio = epochCompressionRatio(mainDb, eid);
+			if (ratio != null) compressionByEpoch.set(eid, ratio);
+		}
+	}
+
+	return turns.map((t) => {
+		const recall = store.listRecallByIndex(conversationId, t.turnIndex);
+		const agg = rawAggBySessionTurn.get(`${t.sessionId}::${t.turnIndex}`);
+		const rawCount = agg?.raw_count ?? 0;
+		const uniqueCount = agg?.unique_count ?? 0;
+		return {
+			turnId: t.turnIndex,
+			conversationId: t.conversationId,
+			sessionId: t.sessionId,
+			turnIndex: t.turnIndex,
+			epochId: t.epochId ?? null,
+			ctxTokens: t.ctxTokens ?? null,
+			ctxPercent: t.ctxPercent ?? null,
+			recallCount: recall.length,
+			rawMessageCount: rawCount,
+			dedupUniqueRatio: rawCount > 0 ? uniqueCount / rawCount : 0,
+			compressionRatio: t.epochId
+				? (compressionByEpoch.get(t.epochId) ?? 0)
+				: 0,
+		};
+	});
+}
+
+/** Aggregate a conversation's per-turn metrics. */
+export function conversationMetrics(
+	store: TurnStore,
+	mainDb: DatabaseSync,
+	conversationId: string,
+): ConversationMetrics {
+	const perTurn = turnMetrics(store, mainDb, conversationId);
+	const turnCount = perTurn.length;
+	const totalRecall = perTurn.reduce((s, t) => s + t.recallCount, 0);
+	const totalRaw = perTurn.reduce((s, t) => s + t.rawMessageCount, 0);
+	const dedupSum = perTurn.reduce((s, t) => s + t.dedupUniqueRatio, 0);
+	const compSum = perTurn.reduce((s, t) => s + t.compressionRatio, 0);
+	const epochs = new Set(perTurn.map((t) => t.epochId).filter(Boolean));
+	return {
+		conversationId,
+		turnCount,
+		totalRecall,
+		totalRawMessages: totalRaw,
+		avgDedupUniqueRatio: turnCount > 0 ? dedupSum / turnCount : 0,
+		avgCompressionRatio: turnCount > 0 ? compSum / turnCount : 0,
+		epochCount: epochs.size,
+	};
+}
+
+function tableExists(db: DatabaseSync, name: string): boolean {
+	return (
+		db
+			.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?")
+			.get(name) !== undefined
+	);
+}
+
+/**
+ * Compression ratio for an epoch: summaryMessageText bytes ÷ raw bytes of the
+ * committed range. Returns null when the epoch or its raw rows are absent.
+ * Ratio < 1 means compression shrank the content (lower = more compression).
+ */
+function epochCompressionRatio(
+	mainDb: DatabaseSync,
+	epochId: string,
+): number | null {
+	const epoch = mainDb
+		.prepare(
+			"SELECT session_id, committed_seq, summary_message_text FROM checkpoint_epochs WHERE epoch_id = ?",
+		)
+		.get(epochId) as
+		| {
+				session_id: string;
+				committed_seq: number;
+				summary_message_text: string;
+		  }
+		| undefined;
+	if (!epoch) return null;
+	const raw = mainDb
+		.prepare(
+			`SELECT COALESCE(SUM(LENGTH(content_bytes)), 0) AS bytes
+       FROM raw_transcript
+       WHERE session_id = ? AND seq <= ?`,
+		)
+		.get(epoch.session_id, epoch.committed_seq) as { bytes: number };
+	const rawBytes = raw?.bytes ?? 0;
+	if (rawBytes <= 0) return null;
+	const summaryBytes = byteLen(epoch.summary_message_text ?? "");
+	return summaryBytes / rawBytes;
+}

package/src/store/sqlite/raw-transcript.ts

@@ -22,6 +22,9 @@ export interface RawTranscriptRow {
   /** ORIGINAL message timestamp captured at append time (NOT a served ts). */
   messageTimestamp: number | null;
   checkpointEpoch: string;
+  /** S50: the per-session turn that produced this message (runtime.currentTurn).
+   *  Null on rows written before S50 or when the writer omits it (back-compat). */
+  turnIndex?: number | null;
 }
 
 /** One checkpoint-epoch bookkeeping row (informational registry). */
@@ -46,6 +49,7 @@ interface RawTranscriptDBRow {
   tool_name: string | null;
   message_timestamp: number | null;
   checkpoint_epoch: string;
+  turn_index: number | null;
 }
 
 /** DB row shape for checkpoint_epochs (snake_case column names). */
@@ -71,6 +75,7 @@ function rowToRawTranscript(row: RawTranscriptDBRow): RawTranscriptRow {
     messageTimestamp:
       row.message_timestamp == null ? null : Number(row.message_timestamp),
     checkpointEpoch: row.checkpoint_epoch,
+    turnIndex: row.turn_index == null ? null : Number(row.turn_index),
   };
 }
 
@@ -99,11 +104,11 @@ export function appendRawTranscript(db: DatabaseSync, row: RawTranscriptRow): vo
   withTx(db, () => {
     db.prepare(
       `INSERT OR IGNORE INTO raw_transcript
-        (content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch)
+        (content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch, turn_index)
        VALUES (
          @content_hash, @session_id,
          COALESCE((SELECT MAX(seq) FROM raw_transcript WHERE session_id = @session_id), 0) + 1,
-         @role, @content_bytes, @tool_name, @message_timestamp, @checkpoint_epoch
+         @role, @content_bytes, @tool_name, @message_timestamp, @checkpoint_epoch, @turn_index
        )`,
     ).run({
       "@content_hash": row.contentHash,
@@ -113,6 +118,7 @@ export function appendRawTranscript(db: DatabaseSync, row: RawTranscriptRow): vo
       "@tool_name": row.toolName,
       "@message_timestamp": row.messageTimestamp,
       "@checkpoint_epoch": row.checkpointEpoch,
+      "@turn_index": row.turnIndex ?? null,
     });
   });
 }
@@ -129,7 +135,7 @@ export function listRawTranscriptRange(
 ): RawTranscriptRow[] {
   const rows = db
     .prepare(
-      `SELECT content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch
+      `SELECT content_hash, session_id, seq, role, content_bytes, tool_name, message_timestamp, checkpoint_epoch, turn_index
        FROM raw_transcript
        WHERE session_id = @session_id AND seq >= @from_seq AND seq <= @to_seq
        ORDER BY seq ASC`,

package/src/store/sqlite.dbmirror.test.ts

@@ -107,6 +107,16 @@ describe("DB mirror", () => {
       assert.equal(rows[0].messageTimestamp, 1234567890);
     });
 
+    it("S50A: stores turn_index when provided; null when omitted (back-compat)", () => {
+      appendRawTranscript(db, makeRow({ contentHash: "with-turn", turnIndex: 7 }));
+      appendRawTranscript(db, makeRow({ contentHash: "no-turn" }));
+      const rows = listRawTranscriptRange(db, "sess-1", 0, 999999);
+      const withTurn = rows.find((r) => r.contentHash === "with-turn");
+      const noTurn = rows.find((r) => r.contentHash === "no-turn");
+      assert.equal(withTurn?.turnIndex, 7);
+      assert.equal(noTurn?.turnIndex, null);
+    });
+
     it("stores checkpoint_epoch", () => {
       appendRawTranscript(db, makeRow({ checkpointEpoch: "ep-42" }));
       const rows = listRawTranscriptRange(db, "sess-1", 0, 999999);