@rubytech/create-realagent 1.0.826 → 1.0.828

package/payload/platform/plugins/whatsapp-import/lib/src/__tests__/delta-append.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from "vitest";
+import { findDeltaCursor } from "../delta-cursor.js";
+import {
+  deriveConversationIdentity,
+  deriveMessageContentHash,
+  normaliseSenderName,
+} from "../derive-keys.js";
+import type { ParsedLine } from "../parse-export.js";
+
+function mk(dateSent: string, senderName: string, body: string): ParsedLine {
+  return { dateSent, senderName, body, sequenceIndex: 0 };
+}
+
+describe("deriveConversationIdentity", () => {
+  it("is stable across participant order (sorted internally)", () => {
+    const a = deriveConversationIdentity({
+      accountId: "acct-1",
+      participantElementIds: ["1:abc:1", "1:abc:2"],
+    });
+    const b = deriveConversationIdentity({
+      accountId: "acct-1",
+      participantElementIds: ["1:abc:2", "1:abc:1"],
+    });
+    expect(a).toBe(b);
+  });
+
+  it("changes when accountId differs", () => {
+    const a = deriveConversationIdentity({
+      accountId: "acct-1",
+      participantElementIds: ["1:abc:1", "1:abc:2"],
+    });
+    const b = deriveConversationIdentity({
+      accountId: "acct-2",
+      participantElementIds: ["1:abc:1", "1:abc:2"],
+    });
+    expect(a).not.toBe(b);
+  });
+
+  it("rejects empty participant array", () => {
+    expect(() =>
+      deriveConversationIdentity({
+        accountId: "acct-1",
+        participantElementIds: [],
+      }),
+    ).toThrow(/non-empty/);
+  });
+
+  it("rejects empty accountId", () => {
+    expect(() =>
+      deriveConversationIdentity({
+        accountId: "",
+        participantElementIds: ["1:abc:1"],
+      }),
+    ).toThrow(/accountId/);
+  });
+
+  it("treats DM and group identically (same formula, different array length)", () => {
+    const dm = deriveConversationIdentity({
+      accountId: "acct-1",
+      participantElementIds: ["1:a:1", "1:a:2"],
+    });
+    const group = deriveConversationIdentity({
+      accountId: "acct-1",
+      participantElementIds: ["1:a:1", "1:a:2", "1:a:3"],
+    });
+    expect(dm).not.toBe(group);
+    // Both must hex-decode to a sha256 (64 hex chars).
+    expect(dm).toMatch(/^[a-f0-9]{64}$/);
+    expect(group).toMatch(/^[a-f0-9]{64}$/);
+  });
+});
+
+describe("deriveMessageContentHash", () => {
+  it("is content-only — no archive bytes contribute", () => {
+    const a = deriveMessageContentHash({
+      dateSent: "2026-03-14T10:00:00+00:00",
+      senderName: "Joel",
+      body: "hi",
+    });
+    const b = deriveMessageContentHash({
+      dateSent: "2026-03-14T10:00:00+00:00",
+      senderName: "Joel",
+      body: "hi",
+    });
+    expect(a).toBe(b);
+  });
+
+  it("changes when any field changes", () => {
+    const base = {
+      dateSent: "2026-03-14T10:00:00+00:00",
+      senderName: "Joel",
+      body: "hi",
+    };
+    expect(deriveMessageContentHash(base)).not.toBe(
+      deriveMessageContentHash({ ...base, body: "hello" }),
+    );
+    expect(deriveMessageContentHash(base)).not.toBe(
+      deriveMessageContentHash({ ...base, senderName: "Adam" }),
+    );
+    expect(deriveMessageContentHash(base)).not.toBe(
+      deriveMessageContentHash({ ...base, dateSent: "2026-03-14T10:00:01+00:00" }),
+    );
+  });
+
+  it("collapses NFKC-equivalent sender names to one hash", () => {
+    const a = deriveMessageContentHash({
+      dateSent: "2026-03-14T10:00:00+00:00",
+      senderName: "  ADAM Mackay  ",
+      body: "hi",
+    });
+    const b = deriveMessageContentHash({
+      dateSent: "2026-03-14T10:00:00+00:00",
+      senderName: "adam mackay",
+      body: "hi",
+    });
+    expect(a).toBe(b);
+  });
+});
+
+describe("normaliseSenderName", () => {
+  it("returns NFKC-trim-lower form", () => {
+    expect(normaliseSenderName("  Adam Mackay  ")).toBe("adam mackay");
+  });
+});
+
+describe("findDeltaCursor", () => {
+  const lines: ParsedLine[] = [
+    mk("2026-03-14T10:00:00+00:00", "Joel", "first"),
+    mk("2026-03-14T10:01:00+00:00", "Adam", "second"),
+    mk("2026-03-14T10:02:00+00:00", "Joel", "third"),
+  ];
+  const hashFor = (l: ParsedLine) =>
+    deriveMessageContentHash({
+      dateSent: l.dateSent,
+      senderName: l.senderName,
+      body: l.body,
+    });
+
+  it("returns 'found' with deltaStart = cursor + 1 when the hash matches a prior line", () => {
+    const result = findDeltaCursor(lines, hashFor(lines[0]));
+    expect(result).toEqual({ kind: "found", deltaStart: 1 });
+  });
+
+  it("returns 'empty' when the cursor is the last line (no new messages)", () => {
+    const result = findDeltaCursor(lines, hashFor(lines[2]));
+    expect(result).toEqual({ kind: "empty" });
+  });
+
+  it("returns 'missing' when no parsed line matches (LOUD-FAIL upstream)", () => {
+    const result = findDeltaCursor(lines, "deadbeef".repeat(8));
+    expect(result).toEqual({ kind: "missing" });
+  });
+
+  it("returns 'missing' for an empty parsed sequence (cursor cannot exist)", () => {
+    const result = findDeltaCursor([], hashFor(lines[0]));
+    expect(result).toEqual({ kind: "missing" });
+  });
+
+  it("rejects empty cursor hash", () => {
+    expect(() => findDeltaCursor(lines, "")).toThrow(/non-empty/);
+    expect(() => findDeltaCursor(lines, "   ")).toThrow(/non-empty/);
+  });
+});

