@afokapu/atdd-flow 0.3.7 → 0.3.8

package/src/threads.ts

@@ -1,8 +1,9 @@
-import { readdir } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
 import { notify } from "./adapters";
 import {
   atomicYaml, canonicalAddress, desk, has, id, now, paths, project, readYaml,
-  required, seat, words,
+  required, runtimeAddress, seat, words,
 } from "./core";
 
 export type Thread = { schema: string; id: string; subject: string; participants: string[]; state: "open" | "closed"; summary?: string; task?: string };
@@ -74,18 +75,135 @@ async function assertRoute(root: string, from: string, recipients: string[]) {
   }
 }
 
-async function inject(root: string, address: string, message: Message, threadId: string) {
+type PendingReference = { thread: string; message: string; created_at: string; published?: boolean };
+type PendingSegment = { schema: "atdd-flow/pi-inbox-segment/v1"; entries: PendingReference[]; next?: string };
+type PendingQueue = { schema: "atdd-flow/pi-inbox-queue/v1"; head?: string; tail?: string };
+
+function inboxDirectory(root: string, address: string) {
+  return join(root, ".atdd-flow", "pi-inbox", encodeURIComponent(address));
+}
+
+const pause = (milliseconds: number) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+/** mkdir is atomic across CLI processes; stale locks are recoverable after a crashed writer. */
+async function withInboxLock<T>(directory: string, action: () => Promise<T>) {
+  await mkdir(directory, { recursive: true });
+  const lock = join(directory, "queue.lock");
+  for (let attempt = 0; attempt < 200; attempt += 1) {
+    try {
+      await mkdir(lock, { recursive: false });
+      try { return await action(); }
+      finally { await rm(lock, { recursive: true, force: true }); }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - (await stat(lock)).mtimeMs > 30_000) await rm(lock, { recursive: true, force: true });
+        else await pause(5);
+      } catch { await pause(5); }
+    }
+  }
+  throw new Error(`Timed out waiting for inbox queue lock ${directory}`);
+}
+
+/** The queue is a bounded linked index: recovery reads only its head segment, never Desk history. */
+type YamlWriter = (path: string, value: unknown) => Promise<void>;
+
+export async function enqueueNativeMail(root: string, address: string, reference: PendingReference, writeYaml: YamlWriter = atomicYaml) {
+  const directory = inboxDirectory(root, address);
+  return withInboxLock(directory, async () => {
+    const statePath = join(directory, "queue.yaml");
+    let queue: PendingQueue;
+    try { queue = await readYaml<PendingQueue>(statePath); }
+    catch { queue = { schema: "atdd-flow/pi-inbox-queue/v1" }; }
+    const entriesPath = (segment: string) => join(directory, "pending", `${segment}.yaml`);
+    const compare = (left: PendingReference, right: PendingReference) => left.created_at.localeCompare(right.created_at) || left.message.localeCompare(right.message);
+    const capacity = 32;
+    if (!queue.head) {
+      const segment = `S-${reference.message}`;
+      await writeYaml(entriesPath(segment), { schema: "atdd-flow/pi-inbox-segment/v1", entries: [reference] } satisfies PendingSegment);
+      queue.head = segment;
+      queue.tail = segment;
+      await writeYaml(statePath, queue);
+      return segment;
+    }
+    // Insert under the same process-safe lock. A full segment spills its latest reference forward, preserving global created_at/message order across rollover.
+    let pending = reference;
+    let current = queue.head;
+    let referenceSegment: string | undefined;
+    while (current) {
+      const record = await readYaml<PendingSegment>(entriesPath(current));
+      record.entries.push(pending);
+      record.entries.sort(compare);
+      if (record.entries.some((entry) => entry.message === reference.message)) referenceSegment = current;
+      if (record.entries.length <= capacity) {
+        await writeYaml(entriesPath(current), record);
+        return referenceSegment ?? current;
+      }
+      pending = record.entries.pop()!;
+      if (pending.message === reference.message) referenceSegment = undefined;
+      if (record.next) {
+        await writeYaml(entriesPath(current), record);
+        current = record.next;
+        continue;
+      }
+      const next = `S-${pending.message}`;
+      // A child must be durable before its parent publishes the link. A crash or
+      // failed write can leave an unlinked orphan, but never a reachable hole.
+      await writeYaml(entriesPath(next), { schema: "atdd-flow/pi-inbox-segment/v1", entries: [pending] } satisfies PendingSegment);
+      record.next = next;
+      await writeYaml(entriesPath(current), record);
+      queue.tail = next;
+      await writeYaml(statePath, queue);
+      return referenceSegment ?? next;
+    }
+    throw new Error("Pending inbox queue has no reachable tail");
+  });
+}
+
+async function publishNativeMail(root: string, address: string, _segment: string, message: string) {
+  const directory = inboxDirectory(root, address);
+  await withInboxLock(directory, async () => {
+    const queue = await readYaml<PendingQueue>(join(directory, "queue.yaml"));
+    let segment = queue.head;
+    while (segment) {
+      const path = join(directory, "pending", `${segment}.yaml`);
+      const record = await readYaml<PendingSegment>(path);
+      const entry = record.entries.find((candidate) => candidate.message === message);
+      if (entry) {
+        entry.published = true;
+        await atomicYaml(path, record);
+        return;
+      }
+      segment = record.next;
+    }
+    // A reconciler can consume an authoritative M-file reference between message persistence and this advisory marker; that is already a successful, exactly-once delivery.
+  });
+}
+
+async function prepareNativeMail(root: string, address: string, message: Message, threadId: string) {
+  const target = await seat(root, address);
+  if (target.runtime?.wake !== "native" && target.agent !== "pi") return;
+  const segment = await enqueueNativeMail(root, address, { thread: threadId, message: message.id, created_at: message.created_at });
+  return { address, segment };
+}
+
+async function inject(root: string, address: string, message: Message, threadId: string, queued = false) {
   const target = await seat(root, address);
   const runtime = target.runtime;
+  if (runtime?.wake === "native" || target.agent === "pi") {
+    if (!queued) await enqueueNativeMail(root, address, { thread: threadId, message: message.id, created_at: message.created_at, published: true });
+    if (!runtime || runtime.wake === "native") return;
+  }
   if (!runtime) return;
-  if (runtime.wake === "native") return;
-  const nativeAddress = runtime.addresses[runtime.application];
-  if (!nativeAddress) return;
+  const storedAddress = runtime.addresses[runtime.application];
+  if (!storedAddress) return;
+  const config = await desk(root);
+  const locator = runtimeAddress(runtime.application, storedAddress, config.herdr_session);
   const record = await thread(root, threadId);
   const recipients = message.to === "all" ? "all" : message.to.join(", ");
   const subject = record.subject.replace(/\s+/g, " ").trim();
   const notice = `SYSTEM: Flow mail ${message.id} | thread ${threadId} (${subject}) | ${message.from} → ${recipients}. Read: atdd-flow message read ${message.id}`;
-  try { await notify(runtime.application, nativeAddress, notice, (await desk(root)).herdr_session); }
+  try { await notify(runtime.application, locator.address, notice, locator.session); }
   catch (error) { console.warn(`Notification for ${address} was not delivered: ${(error as Error).message}`); }
 }
 
