@modootoday/pmcp 0.9.1 → 0.10.0

package/dist/chunk-HNAVQG6R.js

@@ -0,0 +1,1198 @@
+import {
+  readConfig
+} from "./chunk-MSTKY33C.js";
+import {
+  actorIdSchema,
+  bindingSchema,
+  credentialSchema,
+  cursorSchema,
+  inboxSchema,
+  messageSchema,
+  openSqlite,
+  operationSchema,
+  runtimeSchema,
+  sendSchema,
+  sessionsSchema
+} from "./chunk-XOH2CW6P.js";
+
+// src/mailbox/types.ts
+var MailboxError = class extends Error {
+  constructor(code, message, retryable = false) {
+    super(message);
+    this.code = code;
+    this.retryable = retryable;
+    this.name = "MailboxError";
+  }
+  code;
+  retryable;
+};
+function failure(error) {
+  if (error instanceof MailboxError) {
+    return {
+      ok: false,
+      error: {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable
+      }
+    };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "internal_error",
+      message: "Mailbox operation failed",
+      retryable: false
+    }
+  };
+}
+
+// src/mailbox/config.ts
+import { randomUUID } from "crypto";
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { z } from "zod";
+var sectionSchema = z.object({
+  version: z.literal(1),
+  enabled: z.boolean(),
+  project_id: z.uuid(),
+  state_dir: z.string().min(1).optional()
+}).strict();
+function mailboxConfigFrom(project, env = process.env) {
+  if (project.raw.mailbox === void 0) return void 0;
+  const parsed = sectionSchema.safeParse(project.raw.mailbox);
+  if (!parsed.success)
+    throw new MailboxError("invalid_config", "Invalid [mailbox] configuration");
+  const section = parsed.data;
+  const stateRoot = env.XDG_STATE_HOME ?? join(homedir(), ".local/state");
+  const stateDir = section.state_dir ? resolve(project.dir, section.state_dir) : join(stateRoot, "pmcp/projects", section.project_id);
+  return {
+    projectId: section.project_id,
+    enabled: section.enabled,
+    databasePath: join(stateDir, "mailbox.sqlite")
+  };
+}
+function initializeMailboxConfig(file, stateDirectory) {
+  const path = resolve(file);
+  const original = existsSync(path) ? readFileSync(path, "utf8") : void 0;
+  if (original !== void 0 && readConfig(path).raw.mailbox !== void 0) {
+    throw new MailboxError("mailbox_exists", "Mailbox is already configured");
+  }
+  const lines = [
+    "[mailbox]",
+    "version = 1",
+    "enabled = true",
+    `project_id = ${JSON.stringify(randomUUID())}`
+  ];
+  if (stateDirectory)
+    lines.push(`state_dir = ${JSON.stringify(stateDirectory)}`);
+  const text = `${original ?? ""}
+${lines.join("\n")}
+`;
+  mkdirSync(dirname(path), { recursive: true });
+  if (original === void 0) {
+    writeFileSync(path, text, { flag: "wx", mode: 384 });
+  } else {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporary, text, { flag: "wx", mode: 384 });
+      if (readFileSync(path, "utf8") !== original) {
+        throw new MailboxError(
+          "config_conflict",
+          "Configuration changed during initialization"
+        );
+      }
+      renameSync(temporary, path);
+    } finally {
+      rmSync(temporary, { force: true });
+    }
+  }
+  return mailboxConfigFrom(readConfig(path));
+}
+function readPrivateJson(file) {
+  const descriptor = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || (stat.mode & 63) !== 0 || stat.size > 4096) {
+      throw new MailboxError(
+        "unsafe_credential_file",
+        "Use a private regular credential file of at most 4096 bytes"
+      );
+    }
+    if (process.getuid && stat.uid !== process.getuid()) {
+      throw new MailboxError(
+        "unsafe_credential_file",
+        "Credential file must belong to the current user"
+      );
+    }
+    return JSON.parse(readFileSync(descriptor, "utf8"));
+  } finally {
+    closeSync(descriptor);
+  }
+}
+function readCredential(file) {
+  return credentialSchema.parse(readPrivateJson(file));
+}
+function readBinding(file) {
+  return bindingSchema.parse(readPrivateJson(file));
+}
+function writePrivateJson(file, value) {
+  mkdirSync(dirname(resolve(file)), { recursive: true, mode: 448 });
+  writeFileSync(file, `${JSON.stringify(value, null, 2)}
+`, {
+    flag: "wx",
+    mode: 384
+  });
+}
+function writeBindingFile(file, binding) {
+  if (existsSync(file)) {
+    const previous = readBinding(file);
+    if (previous.projectId !== binding.projectId || previous.actorId !== binding.actorId) {
+      throw new MailboxError(
+        "binding_scope_conflict",
+        "Binding file belongs to another actor or project"
+      );
+    }
+  }
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    writePrivateJson(temporary, binding);
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+
+// src/mailbox/store.ts
+import { createHash as createHash2, randomBytes, randomUUID as randomUUID2 } from "crypto";
+import {
+  chmodSync as chmodSync2,
+  copyFileSync,
+  constants as constants2,
+  existsSync as existsSync2,
+  unlinkSync
+} from "fs";
+
+// src/storage/schema.ts
+var SCHEMA_VERSION = 3;
+var SCHEMA_SQL = `
+CREATE TABLE mailbox_project (
+  id TEXT PRIMARY KEY,
+  created_at_ms INTEGER NOT NULL
+);
+CREATE TABLE mailbox_actors (
+  id TEXT PRIMARY KEY,
+  credential_hash TEXT NOT NULL,
+  parent_actor_id TEXT REFERENCES mailbox_actors(id),
+  generation INTEGER NOT NULL DEFAULT 0,
+  active_session_id TEXT REFERENCES mailbox_sessions(id) DEFERRABLE INITIALLY DEFERRED,
+  created_at_ms INTEGER NOT NULL
+);
+CREATE TABLE mailbox_sessions (
+  id TEXT PRIMARY KEY,
+  actor_id TEXT NOT NULL REFERENCES mailbox_actors(id),
+  generation INTEGER NOT NULL,
+  secret_hash TEXT NOT NULL,
+  runtime TEXT NOT NULL,
+  native_session_id TEXT,
+  created_at_ms INTEGER NOT NULL,
+  heartbeat_at_ms INTEGER NOT NULL,
+  expires_at_ms INTEGER NOT NULL,
+  closed_at_ms INTEGER,
+  UNIQUE(actor_id, generation)
+);
+CREATE TABLE mailbox_messages (
+  seq INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  sender_actor_id TEXT NOT NULL REFERENCES mailbox_actors(id),
+  sender_session_id TEXT NOT NULL REFERENCES mailbox_sessions(id),
+  idempotency_key TEXT NOT NULL,
+  payload_json TEXT NOT NULL,
+  body TEXT NOT NULL,
+  thread_id TEXT NOT NULL REFERENCES mailbox_messages(id) DEFERRABLE INITIALLY DEFERRED,
+  reply_to_id TEXT REFERENCES mailbox_messages(id),
+  created_at_ms INTEGER NOT NULL,
+  UNIQUE(sender_actor_id, idempotency_key)
+);
+CREATE TABLE mailbox_receipts (
+  message_id TEXT NOT NULL REFERENCES mailbox_messages(id),
+  target_key TEXT NOT NULL,
+  actor_id TEXT NOT NULL REFERENCES mailbox_actors(id),
+  session_id TEXT REFERENCES mailbox_sessions(id),
+  read_at_ms INTEGER,
+  ack_at_ms INTEGER,
+  PRIMARY KEY(message_id, target_key),
+  CHECK(ack_at_ms IS NULL OR read_at_ms IS NOT NULL)
+);
+CREATE INDEX receipts_actor_session ON mailbox_receipts(actor_id, session_id, message_id);
+CREATE INDEX messages_thread_seq ON mailbox_messages(thread_id, seq);
+CREATE INDEX sessions_actor_presence ON mailbox_sessions(actor_id, closed_at_ms, expires_at_ms);
+PRAGMA user_version = 1;
+`;
+
+// src/storage/migrations.ts
+import { createHash } from "crypto";
+var MIGRATION_2 = `
+ALTER TABLE mailbox_actors ADD COLUMN credential_revision INTEGER NOT NULL DEFAULT 1;
+ALTER TABLE mailbox_actors ADD COLUMN parent_generation INTEGER;
+UPDATE mailbox_actors SET parent_generation = (SELECT generation FROM mailbox_actors p WHERE p.id = mailbox_actors.parent_actor_id) WHERE parent_actor_id IS NOT NULL;
+CREATE TABLE mailbox_migrations (version INTEGER PRIMARY KEY, checksum TEXT NOT NULL);
+CREATE TABLE mailbox_notifications (
+  message_id TEXT NOT NULL REFERENCES mailbox_messages(id),
+  actor_id TEXT NOT NULL REFERENCES mailbox_actors(id),
+  session_id TEXT NOT NULL REFERENCES mailbox_sessions(id),
+  generation INTEGER NOT NULL,
+  native_target TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('pending', 'leased', 'accepted', 'uncertain', 'failed', 'stale')),
+  attempts INTEGER NOT NULL DEFAULT 0,
+  lease_token TEXT,
+  lease_until_ms INTEGER,
+  next_attempt_ms INTEGER NOT NULL,
+  outcome_code TEXT,
+  PRIMARY KEY(message_id, actor_id, session_id)
+);
+CREATE INDEX notifications_pending ON mailbox_notifications(state, next_attempt_ms);
+`;
+function migrateDatabase(database) {
+  let version = database.get("PRAGMA user_version")?.user_version;
+  if (version === 1) {
+    database.exec(MIGRATION_2);
+    database.run(
+      "INSERT INTO mailbox_migrations(version, checksum) VALUES (?, ?)",
+      2,
+      createHash("sha256").update(MIGRATION_2).digest("hex")
+    );
+    database.exec("PRAGMA user_version = 2");
+    version = 2;
+  }
+  if (version === 2) {
+    database.exec(MIGRATION_3);
+    database.run(
+      "INSERT INTO mailbox_migrations(version, checksum) VALUES (?, ?)",
+      3,
+      createHash("sha256").update(MIGRATION_3).digest("hex")
+    );
+    database.exec("PRAGMA user_version = 3");
+  }
+  if (database.all("PRAGMA foreign_key_check").length > 0) {
+    throw new MailboxError(
+      "storage_corrupt",
+      "Migration failed foreign key validation"
+    );
+  }
+}
+var MIGRATION_3 = `
+ALTER TABLE mailbox_actors ADD COLUMN authority_expires_at_ms INTEGER;
+UPDATE mailbox_actors SET authority_expires_at_ms = created_at_ms + 60000 WHERE parent_actor_id IS NOT NULL;
+`;
+function validateMigrations(database) {
+  for (const [version, sql] of [
+    [2, MIGRATION_2],
+    [3, MIGRATION_3]
+  ]) {
+    const expected = createHash("sha256").update(sql).digest("hex");
+    if (database.get(
+      "SELECT checksum FROM mailbox_migrations WHERE version = ?",
+      version
+    )?.checksum !== expected) {
+      throw new MailboxError(
+        "schema_incompatible",
+        "Migration checksum does not match the supported schema"
+      );
+    }
+  }
+}
+
+// src/mailbox/sqlite.ts
+import { chmodSync, mkdirSync as mkdirSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+import { setTimeout as delay } from "timers/promises";
+function storageError(error) {
+  const detail = error instanceof Error ? error.message : "";
+  if (/busy|locked/i.test(detail)) {
+    return new MailboxError("storage_locked", "Mailbox storage is busy", true);
+  }
+  if (/corrupt|malformed|not a database/i.test(detail)) {
+    return new MailboxError("storage_corrupt", "Mailbox storage is corrupt");
+  }
+  return new MailboxError(
+    "storage_unavailable",
+    "Mailbox storage cannot be accessed"
+  );
+}
+async function openDatabase(file) {
+  let native;
+  try {
+    if (file !== ":memory:")
+      mkdirSync2(dirname2(file), { recursive: true, mode: 448 });
+    native = (await openSqlite(file)).db;
+    if (file !== ":memory:") chmodSync(file, 384);
+  } catch (error) {
+    throw storageError(error);
+  }
+  const invoke = (operation) => {
+    try {
+      return operation();
+    } catch (error) {
+      throw storageError(error);
+    }
+  };
+  return {
+    exec: (sql) => invoke(() => native.exec(sql)),
+    get: (sql, ...values) => invoke(() => native.prepare(sql).get(...values)),
+    all: (sql, ...values) => invoke(() => native.prepare(sql).all(...values)),
+    run: (sql, ...values) => {
+      invoke(() => native.prepare(sql).run(...values));
+    },
+    close: () => native.close()
+  };
+}
+async function retryLocked(database, operation) {
+  const deadline = performance.now() + 5e3;
+  while (true) {
+    const remaining = Math.max(1, Math.floor(deadline - performance.now()));
+    database.exec(`PRAGMA busy_timeout = ${Math.min(1e3, remaining)}`);
+    try {
+      return operation();
+    } catch (error) {
+      if (!(error instanceof MailboxError) || error.code !== "storage_locked") {
+        throw error;
+      }
+      if (performance.now() >= deadline) {
+        throw error;
+      }
+      await delay(Math.min(25, Math.max(1, deadline - performance.now())));
+    }
+  }
+}
+function transaction(database, operation, write = true) {
+  return retryLocked(database, () => {
+    database.exec(write ? "BEGIN IMMEDIATE" : "BEGIN");
+    try {
+      const result = operation();
+      database.exec("COMMIT");
+      return result;
+    } catch (error) {
+      database.exec("ROLLBACK");
+      throw error;
+    }
+  });
+}
+
+// src/mailbox/store.ts
+var PRESENCE_TTL_MS = 12e4;
+var HEARTBEAT_INTERVAL_MS = 3e4;
+function hash(secret2) {
+  return createHash2("sha256").update(secret2).digest("hex");
+}
+function secret() {
+  return randomBytes(32).toString("hex");
+}
+var MailboxStore = class _MailboxStore {
+  pending = Promise.resolve();
+  closed = false;
+  config;
+  database;
+  now;
+  constructor(config, database, now) {
+    this.config = config;
+    this.database = database;
+    this.now = now;
+  }
+  static async open(config, now = Date.now) {
+    if (!config.databasePath || !credentialSchema.shape.projectId.safeParse(config.projectId).success) {
+      throw new MailboxError(
+        "invalid_config",
+        "Provide a project UUID and database path"
+      );
+    }
+    if (!config.enabled) {
+      throw new MailboxError("mailbox_disabled", "Mailbox is disabled");
+    }
+    const database = await openDatabase(config.databasePath);
+    const store = new _MailboxStore(config, database, now);
+    try {
+      database.exec("PRAGMA busy_timeout = 1000");
+      database.exec("PRAGMA foreign_keys = ON");
+      await retryLocked(
+        database,
+        () => database.exec("PRAGMA journal_mode = WAL")
+      );
+      await transaction(database, () => {
+        const version = database.get("PRAGMA user_version")?.user_version;
+        if (version === 0) {
+          database.exec(SCHEMA_SQL);
+          database.run(
+            "INSERT INTO mailbox_project(id, created_at_ms) VALUES (?, ?)",
+            config.projectId,
+            now()
+          );
+        }
+        migrateDatabase(database);
+        store.checkSchema();
+        validateMigrations(database);
+      });
+      return store;
+    } catch (error) {
+      database.close();
+      throw error;
+    }
+  }
+  checkSchema() {
+    if (this.database.get("PRAGMA user_version")?.user_version !== SCHEMA_VERSION) {
+      throw new MailboxError(
+        "schema_incompatible",
+        "Mailbox schema version is not supported"
+      );
+    }
+    if (this.database.get("SELECT id FROM mailbox_project")?.id !== this.config.projectId) {
+      throw new MailboxError(
+        "project_mismatch",
+        "Mailbox database belongs to another project"
+      );
+    }
+  }
+  run(operation, write = true) {
+    if (this.closed) {
+      return Promise.reject(
+        new MailboxError("storage_unavailable", "Mailbox storage is closed")
+      );
+    }
+    const next = this.pending.then(
+      () => transaction(
+        this.database,
+        () => {
+          this.checkSchema();
+          return operation();
+        },
+        write
+      )
+    );
+    this.pending = next.catch(() => void 0);
+    return next;
+  }
+  registerActor(actorId, parentActorId, persist, authorityTtlMs = 6e4, parentBinding) {
+    actorIdSchema.parse(actorId);
+    if (parentActorId) {
+      actorIdSchema.parse(parentActorId);
+    }
+    return this.run(() => {
+      if (parentBinding) {
+        this.assertBinding(parentBinding);
+        if (parentActorId !== parentBinding.actorId) {
+          throw new MailboxError(
+            "unauthorized",
+            "Delegation parent does not match the issuer"
+          );
+        }
+      }
+      if (this.database.get("SELECT id FROM mailbox_actors WHERE id = ?", actorId)) {
+        throw new MailboxError("actor_exists", "Actor is already registered");
+      }
+      if (parentActorId && !this.database.get(
+        "SELECT id FROM mailbox_actors WHERE id = ?",
+        parentActorId
+      )) {
+        throw new MailboxError(
+          "unknown_actor",
+          "Parent actor is not registered"
+        );
+      }
+      if (parentActorId) {
+        const parent = this.database.get(
+          "SELECT a.parent_actor_id, s.closed_at_ms, s.expires_at_ms FROM mailbox_actors a LEFT JOIN mailbox_sessions s ON s.id = a.active_session_id WHERE a.id = ?",
+          parentActorId
+        );
+        if (parent?.parent_actor_id || parent?.closed_at_ms !== null || Number(parent?.expires_at_ms ?? 0) <= this.now()) {
+          throw new MailboxError(
+            "stale_parent",
+            "Delegation requires a live root parent attachment"
+          );
+        }
+        if (!Number.isSafeInteger(authorityTtlMs) || authorityTtlMs < 1 || authorityTtlMs > 3e5) {
+          throw new MailboxError(
+            "invalid_ttl",
+            "Child authority TTL must be between 1 and 300000 milliseconds"
+          );
+        }
+      }
+      const credential = {
+        projectId: this.config.projectId,
+        actorId,
+        secret: secret()
+      };
+      this.database.run(
+        "INSERT INTO mailbox_actors(id, credential_hash, parent_actor_id, parent_generation, created_at_ms, authority_expires_at_ms) VALUES (?, ?, ?, ?, ?, ?)",
+        actorId,
+        hash(credential.secret),
+        parentActorId ?? null,
+        parentActorId ? Number(
+          this.database.get(
+            "SELECT generation FROM mailbox_actors WHERE id = ?",
+            parentActorId
+          )?.generation
+        ) : null,
+        this.now(),
+        parentActorId ? this.now() + authorityTtlMs : null
+      );
+      persist?.(credential);
+      return credential;
+    });
+  }
+  registerChild(parent, actorId, ttlMs = 6e4) {
+    return this.registerActor(
+      actorId,
+      parent.actorId,
+      void 0,
+      ttlMs,
+      parent
+    );
+  }
+  attach(credential, runtime, replaceSessionId, nativeSessionId) {
+    credentialSchema.parse(credential);
+    runtimeSchema.parse(runtime);
+    if (nativeSessionId !== void 0 && (nativeSessionId.length < 1 || nativeSessionId.length > 256 || /[\x00-\x1f]/u.test(nativeSessionId))) {
+      throw new MailboxError(
+        "invalid_target",
+        "Native session ID must be a bounded nonempty identifier"
+      );
+    }
+    return this.run(() => {
+      const actor = this.database.get(
+        "SELECT * FROM mailbox_actors WHERE id = ?",
+        credential.actorId
+      );
+      if (credential.projectId !== this.config.projectId || actor?.credential_hash !== hash(credential.secret)) {
+        throw new MailboxError("unauthorized", "Actor credential is invalid");
+      }
+      if (actor.authority_expires_at_ms !== null && Number(actor.authority_expires_at_ms) <= this.now()) {
+        throw new MailboxError(
+          "authority_expired",
+          "Child authority has expired"
+        );
+      }
+      if (actor.parent_actor_id) {
+        const parent = this.database.get(
+          "SELECT a.generation, s.expires_at_ms, s.closed_at_ms FROM mailbox_actors a LEFT JOIN mailbox_sessions s ON s.id = a.active_session_id WHERE a.id = ?",
+          actor.parent_actor_id
+        );
+        if (!parent || parent.generation !== actor.parent_generation || parent.closed_at_ms !== null || Number(parent.expires_at_ms ?? 0) <= this.now()) {
+          throw new MailboxError(
+            "stale_parent",
+            "Parent attachment is no longer current"
+          );
+        }
+      }
+      const activeId = actor.active_session_id;
+      const active = activeId ? this.database.get(
+        "SELECT * FROM mailbox_sessions WHERE id = ?",
+        activeId
+      ) : void 0;
+      if (replaceSessionId && replaceSessionId !== activeId) {
+        throw new MailboxError(
+          "session_conflict",
+          "Expected attachment is no longer current"
+        );
+      }
+      if (active && Number(active.expires_at_ms) > this.now() && !replaceSessionId) {
+        throw new MailboxError(
+          "session_conflict",
+          "Actor already has a live attachment"
+        );
+      }
+      const generation = Number(actor.generation) + 1;
+      if (!Number.isSafeInteger(generation)) {
+        throw new MailboxError(
+          "sequence_overflow",
+          "Attachment generation exceeds safe integer range"
+        );
+      }
+      if (activeId) {
+        this.database.run(
+          "UPDATE mailbox_sessions SET closed_at_ms = ? WHERE id = ?",
+          this.now(),
+          activeId
+        );
+      }
+      const binding = {
+        projectId: this.config.projectId,
+        actorId: credential.actorId,
+        sessionId: randomUUID2(),
+        generation,
+        secret: secret()
+      };
+      this.database.run(
+        "INSERT INTO mailbox_sessions(id, actor_id, generation, secret_hash, runtime, native_session_id, created_at_ms, heartbeat_at_ms, expires_at_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        binding.sessionId,
+        binding.actorId,
+        generation,
+        hash(binding.secret),
+        runtime,
+        nativeSessionId ?? null,
+        this.now(),
+        this.now(),
+        this.now() + PRESENCE_TTL_MS
+      );
+      this.database.run(
+        "UPDATE mailbox_actors SET generation = ?, active_session_id = ? WHERE id = ?",
+        generation,
+        binding.sessionId,
+        binding.actorId
+      );
+      return binding;
+    });
+  }
+  assertBinding(binding) {
+    bindingSchema.parse(binding);
+    const session = this.database.get(
+      "SELECT s.*, a.active_session_id, a.parent_actor_id, a.parent_generation, a.authority_expires_at_ms FROM mailbox_sessions s JOIN mailbox_actors a ON a.id = s.actor_id WHERE s.id = ?",
+      binding.sessionId
+    );
+    if (binding.projectId !== this.config.projectId || !session || session.actor_id !== binding.actorId || session.secret_hash !== hash(binding.secret) || session.generation !== binding.generation || session.active_session_id !== binding.sessionId || session.closed_at_ms !== null || Number(session.expires_at_ms) <= this.now()) {
+      throw new MailboxError(
+        "stale_session",
+        "Attachment is invalid, expired or superseded"
+      );
+    }
+    if (session.parent_actor_id) {
+      if (Number(session.authority_expires_at_ms ?? 0) <= this.now()) {
+        throw new MailboxError(
+          "authority_expired",
+          "Child authority has expired"
+        );
+      }
+      const parent = this.database.get(
+        "SELECT a.generation, s.closed_at_ms, s.expires_at_ms FROM mailbox_actors a LEFT JOIN mailbox_sessions s ON s.id = a.active_session_id WHERE a.id = ?",
+        session.parent_actor_id
+      );
+      if (parent?.generation !== session.parent_generation || parent?.closed_at_ms !== null || Number(parent?.expires_at_ms ?? 0) <= this.now()) {
+        throw new MailboxError(
+          "stale_parent",
+          "Parent attachment is no longer current"
+        );
+      }
+    }
+    return session;
+  }
+  rotateActor(actorId, persist) {
+    actorIdSchema.parse(actorId);
+    return this.run(() => {
+      if (!this.database.get(
+        "SELECT id FROM mailbox_actors WHERE id = ?",
+        actorId
+      )) {
+        throw new MailboxError("unknown_actor", "Actor is not registered");
+      }
+      const credential = {
+        projectId: this.config.projectId,
+        actorId,
+        secret: secret()
+      };
+      this.database.run(
+        "UPDATE mailbox_sessions SET closed_at_ms = COALESCE(closed_at_ms, ?) WHERE actor_id = ?",
+        this.now(),
+        actorId
+      );
+      this.database.run(
+        "UPDATE mailbox_actors SET credential_hash = ?, credential_revision = credential_revision + 1, generation = generation + 1, active_session_id = NULL WHERE id = ?",
+        hash(credential.secret),
+        actorId
+      );
+      this.database.run(
+        "UPDATE mailbox_notifications SET state = 'stale', lease_token = NULL, lease_until_ms = NULL WHERE actor_id = ? AND state IN ('pending', 'leased')",
+        actorId
+      );
+      persist?.(credential);
+      return credential;
+    });
+  }
+  heartbeat(binding) {
+    return this.run(() => {
+      this.assertBinding(binding);
+      this.database.run(
+        "UPDATE mailbox_sessions SET heartbeat_at_ms = ?, expires_at_ms = ? WHERE id = ?",
+        this.now(),
+        this.now() + PRESENCE_TTL_MS,
+        binding.sessionId
+      );
+    });
+  }
+  detach(binding) {
+    return this.run(() => {
+      const session = this.database.get(
+        "SELECT secret_hash FROM mailbox_sessions WHERE id = ?",
+        binding.sessionId
+      );
+      if (binding.projectId !== this.config.projectId || session?.secret_hash !== hash(binding.secret)) {
+        throw new MailboxError(
+          "unauthorized",
+          "Attachment credential is invalid"
+        );
+      }
+      this.database.run(
+        "UPDATE mailbox_sessions SET closed_at_ms = COALESCE(closed_at_ms, ?) WHERE id = ?",
+        this.now(),
+        binding.sessionId
+      );
+      this.database.run(
+        "UPDATE mailbox_actors SET active_session_id = NULL WHERE id = ? AND active_session_id = ?",
+        binding.actorId,
+        binding.sessionId
+      );
+    });
+  }
+  exportRecords(actorId) {
+    if (actorId) {
+      actorIdSchema.parse(actorId);
+    }
+    return this.run(() => {
+      const where = actorId ? "WHERE m.sender_actor_id = ? OR EXISTS (SELECT 1 FROM mailbox_receipts r WHERE r.message_id = m.id AND r.actor_id = ?)" : "";
+      const values = actorId ? [actorId, actorId] : [];
+      const messages = this.database.all(
+        `SELECT m.* FROM mailbox_messages m ${where} ORDER BY m.seq`,
+        ...values
+      );
+      const records = [
+        {
+          type: "metadata",
+          version: 1,
+          projectId: this.config.projectId,
+          exportedAtMs: this.now(),
+          actorId: actorId ?? null
+        }
+      ];
+      for (const message of messages) {
+        const { payload_json: _payload, ...data } = message;
+        records.push({ type: "message", ...data });
+        for (const receipt of this.database.all(
+          "SELECT * FROM mailbox_receipts WHERE message_id = ? ORDER BY target_key",
+          message.id
+        )) {
+          records.push({ type: "receipt", ...receipt });
+        }
+      }
+      return records;
+    }, false);
+  }
+  async backup(destination) {
+    if (this.closed) {
+      throw new MailboxError(
+        "storage_unavailable",
+        "Mailbox storage is closed"
+      );
+    }
+    if (existsSync2(destination)) {
+      throw new MailboxError(
+        "destination_exists",
+        "Backup destination already exists"
+      );
+    }
+    const next = this.pending.then(() => {
+      this.checkSchema();
+      this.database.run("VACUUM INTO ?", destination);
+      chmodSync2(destination, 384);
+    });
+    this.pending = next.catch(() => void 0);
+    await next;
+  }
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    await this.pending;
+    this.database.close();
+  }
+};
+async function restoreBackup(source, config) {
+  copyFileSync(source, config.databasePath, constants2.COPYFILE_EXCL);
+  let store;
+  try {
+    chmodSync2(config.databasePath, 384);
+    const probe = await openDatabase(config.databasePath);
+    try {
+      if (Number(probe.get("PRAGMA user_version")?.user_version) < 1 || Number(probe.get("PRAGMA user_version")?.user_version) > SCHEMA_VERSION || probe.get("SELECT id FROM mailbox_project")?.id !== config.projectId) {
+        throw new MailboxError(
+          "schema_incompatible",
+          "Backup schema or project is not compatible"
+        );
+      }
+    } finally {
+      probe.close();
+    }
+    store = await MailboxStore.open(config);
+    const integrity = store.database.get("PRAGMA integrity_check");
+    if (integrity?.integrity_check !== "ok" || store.database.all("PRAGMA foreign_key_check").length > 0) {
+      throw new MailboxError(
+        "storage_corrupt",
+        "Restored backup failed integrity checks"
+      );
+    }
+  } catch (error) {
+    await store?.close();
+    unlinkSync(config.databasePath);
+    throw error;
+  }
+  await store.close();
+}
+
+// src/mailbox/service.ts
+import { randomUUID as randomUUID3 } from "crypto";
+var MailboxService = class {
+  store;
+  binding;
+  constructor(store, binding) {
+    this.store = store;
+    this.binding = binding;
+  }
+  async call(operation, input) {
+    try {
+      operationSchema.parse(operation);
+      let data;
+      if (operation === "send") {
+        data = await this.send(sendSchema.parse(input));
+      } else if (operation === "inbox") {
+        data = await this.inbox(inboxSchema.parse(input));
+      } else if (operation === "read" || operation === "ack") {
+        data = await this.receipt(
+          messageSchema.parse(input).messageId,
+          operation
+        );
+      } else {
+        sessionsSchema.parse(input);
+        data = await this.sessions();
+      }
+      return { ok: true, data };
+    } catch (error) {
+      if (error instanceof Error && error.name === "ZodError") {
+        return failure(
+          new MailboxError(
+            "invalid_input",
+            "Mailbox input does not match the operation schema"
+          )
+        );
+      }
+      return failure(error);
+    }
+  }
+  send(input) {
+    return this.store.run(() => {
+      const session = this.store.assertBinding(this.binding);
+      const recipients = [
+        ...new Map(
+          input.recipients.map((recipient) => {
+            const sessionId = recipient.sessionId ?? null;
+            const key = `${recipient.actorId}/${sessionId ?? ""}`;
+            return [
+              key,
+              { actorId: recipient.actorId, sessionId, key }
+            ];
+          })
+        ).values()
+      ].sort((a, b) => a.key.localeCompare(b.key, "en"));
+      const payload = JSON.stringify({
+        body: input.body,
+        replyToId: input.replyToId ?? null,
+        recipients: recipients.map(({ key: _key, ...recipient }) => recipient)
+      });
+      const previous = this.store.database.get(
+        "SELECT id, seq, thread_id, payload_json FROM mailbox_messages WHERE sender_actor_id = ? AND idempotency_key = ?",
+        this.binding.actorId,
+        input.idempotencyKey
+      );
+      if (previous) {
+        if (previous.payload_json !== payload) {
+          throw new MailboxError(
+            "idempotency_conflict",
+            "Idempotency key was used for a different payload"
+          );
+        }
+        return {
+          messageId: previous.id,
+          seq: previous.seq,
+          threadId: previous.thread_id,
+          duplicate: true
+        };
+      }
+      for (const recipient of recipients) {
+        if (session.parent_actor_id && recipient.actorId !== session.parent_actor_id) {
+          throw new MailboxError(
+            "recipient_forbidden",
+            "Child actor may send only to its parent"
+          );
+        }
+        if (!this.store.database.get(
+          "SELECT id FROM mailbox_actors WHERE id = ?",
+          recipient.actorId
+        )) {
+          throw new MailboxError(
+            "unknown_actor",
+            "Recipient actor is not registered"
+          );
+        }
+        if (recipient.sessionId && !this.store.database.get(
+          "SELECT id FROM mailbox_sessions WHERE id = ? AND actor_id = ?",
+          recipient.sessionId,
+          recipient.actorId
+        )) {
+          throw new MailboxError(
+            "unknown_session",
+            "Recipient session does not belong to the actor"
+          );
+        }
+      }
+      const id = randomUUID3();
+      let threadId = id;
+      if (input.replyToId) {
+        const original = this.visibleMessage(input.replyToId);
+        threadId = original.thread_id;
+        if (original.read_at_ms === null) {
+          throw new MailboxError(
+            "reply_requires_read",
+            "Read the original message before replying"
+          );
+        }
+      }
+      this.store.database.run(
+        "INSERT INTO mailbox_messages(id, sender_actor_id, sender_session_id, idempotency_key, payload_json, body, thread_id, reply_to_id, created_at_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        id,
+        this.binding.actorId,
+        this.binding.sessionId,
+        input.idempotencyKey,
+        payload,
+        input.body,
+        threadId,
+        input.replyToId ?? null,
+        this.store.now()
+      );
+      const seq = this.store.database.get(
+        "SELECT seq FROM mailbox_messages WHERE id = ?",
+        id
+      )?.seq;
+      if (!Number.isSafeInteger(seq)) {
+        throw new MailboxError(
+          "sequence_overflow",
+          "Message sequence exceeds safe integer range"
+        );
+      }
+      for (const recipient of recipients) {
+        this.store.database.run(
+          "INSERT INTO mailbox_receipts(message_id, target_key, actor_id, session_id) VALUES (?, ?, ?, ?)",
+          id,
+          recipient.key,
+          recipient.actorId,
+          recipient.sessionId
+        );
+      }
+      return { messageId: id, seq, threadId, duplicate: false };
+    });
+  }
+  visibleMessage(messageId) {
+    const message = this.store.database.get(
+      "SELECT m.*, r.target_key, r.read_at_ms, r.ack_at_ms FROM mailbox_messages m JOIN mailbox_receipts r ON r.message_id = m.id WHERE m.id = ? AND r.actor_id = ? AND (r.session_id IS NULL OR r.session_id = ?) ORDER BY r.target_key LIMIT 1",
+      messageId,
+      this.binding.actorId,
+      this.binding.sessionId
+    );
+    if (!message) {
+      throw new MailboxError(
+        "unknown_message",
+        "Message is not available to this attachment"
+      );
+    }
+    return message;
+  }
+  inbox(input) {
+    return this.store.run(() => {
+      this.store.assertBinding(this.binding);
+      let after = 0;
+      let upper = Number(
+        this.store.database.get(
+          "SELECT COALESCE(MAX(seq), 0) AS upper FROM mailbox_messages"
+        )?.upper
+      );
+      if (!Number.isSafeInteger(upper)) {
+        throw new MailboxError(
+          "sequence_overflow",
+          "Message sequence exceeds safe integer range"
+        );
+      }
+      if (input.cursor) {
+        let decoded;
+        try {
+          decoded = cursorSchema.parse(
+            JSON.parse(Buffer.from(input.cursor, "base64url").toString("utf8"))
+          );
+        } catch {
+          throw new MailboxError("invalid_cursor", "Cursor is malformed");
+        }
+        if (decoded.projectId !== this.binding.projectId || decoded.actorId !== this.binding.actorId || decoded.sessionId !== this.binding.sessionId || decoded.state !== input.state || decoded.threadId !== (input.threadId ?? null) || decoded.after > decoded.upper || decoded.upper > upper) {
+          throw new MailboxError(
+            "invalid_cursor",
+            "Cursor does not match the current inbox scope"
+          );
+        }
+        after = decoded.after;
+        upper = decoded.upper;
+      }
+      const stateSql = input.state === "unread" ? "AND r.read_at_ms IS NULL" : "";
+      const ackSql = input.state === "unacknowledged" ? "AND r.ack_at_ms IS NULL" : "";
+      const threadSql = input.threadId ? "AND m.thread_id = ?" : "";
+      const values = [
+        this.binding.actorId,
+        this.binding.sessionId,
+        after,
+        upper
+      ];
+      if (input.threadId) {
+        values.push(input.threadId);
+      }
+      values.push(input.limit + 1);
+      const rows = this.store.database.all(
+        `SELECT DISTINCT m.seq, m.id AS messageId, m.sender_actor_id AS senderActorId, m.thread_id AS threadId, m.reply_to_id AS replyToId, m.created_at_ms AS createdAtMs FROM mailbox_messages m JOIN mailbox_receipts r ON r.message_id = m.id WHERE r.actor_id = ? AND (r.session_id IS NULL OR r.session_id = ?) AND m.seq > ? AND m.seq <= ? ${stateSql} ${ackSql} ${threadSql} ORDER BY m.seq LIMIT ?`,
+        ...values
+      );
+      const items = rows.slice(0, input.limit);
+      let nextCursor = null;
+      if (rows.length > input.limit) {
+        const cursor = {
+          version: 1,
+          projectId: this.binding.projectId,
+          actorId: this.binding.actorId,
+          sessionId: this.binding.sessionId,
+          state: input.state,
+          threadId: input.threadId ?? null,
+          after: items.at(-1)?.seq,
+          upper
+        };
+        nextCursor = Buffer.from(JSON.stringify(cursor)).toString("base64url");
+      }
+      return { items, nextCursor };
+    }, false);
+  }
+  receipt(messageId, operation) {
+    return this.store.run(() => {
+      this.store.assertBinding(this.binding);
+      const message = this.visibleMessage(messageId);
+      if (operation === "ack" && message.read_at_ms === null) {
+        throw new MailboxError(
+          "ack_requires_read",
+          "Read the message before acknowledging it"
+        );
+      }
+      const column = operation === "read" ? "read_at_ms" : "ack_at_ms";
+      this.store.database.run(
+        `UPDATE mailbox_receipts SET ${column} = COALESCE(${column}, ?) WHERE message_id = ? AND actor_id = ? AND (session_id IS NULL OR session_id = ?)`,
+        this.store.now(),
+        messageId,
+        this.binding.actorId,
+        this.binding.sessionId
+      );
+      const current = this.visibleMessage(messageId);
+      const data = {
+        messageId,
+        readAtMs: current.read_at_ms,
+        ackAtMs: current.ack_at_ms
+      };
+      if (operation === "ack") {
+        return data;
+      }
+      return {
+        ...data,
+        body: current.body,
+        senderActorId: current.sender_actor_id,
+        threadId: current.thread_id,
+        replyToId: current.reply_to_id
+      };
+    });
+  }
+  sessions() {
+    return this.store.run(() => {
+      const session = this.store.assertBinding(this.binding);
+      const scope = session.parent_actor_id ? "AND (s.actor_id = ? OR s.actor_id = ?)" : "";
+      const values = session.parent_actor_id ? [
+        this.store.now(),
+        this.binding.actorId,
+        session.parent_actor_id
+      ] : [this.store.now()];
+      const items = this.store.database.all(
+        `SELECT s.id AS sessionId, s.actor_id AS actorId, s.runtime, s.native_session_id AS nativeSessionId, s.expires_at_ms AS expiresAtMs FROM mailbox_sessions s JOIN mailbox_actors a ON a.active_session_id = s.id WHERE s.closed_at_ms IS NULL AND s.expires_at_ms > ? ${scope} ORDER BY s.actor_id`,
+        ...values
+      );
+      return { items };
+    }, false);
+  }
+};
+
+// src/mailbox/attachment.ts
+async function attachMailbox(options) {
+  const store = await MailboxStore.open(options.config);
+  let binding;
+  try {
+    binding = await store.attach(
+      readCredential(options.actorFile),
+      options.runtime,
+      options.replaceSessionId,
+      options.nativeSessionId
+    );
+    if (options.bindingFile) writeBindingFile(options.bindingFile, binding);
+  } catch (error) {
+    if (binding) await store.detach(binding);
+    await store.close();
+    throw error;
+  }
+  const current = binding;
+  let shutdown;
+  const close = () => {
+    if (shutdown) return shutdown;
+    clearInterval(heartbeat);
+    shutdown = (async () => {
+      try {
+        await store.detach(current);
+      } finally {
+        await store.close();
+      }
+    })();
+    return shutdown;
+  };
+  const heartbeat = setInterval(() => {
+    void store.heartbeat(current).catch(() => {
+      options.onExpired?.();
+      void close().catch(() => void 0);
+    });
+  }, HEARTBEAT_INTERVAL_MS);
+  heartbeat.unref();
+  return { service: new MailboxService(store, current), close };
+}
+
+export {
+  MailboxError,
+  failure,
+  mailboxConfigFrom,
+  initializeMailboxConfig,
+  readCredential,
+  readBinding,
+  writePrivateJson,
+  writeBindingFile,
+  SCHEMA_VERSION,
+  openDatabase,
+  PRESENCE_TTL_MS,
+  HEARTBEAT_INTERVAL_MS,
+  MailboxStore,
+  restoreBackup,
+  MailboxService,
+  attachMailbox
+};
+//# sourceMappingURL=chunk-HNAVQG6R.js.map