package/payload/platform/plugins/whatsapp-import/lib/src/__tests__/sessionize.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect } from "vitest";
+import { sessionize } from "../sessionize.js";
+import type { ParsedLine } from "../parse-export.js";
+
+function mk(dateSent: string, body = "x"): ParsedLine {
+  return { senderName: "Joel", dateSent, body, sequenceIndex: 0 };
+}
+
+describe("sessionize", () => {
+  it("returns [] for empty input", () => {
+    expect(sessionize([], 12)).toEqual([]);
+  });
+
+  it("returns one one-message session for a single message", () => {
+    const out = sessionize([mk("2026-03-14T10:00:00+00:00")], 12);
+    expect(out).toHaveLength(1);
+    expect(out[0].messages).toHaveLength(1);
+    expect(out[0].index).toBe(0);
+    expect(out[0].firstMessageAt).toBe("2026-03-14T10:00:00+00:00");
+    expect(out[0].lastMessageAt).toBe("2026-03-14T10:00:00+00:00");
+  });
+
+  it("groups messages within the gap into one session", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-14T11:00:00+00:00"),
+      mk("2026-03-14T12:00:00+00:00"),
+    ];
+    const out = sessionize(messages, 12);
+    expect(out).toHaveLength(1);
+    expect(out[0].messages).toHaveLength(3);
+  });
+
+  it("cuts at gap > gapHours", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-14T11:00:00+00:00"),
+      mk("2026-03-14T23:30:00+00:00"), // 12.5h gap from previous
+      mk("2026-03-15T00:00:00+00:00"),
+    ];
+    const out = sessionize(messages, 12);
+    expect(out).toHaveLength(2);
+    expect(out[0].messages).toHaveLength(2);
+    expect(out[1].messages).toHaveLength(2);
+    expect(out[1].index).toBe(1);
+  });
+
+  it("cuts at exact-at-threshold (gap == gapHours triggers a cut)", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-14T22:00:00+00:00"), // exactly 12h gap
+    ];
+    const out = sessionize(messages, 12);
+    expect(out).toHaveLength(2);
+  });
+
+  it("does not cut at gap just under threshold", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-14T21:59:59+00:00"), // 11h59m59s gap
+    ];
+    const out = sessionize(messages, 12);
+    expect(out).toHaveLength(1);
+  });
+
+  it("emits firstMessageAt / lastMessageAt from the session boundary messages", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-14T11:00:00+00:00"),
+      mk("2026-03-14T12:00:00+00:00"),
+    ];
+    const out = sessionize(messages, 12);
+    expect(out[0].firstMessageAt).toBe("2026-03-14T10:00:00+00:00");
+    expect(out[0].lastMessageAt).toBe("2026-03-14T12:00:00+00:00");
+  });
+
+  it("rejects non-positive gapHours", () => {
+    expect(() => sessionize([mk("2026-03-14T10:00:00+00:00")], 0)).toThrow(/positive/);
+    expect(() => sessionize([mk("2026-03-14T10:00:00+00:00")], -1)).toThrow(/positive/);
+  });
+
+  it("indexes sessions starting at 0 in chronological order", () => {
+    const messages = [
+      mk("2026-03-14T10:00:00+00:00"),
+      mk("2026-03-15T10:00:00+00:00"), // 24h gap
+      mk("2026-03-16T10:00:00+00:00"), // 24h gap
+    ];
+    const out = sessionize(messages, 12);
+    expect(out.map((s) => s.index)).toEqual([0, 1, 2]);
+  });
+});

