harnery 0.45.1 → 0.46.0

package/src/core/inbox/service.ts

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import {
@@ -12,6 +12,8 @@ import {
   HARNERY_INBOX_STATUS_SCHEMA,
   HarneryInboxCapacityError,
   type HarneryInboxLimits,
+  HarneryInboxMessageConflictError,
+  HarneryInboxMessageHistoryMissingError,
   type HarneryInboxMessageRecordV1,
   type HarneryInboxRecordV1,
   type HarneryInboxStatusV1,
@@ -27,6 +29,8 @@ export interface HarneryInboxServiceOptions {
 }
 
 export interface HarneryInboxSendInput {
+  message_id?: string;
+  replay_only?: boolean;
   sender_instance_id: string | null;
   sender_display_name: string;
   recipient_instance_id: string;
@@ -35,12 +39,22 @@ export interface HarneryInboxSendInput {
 }
 
 export interface HarneryInboxSendReceipt {
-  state: "queued";
+  state: "queued" | "duplicate";
   message_id: string;
   body_bytes: number;
   synced: true;
 }
 
+/** A caller freezes the operation and recipient before its first attempt. */
+export function stableInboxMessageId(operationId: string, recipientInstanceId: string): string {
+  const identity = JSON.stringify([
+    "harnery.inbox-operation/v1",
+    opaqueId(operationId, "operation"),
+    opaqueId(recipientInstanceId, "recipient instance"),
+  ]);
+  return `msg_op_${createHash("sha256").update(identity).digest("hex")}`;
+}
+
 export class HarneryInboxService {
   readonly #options: HarneryInboxServiceOptions;
 
@@ -50,6 +64,12 @@ export class HarneryInboxService {
   }
 
   send(input: HarneryInboxSendInput): HarneryInboxSendReceipt {
+    if (input.replay_only !== undefined && typeof input.replay_only !== "boolean") {
+      throw new Error("invalid replay_only flag");
+    }
+    if (input.replay_only && input.message_id === undefined) {
+      throw new Error("replay requires explicit message id");
+    }
     const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
     const bodyBytes = Buffer.byteLength(input.body);
     const limits = this.#options.limits;
@@ -63,7 +83,10 @@ export class HarneryInboxService {
     const record: HarneryInboxMessageRecordV1 = {
       schema: HARNERY_INBOX_RECORD_SCHEMA,
       kind: "message",
-      message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+      message_id:
+        input.message_id === undefined
+          ? `msg_${this.#options.id?.() ?? randomUUID()}`
+          : opaqueId(input.message_id, "message"),
       sender_instance_id: senderId(input.sender_instance_id),
       sender_display_name: boundedDisplay(input.sender_display_name),
       recipient_instance_id: recipient,
@@ -78,6 +101,24 @@ export class HarneryInboxService {
       readOptions(limits),
       (records) => {
         const projection = project(records);
+        const existing = records.find(
+          (item): item is HarneryInboxMessageRecordV1 =>
+            item.kind === "message" && item.message_id === record.message_id,
+        );
+        if (existing) {
+          assertSameMessage(existing, record);
+          return {
+            result: {
+              state: "duplicate",
+              message_id: existing.message_id,
+              body_bytes: existing.body_bytes,
+              synced: true,
+            },
+          };
+        }
+        if (input.replay_only) {
+          throw new HarneryInboxMessageHistoryMissingError(record.message_id);
+        }
         capacityCheck(projection, record, path, limits);
         return {
           append: [record],
@@ -92,6 +133,52 @@ export class HarneryInboxService {
     );
   }
 
+  /** Append a message created on another machine, keeping its id. Importers
+   * on one machine can race, so the duplicate check runs under the lease. */
+  receive(record: HarneryInboxMessageRecordV1): "received" | "duplicate" {
+    const recipient = opaqueId(record.recipient_instance_id, "recipient instance");
+    const limits = this.#options.limits;
+    if (record.body_bytes === 0 || record.body_bytes > limits.max_message_body_bytes) {
+      throw new HarneryInboxCapacityError(
+        "message_body_limit",
+        record.body_bytes,
+        limits.max_message_body_bytes,
+      );
+    }
+    const incoming: HarneryInboxMessageRecordV1 = {
+      schema: HARNERY_INBOX_RECORD_SCHEMA,
+      kind: "message",
+      message_id: opaqueId(record.message_id, "message"),
+      sender_instance_id: senderId(record.sender_instance_id),
+      sender_display_name: boundedDisplay(record.sender_display_name),
+      ...(record.sender_machine ? { sender_machine: boundedDisplay(record.sender_machine) } : {}),
+      recipient_instance_id: recipient,
+      recipient_display_name: boundedDisplay(record.recipient_display_name),
+      created_at: record.created_at,
+      body: record.body,
+      body_bytes: record.body_bytes,
+    };
+    validateRecord(incoming);
+    const path = inboxPath(this.#options.coord_root, recipient);
+    return updateInboxHistory<HarneryInboxRecordV1, "received" | "duplicate">(
+      path,
+      readOptions(limits),
+      (records) => {
+        const projection = project(records);
+        const existing = records.find(
+          (item): item is HarneryInboxMessageRecordV1 =>
+            item.kind === "message" && item.message_id === incoming.message_id,
+        );
+        if (existing) {
+          assertSameMessage(existing, incoming);
+          return { result: "duplicate" };
+        }
+        capacityCheck(projection, incoming, path, limits);
+        return { append: [incoming], result: "received" };
+      },
+    );
+  }
+
   records(recipientInstanceId: string): HarneryInboxRecordV1[] {
     const records = readCrashSafeJsonlFile<HarneryInboxRecordV1>(
       inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")),
@@ -202,6 +289,24 @@ export class HarneryInboxService {
   }
 }
 
+function assertSameMessage(
+  existing: HarneryInboxMessageRecordV1,
+  incoming: HarneryInboxMessageRecordV1,
+): void {
+  const fields = [
+    "sender_instance_id",
+    "sender_display_name",
+    "sender_machine",
+    "recipient_instance_id",
+    "recipient_display_name",
+    "body",
+    "body_bytes",
+  ] as const;
+  if (fields.some((field) => existing[field] !== incoming[field])) {
+    throw new HarneryInboxMessageConflictError(incoming.message_id);
+  }
+}
+
 /** The shared writer refuses an occupied lease before invoking the update.
  * Briefly retry only that exact refusal so concurrent peer senders both get
  * a chance to append. All validation, authority and I/O failures still fail

package/src/core/inbox/targets.ts

@@ -11,10 +11,14 @@ import {
   nativeInstanceIdV3,
   observeLiveEventLedgerRouteV3,
 } from "../events/v3/live-route-observer.ts";
+import { readRemoteMachines } from "../presence/index.ts";
+import { knownRemoteSenders } from "../presence/mail.ts";
 
 export interface MessageTargetInput {
   name?: string;
   instanceId?: string;
+  /** Refuse a later generation of the same immutable instance. */
+  generationId?: string;
   requireLive?: boolean;
   now?: Date;
 }
@@ -22,11 +26,17 @@ export interface MessageTargetInput {
 export type MessageTargetResult =
   | {
       ok: true;
-      target: { instance_id: string; name: string; delivery: "written-live" | "queued" };
+      target: {
+        instance_id: string;
+        name: string;
+        delivery: "written-live" | "queued" | "remote";
+        /** Set when the recipient lives on another machine (ADR 0222). */
+        machine?: string;
+      };
     }
   | {
       ok: false;
-      code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe";
+      code: "no_peer" | "ambiguous_peer" | "not_live" | "authority_unsafe" | "generation_mismatch";
       message: string;
       candidates?: string[];
     };
@@ -35,6 +45,7 @@ export type MessageTargetResult =
 export function resolveMessageTarget(
   coordRoot: string,
   input: MessageTargetInput,
+  options: { view?: CoordinationViewV3 } = {},
 ): MessageTargetResult {
   const requestedName = normalizeName(input.name);
   const requestedInstance = input.instanceId?.trim();
@@ -49,7 +60,9 @@ export function resolveMessageTarget(
     if (observeLiveEventLedgerRouteV3(coordRoot).state === "blocked") {
       return unsafe("The event ledger cannot establish message recipient authority.");
     }
-    view = requireAuthoritySafeCoordinationViewV3(readCoordinationViewV3(coordRoot));
+    view = requireAuthoritySafeCoordinationViewV3(
+      options.view ?? readCoordinationViewV3(coordRoot),
+    );
     if (!view.source_complete) return unsafe("The event ledger read is incomplete.");
   } catch {
     return unsafe("The event ledger cannot establish message recipient authority.");
@@ -79,6 +92,7 @@ export function resolveMessageTarget(
       {
         instanceId,
         name,
+        generationId: generation.generation_id,
         safe: !diagnostics.some((diagnostic) => diagnostic.authority_blocking),
         fresh:
           generation.phase === "live" && Number.isFinite(age) && age >= 0 && age <= freshnessMs,
@@ -107,6 +121,13 @@ export function resolveMessageTarget(
     };
   }
   const target = selected[0]!;
+  if (input.generationId && input.generationId !== target.generationId) {
+    return {
+      ok: false,
+      code: "generation_mismatch",
+      message: "The recipient generation differs from the exact requested generation.",
+    };
+  }
   if (input.requireLive && !target.fresh) {
     return {
       ok: false,
@@ -125,6 +146,76 @@ export function resolveMessageTarget(
   };
 }
 
+/**
+ * Resolve a recipient on another machine, for a name or instance this
+ * machine's ledger has never seen. Candidates come from peer presence (live
+ * or stale) and from senders this machine has received mail from. Returns
+ * null when nothing matches, so the caller can report the local miss.
+ */
+export function resolveRemoteMessageTarget(
+  coordRoot: string,
+  input: MessageTargetInput,
+): MessageTargetResult | null {
+  const requestedName = normalizeName(input.name);
+  const requestedInstance = input.instanceId?.trim();
+  if (!requestedName && !requestedInstance) return null;
+  // Presence/mail names do not prove an exact V3 generation.
+  if (input.generationId) return null;
+  const live = new Set(
+    readRemoteMachines(coordRoot).flatMap(({ agents }) => agents.map((a) => a.instance_id)),
+  );
+  const known = new Map<string, { instanceId: string; name: string; machine: string }>();
+  for (const { machine, agents } of readRemoteMachines(coordRoot, { includeStale: true })) {
+    for (const agent of agents) {
+      if (agent.name)
+        known.set(agent.instance_id, { instanceId: agent.instance_id, name: agent.name, machine });
+    }
+  }
+  for (const sender of knownRemoteSenders(coordRoot)) {
+    if (!known.has(sender.instance_id)) {
+      known.set(sender.instance_id, {
+        instanceId: sender.instance_id,
+        name: sender.name,
+        machine: sender.machine,
+      });
+    }
+  }
+  const candidates = [...known.values()]
+    .filter(({ instanceId }) => !requestedInstance || instanceId === requestedInstance)
+    .filter(({ name }) => !requestedName || normalizeName(name) === requestedName)
+    .map((candidate) => ({ ...candidate, fresh: live.has(candidate.instanceId) }));
+  if (candidates.length === 0) return null;
+  const fresh = candidates.filter(({ fresh }) => fresh);
+  const selected = requestedInstance ? candidates : fresh.length > 0 ? fresh : candidates;
+  if (selected.length !== 1) {
+    return {
+      ok: false,
+      code: "ambiguous_peer",
+      message:
+        "Several agent instances on other machines hold that exact name; specify --instance-id.",
+      candidates: selected.map(({ instanceId, machine }) => `${instanceId} (${machine})`).sort(),
+    };
+  }
+  const target = selected[0]!;
+  if (input.requireLive && !target.fresh) {
+    return {
+      ok: false,
+      code: "not_live",
+      message:
+        "That agent is on another machine and outside live presence; omit --require-live to queue its message.",
+    };
+  }
+  return {
+    ok: true,
+    target: {
+      instance_id: target.instanceId,
+      name: target.name,
+      delivery: "remote",
+      machine: target.machine,
+    },
+  };
+}
+
 function laterPosition(
   left: CoordinationGenerationViewV3,
   right: CoordinationGenerationViewV3,

package/src/core/presence/git.ts

@@ -1,5 +1,6 @@
 /**
- * Git plumbing for the cross-machine presence transport (ADR 0016).
+ * Git plumbing for the cross-machine presence transport (ADR 0016) and the
+ * mail refs that ride on it (ADR 0222).
  *
  * Presence blobs travel as parentless commits (empty tree, JSON message)
  * force-pushed to `refs/harnery/presence/<machine>` on the host repo's own
@@ -15,9 +16,12 @@
 
 import { spawn, spawnSync } from "node:child_process";
 
-/** The ref namespace. Hardcoded — never interpolated from config — so the
- * publisher is structurally unable to touch refs/heads/* (ADR 0016). */
+/** The ref namespaces. Hardcoded — never interpolated from config — so the
+ * publisher is structurally unable to touch refs/heads/* (ADR 0016). Mail
+ * refs carry cross-machine peer messages on the same transport (ADR 0222). */
 export const PRESENCE_REF_PREFIX = "refs/harnery/presence/";
+export const MAIL_REF_PREFIX = "refs/harnery/mail/";
+type HarneryRefPrefix = typeof PRESENCE_REF_PREFIX | typeof MAIL_REF_PREFIX;
 
 /** Well-known SHA of git's empty tree; `git mktree` below guarantees the
  * object exists in the local odb before we build a commit on it. */
@@ -112,44 +116,46 @@ export function writePresenceCommit(root: string, message: string): string | nul
 }
 
 /**
- * Force-push a presence commit to `refs/harnery/presence/<machine>`.
- * `sync: true` (CLI/tests) waits and reports; default is detached fire-and-
- * forget (hook path — a slow or credential-less push must not block a turn).
+ * Force-push a commit to `<prefix><machine>` (presence or mail). `sync: true`
+ * (CLI/tests) waits and reports; default is detached fire-and-forget (hook
+ * path — a slow or credential-less push must not block a turn).
  */
-export function pushPresenceRef(
+export function pushMachineRef(
   root: string,
+  prefix: HarneryRefPrefix,
   machine: string,
   sha: string,
   opts: { sync?: boolean } = {},
 ): { ok: boolean; error?: string } {
-  const refspec = `+${sha}:${PRESENCE_REF_PREFIX}${sanitizeRefComponent(machine)}`;
-  const args = ["-C", root, "push", "--quiet", "--no-verify", "origin", refspec];
-  if (opts.sync) {
-    const r = runGit(root, args.slice(2));
-    return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
-  }
-  try {
-    const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
-    child.unref();
-    return { ok: true };
-  } catch {
-    return { ok: false, error: "spawn failed" };
-  }
+  const refspec = `+${sha}:${prefix}${sanitizeRefComponent(machine)}`;
+  return runNetworkGit(root, ["push", "--quiet", "--no-verify", "origin", refspec], opts);
 }
 
-/** Fetch every peer presence ref from origin into the local ref namespace. */
-export function fetchPresenceRefs(
+/** Fetch every peer presence and mail ref from origin into the local ref
+ * namespace, in one round trip. A namespace with no refs is not an error. */
+export function fetchMachineRefs(
   root: string,
   opts: { sync?: boolean } = {},
 ): { ok: boolean; error?: string } {
-  const refspec = `+${PRESENCE_REF_PREFIX}*:${PRESENCE_REF_PREFIX}*`;
-  const args = ["-C", root, "fetch", "--quiet", "--no-tags", "origin", refspec];
+  const refspecs = [PRESENCE_REF_PREFIX, MAIL_REF_PREFIX].map((p) => `+${p}*:${p}*`);
+  return runNetworkGit(root, ["fetch", "--quiet", "--no-tags", "origin", ...refspecs], opts);
+}
+
+function runNetworkGit(
+  root: string,
+  args: string[],
+  opts: { sync?: boolean },
+): { ok: boolean; error?: string } {
   if (opts.sync) {
-    const r = runGit(root, args.slice(2));
+    const r = runGit(root, args);
     return r.ok ? { ok: true } : { ok: false, error: r.stderr.trim().slice(0, 300) };
   }
   try {
-    const child = spawn("git", args, { detached: true, stdio: "ignore", env: gitEnv() });
+    const child = spawn("git", ["-C", root, ...args], {
+      detached: true,
+      stdio: "ignore",
+      env: gitEnv(),
+    });
     child.unref();
     return { ok: true };
   } catch {
@@ -157,15 +163,14 @@ export function fetchPresenceRefs(
   }
 }
 
-/** Read every locally-known presence ref → [{ref, machine, message}]. */
-export function readPresenceRefs(root: string): Array<{ machine: string; message: string }> {
-  const r = runGit(root, [
-    "for-each-ref",
-    "--format=%(refname)%00%(contents)%01",
-    `${PRESENCE_REF_PREFIX}*`,
-  ]);
+/** Read every locally-known ref under `prefix` → [{machine, message}]. */
+export function readMachineRefs(
+  root: string,
+  prefix: HarneryRefPrefix = PRESENCE_REF_PREFIX,
+): Array<{ machine: string; message: string }> {
+  const r = runGit(root, ["for-each-ref", "--format=%(refname)%00%(contents)%01", `${prefix}*`]);
   if (!r.ok) return [];
-  return parseForEachRefOutput(r.stdout);
+  return parseForEachRefOutput(r.stdout, prefix);
 }
 
 /**
@@ -173,7 +178,10 @@ export function readPresenceRefs(root: string): Array<{ machine: string; message
  * Records are %01-terminated (contents may contain newlines); refname and
  * contents are %00-separated. Exported for unit tests.
  */
-export function parseForEachRefOutput(out: string): Array<{ machine: string; message: string }> {
+export function parseForEachRefOutput(
+  out: string,
+  prefix: HarneryRefPrefix = PRESENCE_REF_PREFIX,
+): Array<{ machine: string; message: string }> {
   const rows: Array<{ machine: string; message: string }> = [];
   for (const rec of out.split("\u0001")) {
     const trimmed = rec.replace(/^\n+/, "");
@@ -181,9 +189,9 @@ export function parseForEachRefOutput(out: string): Array<{ machine: string; mes
     const sep = trimmed.indexOf("\u0000");
     if (sep === -1) continue;
     const refname = trimmed.slice(0, sep).trim();
-    if (!refname.startsWith(PRESENCE_REF_PREFIX)) continue;
+    if (!refname.startsWith(prefix)) continue;
     rows.push({
-      machine: refname.slice(PRESENCE_REF_PREFIX.length),
+      machine: refname.slice(prefix.length),
       message: trimmed.slice(sep + 1).trim(),
     });
   }

package/src/core/presence/index.ts

@@ -31,17 +31,23 @@ import { resolveMachineLabel } from "../../lib/machine.ts";
 import { presenceEnabled } from "../config.ts";
 import { buildPresenceBlob, type PresenceAgent, type PresenceBlob } from "./blob.ts";
 import {
-  fetchPresenceRefs,
+  fetchMachineRefs,
   hasOrigin,
-  pushPresenceRef,
-  readPresenceRefs,
+  PRESENCE_REF_PREFIX,
+  pushMachineRef,
+  readMachineRefs,
   sanitizeRefComponent,
   writePresenceCommit,
 } from "./git.ts";
 
 export type { PresenceAgent, PresenceBlob } from "./blob.ts";
 export { buildPresenceBlob } from "./blob.ts";
-export { PRESENCE_REF_PREFIX, parseForEachRefOutput, sanitizeRefComponent } from "./git.ts";
+export {
+  MAIL_REF_PREFIX,
+  PRESENCE_REF_PREFIX,
+  parseForEachRefOutput,
+  sanitizeRefComponent,
+} from "./git.ts";
 export { ensureRelayDaemon, relayDaemonStatus, runRelayDaemon } from "./relay-client.ts";
 
 /** Re-push at least this often while sessions are live, so peers can treat a
@@ -139,7 +145,9 @@ export function publishPresence(
     const sha = writePresenceCommit(coordRoot, json);
     if (!sha) return { status: "error", error: "commit-tree failed" };
 
-    const push = pushPresenceRef(coordRoot, blob.machine, sha, { sync: opts.sync });
+    const push = pushMachineRef(coordRoot, PRESENCE_REF_PREFIX, blob.machine, sha, {
+      sync: opts.sync,
+    });
     if (!push.ok) return { status: "error", error: push.error ?? "push failed" };
 
     // Optimistic on the detached path: a failed background push self-heals at
@@ -155,7 +163,7 @@ export function publishPresence(
   }
 }
 
-/** Throttled fetch of peer presence refs from origin. */
+/** Throttled fetch of peer presence and mail refs from origin. */
 export function fetchPresence(
   coordRoot: string,
   opts: { force?: boolean; sync?: boolean } = {},
@@ -191,7 +199,7 @@ export function fetchPresence(
       /* best-effort */
     }
 
-    const r = fetchPresenceRefs(coordRoot, { sync: opts.sync });
+    const r = fetchMachineRefs(coordRoot, { sync: opts.sync });
     if (!r.ok) return { status: "error", error: r.error ?? "fetch failed" };
     return { status: "fetched" };
   } catch (e) {
@@ -231,7 +239,7 @@ export function readRemoteMachines(
       if (prev && Date.parse(prev.published_at) >= publishedMs) return;
       byMachine.set(machine, blob);
     };
-    for (const { machine, message } of readPresenceRefs(coordRoot)) {
+    for (const { machine, message } of readMachineRefs(coordRoot, PRESENCE_REF_PREFIX)) {
       try {
         consider(machine, JSON.parse(message) as PresenceBlob);
       } catch {