@@ -97,24 +215,31 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   const recipients = Array.isArray(toValue) ? toValue : await resolveRecipients(root, toValue, record.participants);
   if (recipients.some((address) => !record.participants.includes(address))) throw new Error("Recipients must be thread participants.");
   await assertRoute(root, from, recipients.filter((address) => address !== from));
+  const kind = overrides.kind ?? "message";
+  // Labels are an explicit, non-sensitive operator hint; message bodies never enter durable IDs.
+  const label = words(args, "--label") ?? kind;
   const message: Message = {
-    schema: "atdd-workflow/message/v1", id: id("M"), from, to: toValue === "all" ? "all" : recipients,
-    kind: overrides.kind ?? "message",
+    schema: "atdd-workflow/message/v1", id: id("M", label), from, to: toValue === "all" ? "all" : recipients,
+    kind,
     ...(overrides.in_reply_to ? { in_reply_to: overrides.in_reply_to } : {}),
     ...(overrides.expects_result || has(args, "--expects-result") ? { expects_result: true } : {}),
     created_at: now(), body: required(overrides.body ?? words(args, "--body"), "--body"),
   };
+  const prepared = await Promise.all(recipients.filter((address) => address !== from).map((recipient) => prepareNativeMail(root, recipient, message, threadId)));
+  // The durable queue is published before the authoritative message: a crash can leave only a harmless uncommitted reference, never durable mail without recovery.
   await atomicYaml(paths(root).message(threadId, message.id), message);
-  await Promise.all(recipients.filter((address) => address !== from).map((recipient) => inject(root, recipient, message, threadId)));
+  await Promise.all(prepared.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry)).map((entry) => publishNativeMail(root, entry.address, entry.segment, message.id)));
+  await Promise.all(recipients.filter((address) => address !== from).map((recipient) => inject(root, recipient, message, threadId, prepared.some((entry) => entry?.address === recipient))));
   console.log(message.id);
 }
 
 export async function startThread(root: string, args: string[]) {
   const participants = await resolveRecipients(root, required(words(args, "--with"), "--with"), []);
   if (participants.length < 2) throw new Error("A thread needs at least two participants.");
+  const subject = required(words(args, "--subject"), "--subject");
   const record: Thread = {
-    schema: "atdd-workflow/thread/v1", id: id("T"), participants,
-    subject: required(words(args, "--subject"), "--subject"), state: "open",
+    schema: "atdd-workflow/thread/v1", id: id("T", subject), participants,
+    subject, state: "open",
     ...(words(args, "--task") ? { task: words(args, "--task") } : {}),
   };
   await atomicYaml(paths(root).threadFile(record.id), record);