package/payload/platform/plugins/whatsapp-import/lib/src/__tests__/to-classifier-input.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { toClassifierInput } from "../to-classifier-input.js";
+import type { Session } from "../sessionize.js";
+
+function mkSession(messages: Session["messages"]): Session {
+  return {
+    index: 0,
+    firstMessageAt: messages[0].dateSent,
+    lastMessageAt: messages[messages.length - 1].dateSent,
+    messages,
+  };
+}
+
+describe("toClassifierInput", () => {
+  it("renders one line per message in `[ts] Sender: body` form", () => {
+    const session = mkSession([
+      { senderName: "Joel", dateSent: "2026-03-14T10:00:00+00:00", body: "hi", sequenceIndex: 0 },
+      { senderName: "Adam", dateSent: "2026-03-14T10:01:00+00:00", body: "hey", sequenceIndex: 1 },
+    ]);
+    expect(toClassifierInput(session)).toBe(
+      "[2026-03-14 10:00:00 +00:00] Joel: hi\n[2026-03-14 10:01:00 +00:00] Adam: hey",
+    );
+  });
+
+  it("preserves the operator's offset in the formatted timestamp", () => {
+    const session = mkSession([
+      { senderName: "Joel", dateSent: "2026-03-14T10:00:00+01:00", body: "hi", sequenceIndex: 0 },
+    ]);
+    expect(toClassifierInput(session)).toBe("[2026-03-14 10:00:00 +01:00] Joel: hi");
+  });
+
+  it("normalises a 'Z' offset to +00:00 in the rendered form", () => {
+    const session = mkSession([
+      { senderName: "Joel", dateSent: "2026-03-14T10:00:00Z", body: "hi", sequenceIndex: 0 },
+    ]);
+    expect(toClassifierInput(session)).toBe("[2026-03-14 10:00:00 +00:00] Joel: hi");
+  });
+
+  it("preserves multi-line message bodies verbatim (no escape, internal newlines retained)", () => {
+    const session = mkSession([
+      {
+        senderName: "Joel",
+        dateSent: "2026-03-14T10:00:00+00:00",
+        body: "line one\nline two",
+        sequenceIndex: 0,
+      },
+    ]);
+    expect(toClassifierInput(session)).toBe(
+      "[2026-03-14 10:00:00 +00:00] Joel: line one\nline two",
+    );
+  });
+
+  it("falls back to the raw ISO when the timestamp shape does not match (defensive)", () => {
+    const session = mkSession([
+      { senderName: "Joel", dateSent: "not-an-iso", body: "hi", sequenceIndex: 0 },
+    ]);
+    expect(toClassifierInput(session)).toBe("[not-an-iso] Joel: hi");
+  });
+});

package/payload/platform/plugins/whatsapp-import/lib/src/delta-cursor.ts

