@effect-agent/storage-sqlite 0.1.0-beta.6 → 0.1.0-beta.60

package/src/{sqlite-conversation-store.ts → SqliteThreadStore.ts}

@@ -1,32 +1,34 @@
+import { digestCanonicalBatch, EMPTY_TAIL_DIGEST } from "@effect-agent/thread/Digest";
 import {
-  AppendConflict,
-  AppendResult,
   CanonicalBatch,
   CanonicalRecord,
   CanonicalRecordEnvelope,
   CanonicalSequence,
-  CheckpointRejected,
-  ConversationCheckpoint,
-  ConversationExport,
-  ConversationExportRequest,
-  ConversationMaterialization,
-  ConversationNotMaterialized,
-  ConversationObservation,
-  ConversationRead,
-  ConversationStore,
-  ConversationStoreError,
-  ConversationTail,
-  ConversationTailRequest,
-  DEFAULT_OWNERSHIP_LEASE_DURATION,
-  digestCanonicalBatch,
   Digest,
-  EMPTY_TAIL_DIGEST,
+  ObservationOffset,
+} from "@effect-agent/thread/Records";
+import { DEFAULT_OWNERSHIP_LEASE_DURATION } from "@effect-agent/thread/SubmissionLedger";
+import {
+  AppendConflict,
+  AppendResult,
+  CheckpointRejected,
+  ThreadCheckpoint,
+  ThreadExport,
+  ThreadExportRequest,
+  ThreadMaterialization,
+  ThreadNotMaterialized,
+  ThreadObservation,
+  ThreadRead,
+  ThreadStore,
+  type ThreadCheckpoints,
+  ThreadStoreError,
+  ThreadTail,
+  ThreadTailRequest,
   FenceRejected,
   FencedAppendRequest,
   LoadCheckpointRequest,
-  ObservationOffset,
   SaveCheckpointRequest,
-} from "@effect-agent/session";
+} from "@effect-agent/thread/ThreadStore";
 import { NodeCrypto } from "@effect/platform-node";
 import { SqliteClient } from "@effect/sql-sqlite-node";
 import {
@@ -41,29 +43,29 @@ import {
   Schema,
   Stream,
 } from "effect";
-import * as SqlClientService from "effect/unstable/sql/SqlClient";
+import type * as SqlClientService from "effect/unstable/sql/SqlClient";
 
 import {
+  initializeSqliteJournal,
+  RawAppendRequest,
+  RawCheckpoint,
+  RawReadRequest,
+  type SqliteJournal,
+} from "./internal/sqlite-journal.ts";
+import { SqliteStorageConfig, SqliteStorageConfigValue } from "./SqliteStorageConfig.ts";
+import {
+  type SqliteStorageCompatibilityError,
   SqliteAppendConflict,
   SqliteCheckpointConflict,
   SqliteFenceRejected,
   type SqliteStorageFailpointLocation,
-  SqliteStorageCompatibilityError,
   SqliteStorageCorruptionError,
   SqliteStorageError,
-} from "./errors.ts";
-import {
-  initializeSqliteJournal,
-  RawAppendRequest,
-  RawCheckpoint,
-  RawReadRequest,
-  type SqliteJournal,
-} from "./sqlite-journal.ts";
-import { SqliteStorageConfig, SqliteStorageConfigValue } from "./sqlite-storage-config.ts";
+} from "./SqliteStorageError.ts";
 import {
   SqliteStorageFailpoint,
   type SqliteStorageFailpointHandler,
-} from "./sqlite-storage-failpoint.ts";
+} from "./SqliteStorageFailpoint.ts";
 
 export interface SqliteStorageOptions {
   readonly filename: string;
@@ -72,7 +74,7 @@ export interface SqliteStorageOptions {
   readonly busyTimeout?: number | undefined;
   /**
    * Submission ownership lease duration in milliseconds (D5). Defaults to
-   * `DEFAULT_OWNERSHIP_LEASE_DURATION` from `@effect-agent/session`.
+   * `DEFAULT_OWNERSHIP_LEASE_DURATION` from `@effect-agent/thread`.
    */
   readonly ownershipLeaseDuration?: number | undefined;
   /**
@@ -93,100 +95,104 @@ const OffsetText = Schema.String.check(Schema.isMaxLength(4 * 1024));
 const SQLITE_OFFSET_PREFIX = "effect-agent-sqlite@1:";
 const ZERO_CANONICAL_SEQUENCE = Schema.decodeSync(CanonicalSequence)(0);
 const isDigest = Schema.is(Digest);
+const isSqliteFenceRejected = Schema.is(SqliteFenceRejected);
+const isSqliteAppendConflict = Schema.is(SqliteAppendConflict);
+const isSqliteCheckpointConflict = Schema.is(SqliteCheckpointConflict);
 
 const storeError = (operation: string, error: { readonly message: string }) =>
-  ConversationStoreError.make({
+  ThreadStoreError.make({
     cause: error,
     operation,
     message: error.message,
   });
 
 const schemaStoreError = (operation: string, error: { readonly message: string }) =>
-  ConversationStoreError.make({
+  ThreadStoreError.make({
     cause: error,
     operation,
     message: error.message,
   });
 
-const makeOffset = Effect.fn("SqliteConversationStore.makeOffset")(function* (
-  conversationId: ConversationMaterialization["conversationId"],
+const makeOffset = Effect.fn("SqliteThreadStore.makeOffset")(function* (
+  threadId: ThreadMaterialization["threadId"],
   sequence: number,
-): Effect.fn.Return<ObservationOffset, ConversationStoreError> {
+): Effect.fn.Return<ObservationOffset, ThreadStoreError> {
   return yield* Schema.decodeUnknownEffect(CanonicalSequence)(sequence).pipe(
     Effect.flatMap((validatedSequence) =>
       Schema.decodeUnknownEffect(ObservationOffset)(
-        `${SQLITE_OFFSET_PREFIX}${encodeURIComponent(conversationId)}:${validatedSequence}`,
+        `${SQLITE_OFFSET_PREFIX}${encodeURIComponent(threadId)}:${validatedSequence}`,
       ),
     ),
     Effect.mapError((error) => schemaStoreError("encode observation offset", error)),
   );
 });
 
-const parseOffset = Effect.fn("SqliteConversationStore.parseOffset")(function* (
-  conversationId: ConversationMaterialization["conversationId"],
+const parseOffset = Effect.fn("SqliteThreadStore.parseOffset")(function* (
+  threadId: ThreadMaterialization["threadId"],
   offset: ObservationOffset | undefined,
-): Effect.fn.Return<CanonicalSequence, ConversationStoreError> {
+): Effect.fn.Return<CanonicalSequence, ThreadStoreError> {
   if (offset === undefined) return ZERO_CANONICAL_SEQUENCE;
+
   const text = yield* Schema.decodeUnknownEffect(OffsetText)(offset).pipe(
     Effect.mapError((error) => schemaStoreError("decode observation offset", error)),
   );
-  const conversationPrefix = `${SQLITE_OFFSET_PREFIX}${encodeURIComponent(conversationId)}:`;
-  if (!text.startsWith(conversationPrefix)) {
-    return yield* ConversationStoreError.make({
+
+  const threadPrefix = `${SQLITE_OFFSET_PREFIX}${encodeURIComponent(threadId)}:`;
+
+  if (!text.startsWith(threadPrefix)) {
+    return yield* ThreadStoreError.make({
       operation: "decode observation offset",
-      message:
-        "The observation offset belongs to a different adapter, storage version, or Conversation.",
+      message: "The observation offset belongs to a different adapter, storage version, or Thread.",
     });
   }
-  const sequenceText = text.slice(conversationPrefix.length);
+  const sequenceText = text.slice(threadPrefix.length);
+
   if (!/^(0|[1-9][0-9]*)$/.test(sequenceText)) {
-    return yield* ConversationStoreError.make({
+    return yield* ThreadStoreError.make({
       operation: "decode observation offset",
       message: "The observation offset is malformed.",
     });
   }
+
   return yield* Schema.decodeUnknownEffect(CanonicalSequence)(Number(sequenceText)).pipe(
     Effect.mapError((error) => schemaStoreError("decode observation offset", error)),
   );
 });
 
-const mapFence = (
-  conversationId: ConversationMaterialization["conversationId"],
-  error: SqliteFenceRejected,
-) =>
+const mapFence = (threadId: ThreadMaterialization["threadId"], error: SqliteFenceRejected) =>
   FenceRejected.make({
-    conversationId,
+    threadId,
     actualEpoch: error.actualEpoch,
     attemptedEpoch: error.producerEpoch,
   });
 
-const encodeCanonicalRecord = Effect.fn("SqliteConversationStore.encodeCanonicalRecord")(function* (
+const encodeCanonicalRecord = Effect.fn("SqliteThreadStore.encodeCanonicalRecord")(function* (
   record: CanonicalRecord,
-): Effect.fn.Return<string, ConversationStoreError> {
+): Effect.fn.Return<string, ThreadStoreError> {
   return yield* Schema.encodeEffect(Schema.fromJsonString(CanonicalRecord))(record).pipe(
     Effect.mapError((error) => schemaStoreError("encode canonical record", error)),
   );
 });
 
-const encodeCanonicalBatch = Effect.fn("SqliteConversationStore.encodeCanonicalBatch")(function* (
+const encodeCanonicalBatch = Effect.fn("SqliteThreadStore.encodeCanonicalBatch")(function* (
   batch: CanonicalBatch,
-): Effect.fn.Return<string, ConversationStoreError> {
+): Effect.fn.Return<string, ThreadStoreError> {
   return yield* Schema.encodeEffect(Schema.fromJsonString(CanonicalBatch))(batch).pipe(
     Effect.mapError((error) => schemaStoreError("encode canonical batch", error)),
   );
 });
 
-const encodeCheckpoint = Effect.fn("SqliteConversationStore.encodeCheckpoint")(function* (
-  checkpoint: ConversationCheckpoint,
-): Effect.fn.Return<string, ConversationStoreError> {
-  return yield* Schema.encodeEffect(Schema.fromJsonString(ConversationCheckpoint))(checkpoint).pipe(
+const encodeCheckpoint = Effect.fn("SqliteThreadStore.encodeCheckpoint")(function* (
+  checkpoint: ThreadCheckpoint,
+): Effect.fn.Return<string, ThreadStoreError> {
+  return yield* Schema.encodeEffect(Schema.fromJsonString(ThreadCheckpoint))(checkpoint).pipe(
     Effect.mapError((error) => schemaStoreError("encode checkpoint", error)),
   );
 });
 
-const decodeEnvelope = Effect.fn("SqliteConversationStore.decodeEnvelope")(function* (row: {
+const decodeEnvelope = Effect.fn("SqliteThreadStore.decodeEnvelope")(function* (row: {
   readonly batch_id: string;
-  readonly conversation_id: string;
+  readonly thread_id: string;
   readonly record_json: string;
   readonly sequence: CanonicalSequence;
 }) {
@@ -194,23 +200,25 @@ const decodeEnvelope = Effect.fn("SqliteConversationStore.decodeEnvelope")(funct
     row.record_json,
   ).pipe(
     Effect.mapError((error) =>
-      ConversationStoreError.make({
+      ThreadStoreError.make({
         operation: "decode canonical record",
         message: error.message,
       }),
     ),
   );
-  const conversationId = yield* Schema.decodeUnknownEffect(
-    CanonicalRecordEnvelope.fields.conversationId,
-  )(row.conversation_id).pipe(
-    Effect.mapError((error) => schemaStoreError("decode conversation identity", error)),
-  );
-  const offset = yield* makeOffset(conversationId, row.sequence);
+
+  const threadId = yield* Schema.decodeUnknownEffect(CanonicalRecordEnvelope.fields.threadId)(
+    row.thread_id,
+  ).pipe(Effect.mapError((error) => schemaStoreError("decode thread identity", error)));
+
+  const offset = yield* makeOffset(threadId, row.sequence);
+
   const batchId = yield* Schema.decodeUnknownEffect(CanonicalRecordEnvelope.fields.batchId)(
     row.batch_id,
   ).pipe(Effect.mapError((error) => schemaStoreError("decode batch identity", error)));
+
   return CanonicalRecordEnvelope.make({
-    conversationId,
+    threadId,
     batchId,
     sequence: row.sequence,
     offset,
@@ -218,42 +226,47 @@ const decodeEnvelope = Effect.fn("SqliteConversationStore.decodeEnvelope")(funct
   });
 });
 
-const decodeCheckpoint = Effect.fn("SqliteConversationStore.decodeCheckpoint")(function* (
+const decodeCheckpoint = Effect.fn("SqliteThreadStore.decodeCheckpoint")(function* (
   checkpointJson: string,
-): Effect.fn.Return<ConversationCheckpoint, ConversationStoreError> {
-  return yield* Schema.decodeEffect(Schema.fromJsonString(ConversationCheckpoint))(
-    checkpointJson,
-  ).pipe(Effect.mapError((error) => schemaStoreError("decode checkpoint", error)));
+): Effect.fn.Return<ThreadCheckpoint, ThreadStoreError> {
+  return yield* Schema.decodeEffect(Schema.fromJsonString(ThreadCheckpoint))(checkpointJson).pipe(
+    Effect.mapError((error) => schemaStoreError("decode checkpoint", error)),
+  );
 });
 
-const requireConversation = Effect.fn("SqliteConversationStore.requireConversation")(function* (
+const requireThread = Effect.fn("SqliteThreadStore.requireThread")(function* (
   journal: SqliteJournal,
-  conversationId: ConversationMaterialization["conversationId"],
+  threadId: ThreadMaterialization["threadId"],
 ) {
   const rows = yield* journal
-    .getConversation(conversationId)
-    .pipe(Effect.mapError((error) => storeError("read conversation", error)));
+    .getThread(threadId)
+    .pipe(Effect.mapError((error) => storeError("read thread", error)));
+
   if (rows.length === 0) {
-    return yield* ConversationNotMaterialized.make({ conversationId });
+    return yield* ThreadNotMaterialized.make({ threadId });
   }
+
   return rows[0];
 });
 
-const tailDigestAt = Effect.fn("SqliteConversationStore.tailDigestAt")(function* (
+const tailDigestAt = Effect.fn("SqliteThreadStore.tailDigestAt")(function* (
   journal: SqliteJournal,
-  conversationId: ConversationMaterialization["conversationId"],
+  threadId: ThreadMaterialization["threadId"],
   sequence: CanonicalSequence,
 ) {
   if (sequence === 0) return EMPTY_TAIL_DIGEST;
+
   const digests = yield* journal
-    .getTailDigestAt(conversationId, sequence)
+    .getTailDigestAt(threadId, sequence)
     .pipe(Effect.mapError((error) => storeError("read checkpoint digest", error)));
+
   if (digests.length !== 1) {
     return yield* CheckpointRejected.make({
-      conversationId,
+      threadId,
       reason: "digest-mismatch",
     });
   }
+
   return yield* Schema.decodeUnknownEffect(Digest)(digests[0]).pipe(
     Effect.mapError((error) => schemaStoreError("decode checkpoint digest", error)),
   );
@@ -264,14 +277,17 @@ const groupByKey = <A>(
   key: (row: A) => string,
 ): ReadonlyMap<string, ReadonlyArray<A>> => {
   const grouped = new Map<string, Array<A>>();
+
   for (const row of rows) {
     const existing = grouped.get(key(row));
+
     if (existing === undefined) {
       grouped.set(key(row), [row]);
     } else {
       existing.push(row);
     }
   }
+
   return grouped;
 };
 
@@ -280,69 +296,68 @@ const groupByKey = <A>(
  * and re-digested against the canonical chain. Routine opens skip this scan: per-operation
  * Schema decoding plus the digest chain already fail clearly on corrupt rows.
  */
-const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPayloads")(function* (
+const decodeStartupPayloads = Effect.fn("SqliteThreadStore.decodeStartupPayloads")(function* (
   journal: SqliteJournal,
   crypto: Crypto.Crypto,
 ) {
   const stored = yield* journal.scanStoredPayloads();
+
   const batches = yield* Effect.forEach(stored.batches, (batch) =>
     Schema.decodeEffect(Schema.fromJsonString(CanonicalBatch))(batch.batch_json).pipe(
       Effect.map((decoded) => ({ decoded, row: batch })),
       Effect.mapError((error) =>
         SqliteStorageCorruptionError.make({
           table: "effect_agent_canonical_batches",
-          rowKey: `${batch.conversation_id}/${batch.batch_id}`,
+          rowKey: `${batch.thread_id}/${batch.batch_id}`,
           message: error.message,
         }),
       ),
     ),
   );
+
   const records = yield* Effect.forEach(stored.records, (record) =>
     Schema.decodeEffect(Schema.fromJsonString(CanonicalRecord))(record.record_json).pipe(
       Effect.map((decoded) => ({ decoded, row: record })),
       Effect.mapError((error) =>
         SqliteStorageCorruptionError.make({
           table: "effect_agent_canonical_records",
-          rowKey: `${record.conversation_id}/${record.sequence}`,
+          rowKey: `${record.thread_id}/${record.sequence}`,
           message: error.message,
         }),
       ),
     ),
   );
+
   const checkpoints = yield* Effect.forEach(stored.checkpoints, (checkpoint) =>
-    Schema.decodeEffect(Schema.fromJsonString(ConversationCheckpoint))(
-      checkpoint.checkpoint_json,
-    ).pipe(
+    Schema.decodeEffect(Schema.fromJsonString(ThreadCheckpoint))(checkpoint.checkpoint_json).pipe(
       Effect.map((decoded) => ({ decoded, row: checkpoint })),
       Effect.mapError((error) =>
         SqliteStorageCorruptionError.make({
           table: "effect_agent_checkpoints",
-          rowKey: `${checkpoint.conversation_id}/${checkpoint.through_sequence}`,
+          rowKey: `${checkpoint.thread_id}/${checkpoint.through_sequence}`,
           message: error.message,
         }),
       ),
     ),
   );
 
-  const batchesByConversation = groupByKey(batches, ({ row }) => row.conversation_id);
-  const recordsByConversation = groupByKey(records, ({ row }) => row.conversation_id);
-  const checkpointsByConversation = groupByKey(checkpoints, ({ row }) => row.conversation_id);
-  const materializedIds = new Set(
-    stored.conversations.map((conversation) => conversation.conversation_id),
-  );
+  const batchesByThread = groupByKey(batches, ({ row }) => row.thread_id);
+  const recordsByThread = groupByKey(records, ({ row }) => row.thread_id);
+  const checkpointsByThread = groupByKey(checkpoints, ({ row }) => row.thread_id);
+  const materializedIds = new Set(stored.threads.map((thread) => thread.thread_id));
 
-  for (const conversation of stored.conversations) {
-    const conversationBatches = batchesByConversation.get(conversation.conversation_id) ?? [];
-    const conversationRecords = recordsByConversation.get(conversation.conversation_id) ?? [];
-    const conversationCheckpoints =
-      checkpointsByConversation.get(conversation.conversation_id) ?? [];
-    const recordsByBatch = groupByKey(conversationRecords, ({ row }) => row.batch_id);
+  for (const thread of stored.threads) {
+    const threadBatches = batchesByThread.get(thread.thread_id) ?? [];
+    const threadRecords = recordsByThread.get(thread.thread_id) ?? [];
+    const threadCheckpoints = checkpointsByThread.get(thread.thread_id) ?? [];
+    const recordsByBatch = groupByKey(threadRecords, ({ row }) => row.batch_id);
     let previousDigest = EMPTY_TAIL_DIGEST;
     let expectedSequence = 1;
     const tailDigests = new Map<number, string>([[0, EMPTY_TAIL_DIGEST]]);
 
-    for (const { decoded: canonicalBatch, row: batchRow } of conversationBatches) {
-      const key = `${batchRow.conversation_id}/${batchRow.batch_id}`;
+    for (const { decoded: canonicalBatch, row: batchRow } of threadBatches) {
+      const key = `${batchRow.thread_id}/${batchRow.batch_id}`;
+
       if (
         canonicalBatch.batchId !== batchRow.batch_id ||
         batchRow.first_sequence !== expectedSequence ||
@@ -365,6 +380,7 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
           }),
         ),
       );
+
       if (batchRow.batch_digest !== digest || batchRow.tail_digest !== digest) {
         return yield* SqliteStorageCorruptionError.make({
           table: "effect_agent_canonical_batches",
@@ -374,6 +390,7 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
       }
 
       const batchRecords = recordsByBatch.get(batchRow.batch_id) ?? [];
+
       if (batchRecords.length !== canonicalBatch.records.length) {
         return yield* SqliteStorageCorruptionError.make({
           table: "effect_agent_canonical_records",
@@ -384,6 +401,7 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
       for (let index = 0; index < canonicalBatch.records.length; index++) {
         const expectedRecord = canonicalBatch.records[index];
         const storedRecord = batchRecords[index];
+
         const expectedJson = yield* Schema.encodeEffect(Schema.fromJsonString(CanonicalRecord))(
           expectedRecord,
         ).pipe(
@@ -395,6 +413,7 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
             }),
           ),
         );
+
         const storedJson = yield* Schema.encodeEffect(Schema.fromJsonString(CanonicalRecord))(
           storedRecord.decoded,
         ).pipe(
@@ -406,6 +425,7 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
             }),
           ),
         );
+
         if (
           storedRecord.row.sequence !== batchRow.first_sequence + index ||
           storedRecord.row.record_id !== expectedRecord.recordId ||
@@ -425,27 +445,27 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
     }
 
     if (
-      conversationRecords.length !== conversation.tail_sequence ||
-      conversation.tail_sequence !== expectedSequence - 1 ||
-      conversation.tail_digest !== previousDigest
+      threadRecords.length !== thread.tail_sequence ||
+      thread.tail_sequence !== expectedSequence - 1 ||
+      thread.tail_digest !== previousDigest
     ) {
       return yield* SqliteStorageCorruptionError.make({
-        table: "effect_agent_conversations",
-        rowKey: conversation.conversation_id,
-        message: "Conversation tail does not match its canonical batch chain.",
+        table: "effect_agent_threads",
+        rowKey: thread.thread_id,
+        message: "Thread tail does not match its canonical batch chain.",
       });
     }
 
-    for (const checkpoint of conversationCheckpoints) {
+    for (const checkpoint of threadCheckpoints) {
       if (
-        checkpoint.decoded.conversationId !== conversation.conversation_id ||
+        checkpoint.decoded.threadId !== thread.thread_id ||
         checkpoint.decoded.throughSequence !== checkpoint.row.through_sequence ||
         checkpoint.decoded.tailDigest !== checkpoint.row.tail_digest ||
         tailDigests.get(checkpoint.row.through_sequence) !== checkpoint.row.tail_digest
       ) {
         return yield* SqliteStorageCorruptionError.make({
           table: "effect_agent_checkpoints",
-          rowKey: `${conversation.conversation_id}/${checkpoint.row.through_sequence}`,
+          rowKey: `${thread.thread_id}/${checkpoint.row.through_sequence}`,
           message: "Checkpoint identity or digest is not bound to a canonical batch tail.",
         });
       }
@@ -453,48 +473,51 @@ const decodeStartupPayloads = Effect.fn("SqliteConversationStore.decodeStartupPa
   }
 
   if (
-    batches.some(({ row }) => !materializedIds.has(row.conversation_id)) ||
-    records.some(({ row }) => !materializedIds.has(row.conversation_id)) ||
-    checkpoints.some(({ row }) => !materializedIds.has(row.conversation_id))
+    batches.some(({ row }) => !materializedIds.has(row.thread_id)) ||
+    records.some(({ row }) => !materializedIds.has(row.thread_id)) ||
+    checkpoints.some(({ row }) => !materializedIds.has(row.thread_id))
   ) {
     return yield* SqliteStorageCorruptionError.make({
-      table: "effect_agent_conversations",
+      table: "effect_agent_threads",
       rowKey: "startup_scan",
-      message: "Canonical rows exist without a materialized Conversation.",
+      message: "Canonical rows exist without a materialized Thread.",
     });
   }
 });
 
-const makeServices = Effect.fn("SqliteConversationStore.makeServices")(function* () {
+const makeServices = Effect.fn("SqliteThreadStore.makeServices")(function* () {
   const config = yield* SqliteStorageConfig;
   const failpoint = yield* SqliteStorageFailpoint;
-  const sql = yield* SqlClientService.SqlClient;
   const crypto = yield* Crypto.Crypto;
-  const journal = yield* initializeSqliteJournal(sql, failpoint.hit, config.busyTimeout);
+  const journal = yield* initializeSqliteJournal();
+
   if (config.verifyOnOpen) {
     yield* decodeStartupPayloads(journal, crypto);
   }
 
   const provideCrypto = <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>) =>
     Effect.provideService(effect, Crypto.Crypto, crypto);
-  const hitFailpoint = Effect.fn("SqliteConversationStore.hitFailpoint")(
-    (location: SqliteStorageFailpointLocation): Effect.Effect<void, ConversationStoreError> =>
+
+  const hitFailpoint = Effect.fn("SqliteThreadStore.hitFailpoint")(
+    (location: SqliteStorageFailpointLocation): Effect.Effect<void, ThreadStoreError> =>
       failpoint
         .hit(location)
         .pipe(Effect.mapError((error) => storeError(`storage failpoint ${location}`, error))),
   );
 
-  const materialize: ConversationStore["Service"]["materialize"] = Effect.fn(
-    "SqliteConversationStore.materialize",
-  )(function* (request: ConversationMaterialization) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ConversationMaterialization))(
+  const materialize: ThreadStore["Service"]["materialize"] = Effect.fn(
+    "SqliteThreadStore.materialize",
+  )(function* (request: ThreadMaterialization) {
+    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ThreadMaterialization))(
       request,
     ).pipe(Effect.mapError((error) => schemaStoreError("validate materialization", error)));
+
     const now = yield* Clock.currentTimeMillis;
+
     yield* hitFailpoint("materialize:before");
     yield* journal
       .materialize(
-        validated.conversationId,
+        validated.threadId,
         new Date(now).toISOString(),
         EMPTY_TAIL_DIGEST,
         validated.producerEpoch,
@@ -502,24 +525,28 @@ const makeServices = Effect.fn("SqliteConversationStore.makeServices")(function*
       .pipe(
         Effect.mapError((error) =>
           error._tag === "SqliteFenceRejected"
-            ? mapFence(validated.conversationId, error)
-            : storeError("materialize conversation", error),
+            ? mapFence(validated.threadId, error)
+            : storeError("materialize thread", error),
         ),
       );
     yield* hitFailpoint("materialize:after");
   });
 
-  const append: ConversationStore["Service"]["append"] = Effect.fn(
-    "SqliteConversationStore.append",
-  )(function* (request: FencedAppendRequest) {
+  const append: ThreadStore["Service"]["append"] = Effect.fn("SqliteThreadStore.append")(function* (
+    request: FencedAppendRequest,
+  ) {
     const validated = yield* Schema.decodeUnknownEffect(Schema.toType(FencedAppendRequest))(
       request,
     ).pipe(Effect.mapError((error) => schemaStoreError("validate canonical append", error)));
-    yield* requireConversation(journal, validated.conversationId);
+
+    yield* requireThread(journal, validated.threadId);
+
     const tailDigest = yield* provideCrypto(
       digestCanonicalBatch(validated.expectedTailDigest, validated.batch),
     ).pipe(Effect.mapError((error) => storeError("digest canonical append", error)));
+
     const batchJson = yield* encodeCanonicalBatch(validated.batch);
+
     const rawRecords = yield* Effect.forEach(validated.batch.records, (record) =>
       encodeCanonicalRecord(record).pipe(
         Effect.map((recordJson) => ({
@@ -528,8 +555,9 @@ const makeServices = Effect.fn("SqliteConversationStore.makeServices")(function*
         })),
       ),
     );
+
     const rawRequest = yield* Schema.decodeUnknownEffect(RawAppendRequest)({
-      conversationId: validated.conversationId,
+      threadId: validated.threadId,
       batchId: validated.batch.batchId,
       batchDigest: tailDigest,
       batchJson,
@@ -539,27 +567,30 @@ const makeServices = Effect.fn("SqliteConversationStore.makeServices")(function*
       records: rawRecords,
       tailDigest,
     }).pipe(Effect.mapError((error) => schemaStoreError("encode canonical append", error)));
+
     yield* hitFailpoint("append:before");
+
     const result = yield* journal.append(rawRequest).pipe(
       Effect.mapError((error) => {
-        if (error instanceof SqliteFenceRejected) {
-          return mapFence(validated.conversationId, error);
+        if (isSqliteFenceRejected(error)) {
+          return mapFence(validated.threadId, error);
         }
-        if (error instanceof SqliteAppendConflict) {
+        if (isSqliteAppendConflict(error)) {
           return error.actualTailSequence !== undefined && isDigest(error.actualTailDigest)
             ? AppendConflict.make({
-                conversationId: validated.conversationId,
+                threadId: validated.threadId,
                 batchId: validated.batch.batchId,
                 reason: error.reason,
                 actualTailSequence: error.actualTailSequence,
                 actualTailDigest: error.actualTailDigest,
               })
             : AppendConflict.make({
-                conversationId: validated.conversationId,
+                threadId: validated.threadId,
                 batchId: validated.batch.batchId,
                 reason: error.reason,
               });
         }
+
         return storeError("append canonical batch", error);
       }),
       Effect.flatMap((result) =>
@@ -568,224 +599,264 @@ const makeServices = Effect.fn("SqliteConversationStore.makeServices")(function*
         ),
       ),
     );
+
     yield* hitFailpoint("append:after");
+
     return result;
   });
 
-  const loadRecords = Effect.fn("SqliteConversationStore.loadRecords")(function* (
+  const loadRecords = Effect.fn("SqliteThreadStore.loadRecords")(function* (
     request: RawReadRequest,
   ) {
     const rows = yield* journal
       .read(request)
       .pipe(Effect.mapError((error) => storeError("read canonical records", error)));
+
     return yield* Effect.forEach(rows, decodeEnvelope);
   });
 
-  const readEffect = Effect.fn("SqliteConversationStore.read")(function* (
-    request: ConversationRead,
-  ) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ConversationRead))(
-      request,
-    ).pipe(Effect.mapError((error) => schemaStoreError("validate conversation read", error)));
-    yield* requireConversation(journal, validated.conversationId);
+  const readEffect = Effect.fn("SqliteThreadStore.read")(function* (request: ThreadRead) {
+    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ThreadRead))(request).pipe(
+      Effect.mapError((error) => schemaStoreError("validate thread read", error)),
+    );
+
+    yield* requireThread(journal, validated.threadId);
+
     const records = yield* loadRecords(
       RawReadRequest.make({
-        conversationId: validated.conversationId,
+        threadId: validated.threadId,
         fromSequenceExclusive: validated.afterSequence ?? ZERO_CANONICAL_SEQUENCE,
         limit: validated.limit,
       }),
     );
+
     return Stream.fromIterable(records);
   });
-  const read: ConversationStore["Service"]["read"] = (request) =>
-    Stream.unwrap(readEffect(request));
 
-  const observeEffect = Effect.fn("SqliteConversationStore.observe")(function* (
-    request: ConversationObservation,
+  const read: ThreadStore["Service"]["read"] = (request) => Stream.unwrap(readEffect(request));
+
+  const observeEffect = Effect.fn("SqliteThreadStore.observe")(function* (
+    request: ThreadObservation,
   ) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ConversationObservation))(
+    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ThreadObservation))(
       request,
-    ).pipe(
-      Effect.mapError((error) => schemaStoreError("validate conversation observation", error)),
-    );
-    yield* requireConversation(journal, validated.conversationId);
-    const initialSequence = yield* parseOffset(validated.conversationId, validated.afterOffset);
+    ).pipe(Effect.mapError((error) => schemaStoreError("validate thread observation", error)));
+
+    yield* requireThread(journal, validated.threadId);
+    const initialSequence = yield* parseOffset(validated.threadId, validated.afterOffset);
     const cursor = yield* Ref.make(initialSequence);
-    const poll = Effect.fn("SqliteConversationStore.observePoll")(function* () {
+
+    const poll = Effect.fn("SqliteThreadStore.observePoll")(function* () {
       const fromSequenceExclusive = yield* Ref.get(cursor);
+
       const records = yield* loadRecords(
         RawReadRequest.make({
-          conversationId: validated.conversationId,
+          threadId: validated.threadId,
           fromSequenceExclusive,
           limit: 1_024,
         }),
       );
+
       if (records.length === 0) {
         yield* Effect.sleep(config.observationPollInterval);
+
         return [];
       }
       yield* Ref.set(cursor, records[records.length - 1].sequence);
+
       return records;
     });
+
     return Stream.fromIterableEffectRepeat(poll());
   });
-  const observe: ConversationStore["Service"]["observe"] = (request) =>
+
+  const observe: ThreadStore["Service"]["observe"] = (request) =>
     Stream.unwrap(observeEffect(request));
 
-  const exportConversation: ConversationStore["Service"]["export"] = Effect.fn(
-    "SqliteConversationStore.export",
-  )(function* (request: ConversationExportRequest) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ConversationExportRequest))(
-      request,
-    ).pipe(Effect.mapError((error) => schemaStoreError("validate conversation export", error)));
-    yield* requireConversation(journal, validated.conversationId);
-    const exported = yield* journal
-      .exportConversation(validated.conversationId)
-      .pipe(Effect.mapError((error) => storeError("export conversation", error)));
-    const records = yield* Effect.forEach(exported.records, decodeEnvelope);
-    if (records.length > 65_536) {
-      return yield* ConversationStoreError.make({
-        operation: "decode conversation export",
-        message: "The conversation exceeds the current export record limit.",
+  const exportThread: ThreadStore["Service"]["export"] = Effect.fn("SqliteThreadStore.export")(
+    function* (request: ThreadExportRequest) {
+      const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ThreadExportRequest))(
+        request,
+      ).pipe(Effect.mapError((error) => schemaStoreError("validate thread export", error)));
+
+      yield* requireThread(journal, validated.threadId);
+
+      const exported = yield* journal
+        .exportThread(validated.threadId)
+        .pipe(Effect.mapError((error) => storeError("export thread", error)));
+
+      const records = yield* Effect.forEach(exported.records, decodeEnvelope);
+
+      if (records.length > 65_536) {
+        return yield* ThreadStoreError.make({
+          operation: "decode thread export",
+          message: "The thread exceeds the current export record limit.",
+        });
+      }
+
+      const tailDigest = yield* Schema.decodeUnknownEffect(Digest)(
+        exported.thread.tail_digest,
+      ).pipe(Effect.mapError((error) => schemaStoreError("decode export tail digest", error)));
+
+      return ThreadExport.make({
+        format: "effect-agent/thread@1",
+        threadId: validated.threadId,
+        tailSequence: exported.thread.tail_sequence,
+        tailDigest,
+        records,
       });
-    }
-    const tailDigest = yield* Schema.decodeUnknownEffect(Digest)(
-      exported.conversation.tail_digest,
-    ).pipe(Effect.mapError((error) => schemaStoreError("decode export tail digest", error)));
-    return ConversationExport.make({
-      format: "effect-agent/conversation@1",
-      conversationId: validated.conversationId,
-      tailSequence: exported.conversation.tail_sequence,
-      tailDigest,
-      records,
-    });
-  });
+    },
+  );
 
-  const inspectTail: ConversationStore["Service"]["inspectTail"] = Effect.fn(
-    "SqliteConversationStore.inspectTail",
-  )(function* (request: ConversationTailRequest) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ConversationTailRequest))(
+  const inspectTail: ThreadStore["Service"]["inspectTail"] = Effect.fn(
+    "SqliteThreadStore.inspectTail",
+  )(function* (request: ThreadTailRequest) {
+    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(ThreadTailRequest))(
       request,
     ).pipe(Effect.mapError((error) => schemaStoreError("validate tail inspection", error)));
-    const conversation = yield* requireConversation(journal, validated.conversationId);
-    const tailDigest = yield* Schema.decodeUnknownEffect(Digest)(conversation.tail_digest).pipe(
+
+    const thread = yield* requireThread(journal, validated.threadId);
+
+    const tailDigest = yield* Schema.decodeUnknownEffect(Digest)(thread.tail_digest).pipe(
       Effect.mapError((error) => schemaStoreError("decode tail digest", error)),
     );
-    return ConversationTail.make({
-      conversationId: validated.conversationId,
-      tailSequence: conversation.tail_sequence,
+
+    return ThreadTail.make({
+      threadId: validated.threadId,
+      tailSequence: thread.tail_sequence,
       tailDigest,
-      producerEpoch: conversation.producer_epoch,
+      producerEpoch: thread.producer_epoch,
     });
   });
 
-  const saveCheckpoint: ConversationStore["Service"]["saveCheckpoint"] = Effect.fn(
-    "SqliteConversationStore.saveCheckpoint",
-  )(function* (request: SaveCheckpointRequest) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(SaveCheckpointRequest))(
-      request,
-    ).pipe(Effect.mapError((error) => schemaStoreError("validate checkpoint", error)));
-    const conversation = yield* requireConversation(journal, validated.checkpoint.conversationId);
-    if (validated.checkpoint.throughSequence > conversation.tail_sequence) {
-      return yield* CheckpointRejected.make({
-        conversationId: validated.checkpoint.conversationId,
-        reason: "ahead-of-tail",
-      });
-    }
-    const canonicalDigest = yield* tailDigestAt(
-      journal,
-      validated.checkpoint.conversationId,
-      validated.checkpoint.throughSequence,
-    );
-    if (canonicalDigest !== validated.checkpoint.tailDigest) {
-      return yield* CheckpointRejected.make({
-        conversationId: validated.checkpoint.conversationId,
-        reason: "digest-mismatch",
-      });
-    }
-    const checkpointJson = yield* encodeCheckpoint(validated.checkpoint);
-    const raw = RawCheckpoint.make({
-      conversationId: validated.checkpoint.conversationId,
-      throughSequence: validated.checkpoint.throughSequence,
-      tailDigest: validated.checkpoint.tailDigest,
-      checkpointJson,
-    });
-    yield* hitFailpoint("save-checkpoint:before");
-    yield* journal.saveCheckpoint(raw).pipe(
-      Effect.mapError((error) =>
-        error instanceof SqliteCheckpointConflict
-          ? CheckpointRejected.make({
-              conversationId: validated.checkpoint.conversationId,
-              reason: "digest-mismatch",
-            })
-          : storeError("save checkpoint", error),
-      ),
-    );
-    yield* hitFailpoint("save-checkpoint:after");
-  });
+  const saveCheckpoint: ThreadCheckpoints["save"] = Effect.fn("SqliteThreadStore.saveCheckpoint")(
+    function* (request: SaveCheckpointRequest) {
+      const validated = yield* Schema.decodeUnknownEffect(Schema.toType(SaveCheckpointRequest))(
+        request,
+      ).pipe(Effect.mapError((error) => schemaStoreError("validate checkpoint", error)));
 
-  const loadCheckpoint: ConversationStore["Service"]["loadCheckpoint"] = Effect.fn(
-    "SqliteConversationStore.loadCheckpoint",
-  )(function* (request: LoadCheckpointRequest) {
-    const validated = yield* Schema.decodeUnknownEffect(Schema.toType(LoadCheckpointRequest))(
-      request,
-    ).pipe(Effect.mapError((error) => schemaStoreError("validate checkpoint lookup", error)));
-    const conversation = yield* requireConversation(journal, validated.conversationId);
-    const rows = yield* journal
-      .loadCheckpoint(
-        validated.conversationId,
-        validated.atOrBeforeSequence ?? conversation.tail_sequence,
-      )
-      .pipe(Effect.mapError((error) => storeError("load checkpoint", error)));
-    if (rows.length === 0) return Option.none();
-    if (rows.length !== 1) {
-      return yield* ConversationStoreError.make({
-        operation: "load checkpoint",
-        message: `Expected at most one checkpoint row but found ${rows.length}.`,
-      });
-    }
-    const checkpoint = yield* decodeCheckpoint(rows[0].checkpoint_json);
-    const canonicalDigest = yield* tailDigestAt(
-      journal,
-      checkpoint.conversationId,
-      checkpoint.throughSequence,
-    );
-    if (canonicalDigest !== checkpoint.tailDigest) {
-      return yield* CheckpointRejected.make({
-        conversationId: checkpoint.conversationId,
-        reason: "digest-mismatch",
+      const thread = yield* requireThread(journal, validated.checkpoint.threadId);
+
+      if (validated.checkpoint.throughSequence > thread.tail_sequence) {
+        return yield* CheckpointRejected.make({
+          threadId: validated.checkpoint.threadId,
+          reason: "ahead-of-tail",
+        });
+      }
+
+      const canonicalDigest = yield* tailDigestAt(
+        journal,
+        validated.checkpoint.threadId,
+        validated.checkpoint.throughSequence,
+      );
+
+      if (canonicalDigest !== validated.checkpoint.tailDigest) {
+        return yield* CheckpointRejected.make({
+          threadId: validated.checkpoint.threadId,
+          reason: "digest-mismatch",
+        });
+      }
+      const checkpointJson = yield* encodeCheckpoint(validated.checkpoint);
+
+      const raw = RawCheckpoint.make({
+        threadId: validated.checkpoint.threadId,
+        throughSequence: validated.checkpoint.throughSequence,
+        tailDigest: validated.checkpoint.tailDigest,
+        checkpointJson,
       });
-    }
-    return Option.some(checkpoint);
-  });
 
-  const conversationStore = ConversationStore.of({
+      yield* hitFailpoint("save-checkpoint:before");
+      yield* journal.saveCheckpoint(raw).pipe(
+        Effect.mapError((error) =>
+          isSqliteCheckpointConflict(error)
+            ? CheckpointRejected.make({
+                threadId: validated.checkpoint.threadId,
+                reason: "digest-mismatch",
+              })
+            : storeError("save checkpoint", error),
+        ),
+      );
+      yield* hitFailpoint("save-checkpoint:after");
+    },
+  );
+
+  const loadCheckpoint: ThreadCheckpoints["load"] = Effect.fn("SqliteThreadStore.loadCheckpoint")(
+    function* (request: LoadCheckpointRequest) {
+      const validated = yield* Schema.decodeUnknownEffect(Schema.toType(LoadCheckpointRequest))(
+        request,
+      ).pipe(Effect.mapError((error) => schemaStoreError("validate checkpoint lookup", error)));
+
+      const thread = yield* requireThread(journal, validated.threadId);
+
+      const rows = yield* journal
+        .loadCheckpoint(validated.threadId, validated.atOrBeforeSequence ?? thread.tail_sequence)
+        .pipe(Effect.mapError((error) => storeError("load checkpoint", error)));
+
+      if (rows.length === 0) return Option.none();
+      if (rows.length !== 1) {
+        return yield* ThreadStoreError.make({
+          operation: "load checkpoint",
+          message: `Expected at most one checkpoint row but found ${rows.length}.`,
+        });
+      }
+      const row = rows[0];
+      const checkpoint = yield* decodeCheckpoint(row.checkpoint_json);
+
+      if (
+        row.thread_id !== validated.threadId ||
+        checkpoint.threadId !== row.thread_id ||
+        checkpoint.throughSequence !== row.through_sequence ||
+        checkpoint.tailDigest !== row.tail_digest
+      ) {
+        return yield* ThreadStoreError.make({
+          operation: "load checkpoint",
+          message: "Stored checkpoint metadata does not match its canonical row.",
+        });
+      }
+
+      const canonicalDigest = yield* tailDigestAt(
+        journal,
+        checkpoint.threadId,
+        checkpoint.throughSequence,
+      );
+
+      if (canonicalDigest !== checkpoint.tailDigest) {
+        return yield* CheckpointRejected.make({
+          threadId: checkpoint.threadId,
+          reason: "digest-mismatch",
+        });
+      }
+
+      return Option.some(checkpoint);
+    },
+  );
+
+  const threadStore = ThreadStore.of({
     append,
-    export: exportConversation,
+    export: exportThread,
     inspectTail,
-    loadCheckpoint,
     materialize,
     observe,
     read,
-    saveCheckpoint,
+    checkpoints: { save: saveCheckpoint, load: loadCheckpoint },
   });
 
-  return Context.make(ConversationStore, conversationStore);
+  return Context.make(ThreadStore, threadStore);
 });
 
 /**
- * SQLite Conversation Store implementation with configuration, failpoint, SQL, and Crypto
+ * SQLite Thread Store implementation with configuration, failpoint, SQL, and Crypto
  * authority kept visible in its input channel.
  */
-export const conversationStoreLayer: Layer.Layer<
-  ConversationStore,
+export const threadStoreLayer: Layer.Layer<
+  ThreadStore,
   SqliteStorageInitializationError,
   SqliteStorageConfig | SqliteStorageFailpoint | SqlClientService.SqlClient | Crypto.Crypto
 > = Layer.effectContext(makeServices());
 
 /**
  * Validated SQLite storage configuration Layer with the documented defaults applied. Shared
- * by the ConversationStore and SubmissionLedger convenience layers so their defaults cannot
+ * by the ThreadStore and SubmissionLedger convenience layers so their defaults cannot
  * drift.
  */
 export const storageConfigLayer = (
@@ -818,24 +889,23 @@ export const storageFailpointLayer = (
     : Layer.succeed(SqliteStorageFailpoint)({ hit: options.failpoint });
 
 /**
- * A composition-root convenience Layer for canonical Conversations. Durable accepted work is
+ * A composition-root convenience Layer for canonical Threads. Durable accepted work is
  * served by the separate SubmissionLedger port.
  */
 export const layer = (
   options: SqliteStorageOptions,
-): Layer.Layer<ConversationStore, SqliteStorageInitializationError> => {
-  const sqlLayer = SqliteClient.layer({ filename: options.filename });
-  return conversationStoreLayer.pipe(
-    Layer.provide(
-      Layer.mergeAll(
-        storageConfigLayer(options),
-        storageFailpointLayer(options),
-        sqlLayer,
-        NodeCrypto.layer,
+): Layer.Layer<ThreadStore, SqliteStorageInitializationError> =>
+  Layer.unwrap(
+    Effect.map(SqliteStorageConfig, (config) =>
+      threadStoreLayer.pipe(
+        Layer.provide(
+          Layer.mergeAll(
+            Layer.succeed(SqliteStorageConfig)(config),
+            storageFailpointLayer(options),
+            SqliteClient.layer({ filename: options.filename }),
+            NodeCrypto.layer,
+          ),
+        ),
       ),
     ),
-  );
-};
-
-/** Create an adapter-owned resumable observation offset for a known canonical sequence. */
-export const observationOffsetAt = makeOffset;
+  ).pipe(Layer.provide(storageConfigLayer(options)));