@@ -0,0 +1,54 @@
+import type { ParsedLine } from "./parse-export.js";
+import { deriveMessageContentHash } from "./derive-keys.js";
+
+// ---------------------------------------------------------------------------
+// delta-cursor — locate the cursor for delta-append re-imports (Task 891).
+//
+// Pure function. Given a parsed re-export and the `lastIngestedMessageHash`
+// recorded on the prior `:ConversationArchive`, find the position of the
+// matching message in the parsed sequence and return `index + 1` (the slice
+// start for the delta). Three outcomes:
+//
+//   { kind: "found", deltaStart }    → slice parsedLines from deltaStart
+//   { kind: "empty" }                → cursor is the last line; no delta
+//   { kind: "missing" }              → cursor not found (LOUD-FAIL upstream)
+//
+// `missing` covers both the "operator deleted prior messages from the
+// re-export" case and the "operator imported a different chat archive"
+// case. The orchestrator emits `[whatsapp-import] FAIL delta-cursor-missing`
+// and exits non-zero when this surfaces.
+// ---------------------------------------------------------------------------
+
+export type CursorResult =
+  | { kind: "found"; deltaStart: number }
+  | { kind: "empty" }
+  | { kind: "missing" };
+
+/**
+ * Walk parsed lines forward and return the first index whose content hash
+ * matches `lastIngestedMessageHash`. The first match is correct because
+ * messages with identical (dateSent, normalisedSenderName, body) tuples
+ * are genuine duplicates — there is no way to disambiguate them and slicing
+ * after the first occurrence is the chronologically safe choice.
+ */
+export function findDeltaCursor(
+  parsedLines: readonly ParsedLine[],
+  lastIngestedMessageHash: string,
+): CursorResult {
+  if (!lastIngestedMessageHash || !lastIngestedMessageHash.trim()) {
+    throw new Error("findDeltaCursor: lastIngestedMessageHash must be non-empty");
+  }
+  for (let i = 0; i < parsedLines.length; i++) {
+    const line = parsedLines[i];
+    const hash = deriveMessageContentHash({
+      dateSent: line.dateSent,
+      senderName: line.senderName,
+      body: line.body,
+    });
+    if (hash === lastIngestedMessageHash) {
+      if (i === parsedLines.length - 1) return { kind: "empty" };
+      return { kind: "found", deltaStart: i + 1 };
+    }
+  }
+  return { kind: "missing" };
+}

package/payload/platform/plugins/whatsapp-import/lib/src/derive-keys.ts

@@ -1,22 +1,23 @@
 import { createHash } from "node:crypto";
 
 // ---------------------------------------------------------------------------
-// derive-keys — natural-key derivation for whatsapp-import (Task 870).
+// derive-keys — natural-key derivation for whatsapp-import (Task 891,
+// supersedes Task 870's per-message contract).
 //
 // Pure functions. No I/O. The whole point is that re-imports of the same
-// archive collapse to the same Message identity regardless of release-level
-// drift in array indices, hash widths, or arbitrary tiebreakers.
+// archive collapse to the same identity regardless of release-level drift in
+// chunk indices, hash widths, or arbitrary tiebreakers.
 //
-// Key shape (Task 870 brief):
+// Identity contracts (Task 891 brief):
 //
-//   messageId = whatsapp-export:msg:<conversationSha256>:<dateSentISO>
-//                                  :<NFKC-trim-lower(senderName)>
-//                                  :<sha256-hex(body)>
+//   conversationIdentity   = sha256(accountId + ":" + sortedParticipantElementIds.join(","))
+//   messageContentHash     = sha256(dateSent + "|" + NFKC-trim-lower(senderName) + "|" + body)
 //
-// Operator constraint: the same archive must be re-imported with the same
-// `--timezone` flag. Different timezones reinterpret wall-clock instants and
-// will produce drifted messageIds — that is correct semantics, not a bug.
-// Documented in .docs/whatsapp.md natural-key contract section.
+// `conversationIdentity` is stable across re-exports — same operator + same
+// participant set → same identity, regardless of file bytes. DM and group
+// follow the same formula; the difference is the participant array length.
+// `messageContentHash` is content-only (no archive sha256, no chunk index)
+// so cursor lookup survives a fresh re-export of the same chat.
 // ---------------------------------------------------------------------------
 
 export function normaliseSenderName(name: string): string {
@@ -27,33 +28,55 @@ export function sha256Hex(input: string): string {
   return createHash("sha256").update(input).digest("hex");
 }
 
-export interface DeriveMessageIdInput {
-  /** SHA-256 of the source `_chat.txt` bytes — stable across re-imports. */
-  conversationSha256: string;
+export interface DeriveConversationIdentityInput {
+  accountId: string;
+  /**
+   * Element IDs of every confirmed participant (owner + others). Order is
+   * not significant; the function sorts internally so the same set always
+   * produces the same identity.
+   */
+  participantElementIds: readonly string[];
+}
+
+/**
+ * Compute the stable identity for a conversation. Same accountId + same
+ * participant set ⇒ same identity, regardless of message content or export
+ * file bytes. DM and group chats use this identical formula.
+ */
+export function deriveConversationIdentity(
+  input: DeriveConversationIdentityInput,
+): string {
+  if (!input.accountId || !input.accountId.trim()) {
+    throw new Error("deriveConversationIdentity: accountId is required");
+  }
+  if (input.participantElementIds.length === 0) {
+    throw new Error("deriveConversationIdentity: participantElementIds must be non-empty");
+  }
+  const sorted = [...input.participantElementIds].sort();
+  return sha256Hex(`${input.accountId}:${sorted.join(",")}`);
+}
+
+export interface DeriveMessageContentHashInput {
   /** ISO 8601 with timezone offset, as emitted by parseExport. */
   dateSent: string;
   /** Raw senderName from the export line. Normalised internally. */
   senderName: string;
-  /** Raw message body. Hashed internally. */
+  /** Raw message body. */
   body: string;
 }
 
-export function deriveMessageId(input: DeriveMessageIdInput): string {
+/**
+ * Compute a content-only hash for a single message. Used as the delta-append
+ * cursor: `:ConversationArchive.lastIngestedMessageHash` records the hash of
+ * the last ingested message; on re-import, the orchestrator finds the line
+ * with the matching hash and slices everything after it.
+ *
+ * Excludes archive sha256 deliberately — the cursor must survive a fresh
+ * re-export of the same chat (different file bytes, same message tuples).
+ */
+export function deriveMessageContentHash(
+  input: DeriveMessageContentHashInput,
+): string {
   const norm = normaliseSenderName(input.senderName);
-  const bodyHash = sha256Hex(input.body);
-  return `whatsapp-export:msg:${input.conversationSha256}:${input.dateSent}:${norm}:${bodyHash}`;
-}
-
-export interface ObservationContentFields {
-  summary?: string | null;
-  from?: string | null;
-  to?: string | null;
-  subject?: string | null;
-}
-
-export function observationContentHash(fields: ObservationContentFields): string {
-  const parts = [fields.summary, fields.from, fields.to, fields.subject].map(
-    (p) => (p ?? "").normalize("NFKC").trim().toLowerCase(),
-  );
-  return sha256Hex(parts.join("|"));
+  return sha256Hex(`${input.dateSent}|${norm}|${input.body}`);
 }

package/payload/platform/plugins/whatsapp-import/lib/src/index.ts

@@ -5,15 +5,18 @@ export type {
   ParseExportCounters,
   ParsedLine,
 } from "./parse-export.js";
-export { parseFilterArg, applyFilter } from "./filter.js";
-export type { Filter } from "./filter.js";
 export {
   normaliseSenderName,
   sha256Hex,
-  deriveMessageId,
-  observationContentHash,
+  deriveConversationIdentity,
+  deriveMessageContentHash,
 } from "./derive-keys.js";
 export type {
-  DeriveMessageIdInput,
-  ObservationContentFields,
+  DeriveConversationIdentityInput,
+  DeriveMessageContentHashInput,
 } from "./derive-keys.js";
+export { sessionize } from "./sessionize.js";
+export type { Session } from "./sessionize.js";
+export { toClassifierInput } from "./to-classifier-input.js";
+export { findDeltaCursor } from "./delta-cursor.js";
+export type { CursorResult } from "./delta-cursor.js";

package/payload/platform/plugins/whatsapp-import/lib/src/sessionize.ts

@@ -0,0 +1,81 @@
+import type { ParsedLine } from "./parse-export.js";
+
+// ---------------------------------------------------------------------------
+// sessionize — Pass 1 of the chunked-archive pipeline (Task 891).
+//
+// Pure function. Splits a chronologically-ordered sequence of parsed messages
+// into "sessions" wherever the gap between consecutive `dateSent` values
+// exceeds `gapHours`. Each session feeds memory-classify (mode='chat') as a
+// turn-attributed block; the LLM then chunks each session into one or more
+// `:Section:Conversation` rows with summary+keywords (Pass 2).
+//
+// Why deterministic gap-cut, not LLM topic detection:
+//   - The natural cadence of human chat (sleep, working hours, weekend gaps)
+//     produces clean session boundaries that the operator can intuit.
+//   - LLM-only chunking against a 10K-message archive sends 10K messages into
+//     one prompt and pays attention only to the last 1K — gap-cut bounds the
+//     window before the LLM ever sees it.
+//   - The default 12h gap matches one sleep cycle: messages on the same day
+//     belong together; a 14-hour gap (last evening message → next morning) is
+//     a fresh session even when the topic is identical.
+// ---------------------------------------------------------------------------
+
+export interface Session {
+  /** 0-based index across the archive's sessions. */
+  index: number;
+  /** ISO 8601 timestamp of the first message in the session. */
+  firstMessageAt: string;
+  /** ISO 8601 timestamp of the last message in the session. */
+  lastMessageAt: string;
+  /** Messages in the session, chronological. */
+  messages: ParsedLine[];
+}
+
+/**
+ * Split parsed messages into sessions on gaps ≥ `gapHours`. Input must be
+ * pre-sorted by `dateSent` (parse-export emits in file order, which IS
+ * chronological for any well-formed `_chat.txt`).
+ *
+ * Boundary semantics (exact-at-threshold):
+ *   gap == gapHours    → cut here (start a new session)
+ *   gap <  gapHours    → same session
+ *   gap >  gapHours    → cut here
+ *
+ * Empty input returns []; single-message input returns one one-message session.
+ */
+export function sessionize(
+  messages: readonly ParsedLine[],
+  gapHours: number,
+): Session[] {
+  if (gapHours <= 0) {
+    throw new Error(`sessionize: gapHours must be positive, got ${gapHours}`);
+  }
+  if (messages.length === 0) return [];
+
+  const gapMs = gapHours * 60 * 60 * 1000;
+  const sessions: Session[] = [];
+  let currentMessages: ParsedLine[] = [messages[0]];
+
+  const flush = () => {
+    sessions.push({
+      index: sessions.length,
+      firstMessageAt: currentMessages[0].dateSent,
+      lastMessageAt: currentMessages[currentMessages.length - 1].dateSent,
+      messages: currentMessages,
+    });
+  };
+
+  for (let i = 1; i < messages.length; i++) {
+    const prevMs = Date.parse(messages[i - 1].dateSent);
+    const currMs = Date.parse(messages[i].dateSent);
+    const gap = currMs - prevMs;
+    if (gap >= gapMs) {
+      flush();
+      currentMessages = [messages[i]];
+    } else {
+      currentMessages.push(messages[i]);
+    }
+  }
+  flush();
+  return sessions;
+}

package/payload/platform/plugins/whatsapp-import/lib/src/to-classifier-input.ts

@@ -0,0 +1,48 @@
+import type { Session } from "./sessionize.js";
+
+// ---------------------------------------------------------------------------
+// to-classifier-input — Pass 2 input formatter (Task 891).
+//
+// Pure function. Renders one Session as a turn-attributed text block ready
+// to hand to memory-classify (mode='chat'). Format:
+//
+//   [YYYY-MM-DD HH:MM:SS TZ] <Sender>: <body>
+//   [YYYY-MM-DD HH:MM:SS TZ] <Sender>: <body>
+//   ...
+//
+// Multi-line message bodies are kept verbatim (with their internal newlines).
+// The leading `[ts] <Sender>: ` prefix is the only structural addition; the
+// classifier prompt instructs Haiku to preserve it in the chunk `body` so
+// downstream Phase 2 work can recover per-message provenance via snippet
+// matching against the conversation tail.
+//
+// Timezone: each `dateSent` ISO already carries an offset (set by parseExport
+// from the operator's confirmed IANA zone). The renderer prints the
+// human-readable wall-clock for that offset; the trailing "TZ" suffix is the
+// offset itself, not a zone name.
+// ---------------------------------------------------------------------------
+
+export function toClassifierInput(session: Session): string {
+  const lines: string[] = [];
+  for (const m of session.messages) {
+    lines.push(`[${formatWallClock(m.dateSent)}] ${m.senderName}: ${m.body}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Format an ISO 8601 instant with offset as `YYYY-MM-DD HH:MM:SS ±HH:MM`,
+ * preserving the offset that the parser set from the operator's IANA zone.
+ * The wall-clock components are read directly from the ISO string — no
+ * Date construction (which would re-interpret in the local zone).
+ */
+function formatWallClock(iso: string): string {
+  // ISO from parse-export is shaped: "YYYY-MM-DDTHH:MM:SS±HH:MM" (or "Z").
+  const m = iso.match(
+    /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})$/,
+  );
+  if (!m) return iso; // surface the raw value if the shape drifted; pure function never throws on caller-supplied data
+  const [, y, mo, d, h, mi, s, off] = m;
+  const offsetLabel = off === "Z" ? "+00:00" : off;
+  return `${y}-${mo}-${d} ${h}:${mi}:${s} ${offsetLabel}`;
+}