@helipod/client 0.1.0

package/dist/outbox-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/outbox-fs.ts"],"sourcesContent":["/**\n * `fsOutbox()` — the filesystem OutboxStorage for Node/Bun/Electron/Tauri hosts (spec:\n * docs/superpowers/specs/2025-11-04-fs-outbox-adapter-design.md). One append-only JSONL journal\n * per queue dir; every seam mutation is one appended line through a serialized write-behind\n * appender (same-microtask ops batch into ONE write+fsync — the fs twin of outbox-idb's\n * pendingOps/queueMicrotask batcher); hydrate replays the journal. A torn TAIL line (the only\n * thing an interrupted append can produce) is physically truncated — that entry was never\n * park-eligible, so dropping it is correct. A corrupt MIDDLE line is quarantined and skipped.\n * Compaction (at open and past 4096 ops) rewrites live state tmp → fsync → rename → dir fsync.\n * `node:*` imports live ONLY in this file — it ships as the `./outbox-fs` subpath export so the\n * browser bundles never see them.\n */\nimport { appendFileSync, unlinkSync } from \"node:fs\";\nimport { mkdir, open, readFile, rename, rm, truncate, unlink, writeFile, type FileHandle } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport {\n  memoryOutbox,\n  type HydrateResult,\n  type OutboxEntry,\n  type OutboxEntryError,\n  type OutboxEntryStatus,\n  type OutboxMeta,\n  type OutboxStorage,\n} from \"./outbox-storage\";\nimport { dropStaleVersion } from \"./outbox-idb\";\n\nexport interface FsOutboxOptions {\n  /** Queue directory (created recursively). One durable queue per dir. */\n  dir: string;\n  /** fsync appends before resolving append()'s promise. Default true. */\n  fsync?: boolean;\n  /** Fired once if the adapter degrades to memoryOutbox() (lock held by another process, or an\n   *  open/hydrate failure). */\n  onFallback?: (reason: unknown) => void;\n}\n\n/** Thrown (rejecting the operation's promise) when a mutating call's flush runs — or would run —\n *  after `close()` has completed. Before this existed, a flush that observed `closed` mid-batch\n *  simply `return`ed, letting every op in that batch resolve normally despite never being written\n *  — a silent, undetectable data-loss window. Now the batch's shared promise rejects instead, so a\n *  caller racing `close()` learns its write was dropped rather than believing it durable. */\nexport class OutboxClosedError extends Error {\n  readonly code = \"OUTBOX_CLOSED\";\n  constructor(\n    message = \"fsOutbox is closed; this operation's outcome is UNKNOWN — it may or may not have \" +\n      \"been durably persisted (close()'s own final compaction can snapshot state an op mutated \" +\n      \"before its flush rejected). Treat like any in-flight-at-shutdown write: verify on next hydrate.\",\n  ) {\n    super(message);\n    this.name = \"OutboxClosedError\";\n  }\n}\n\nconst COMPACT_THRESHOLD = 4096;\n\ntype JournalOp =\n  | { op: \"append\"; entry: OutboxEntry }\n  | { op: \"status\"; clientId: string; seq: number; status: OutboxEntryStatus; error?: OutboxEntryError }\n  | { op: \"dequeue\"; clientId: string; seq: number }\n  | { op: \"meta\"; clientId: string; meta: OutboxMeta }\n  | { op: \"metaDelete\"; clientId: string };\n\nconst key = (clientId: string, seq: number) => `${clientId}\\0${seq}`;\n\ninterface State {\n  entries: Map<string, OutboxEntry>;\n  meta: Map<string, OutboxMeta>;\n}\n\nfunction applyOp(state: State, op: JournalOp): void {\n  switch (op.op) {\n    case \"append\":\n      state.entries.set(key(op.entry.clientId, op.entry.seq), op.entry);\n      break;\n    case \"status\": {\n      const existing = state.entries.get(key(op.clientId, op.seq));\n      if (existing)\n        state.entries.set(key(op.clientId, op.seq), {\n          ...existing,\n          status: op.status,\n          ...(op.error !== undefined ? { error: op.error } : {}),\n        });\n      break;\n    }\n    case \"dequeue\":\n      state.entries.delete(key(op.clientId, op.seq));\n      break;\n    case \"meta\":\n      state.meta.set(op.clientId, op.meta);\n      break;\n    case \"metaDelete\":\n      state.meta.delete(op.clientId);\n      break;\n  }\n}\n\n/** The direct (lock-free) open — `fsOutbox()` below wraps this with lock + probe-and-fallback. */\nexport class FsOutboxStorage implements OutboxStorage {\n  /** Accepts an injectable stats object (the `fsOutbox()` lock wrapper passes its own so the object\n   *  it returns from `fsOutbox()` stays live even across a probe-and-fallback swap) — defaults to a\n   *  fresh one for direct construction (tests, direct use of this class). */\n  readonly stats: { flushes: number; fsyncs: number };\n\n  private state: State = { entries: new Map(), meta: new Map() };\n  private opCount = 0;\n  private handle: FileHandle | undefined;\n  private pending: string[] = [];\n  private flushScheduled = false;\n  /** Serializes flushes, compactions, and close() — every disk mutation chains on this, INCLUDING\n   *  close() itself (see close() below), so nothing can run concurrently with or after a completed\n   *  close(). Fail-stop by construction: once any chained link throws (disk-full, a corrupt-open\n   *  failure, `OutboxClosedError`), `this.tail` becomes a permanently-rejected promise and every\n   *  later `.then(...)` chained onto it (the normal way every method here extends the chain) short-\n   *  circuits straight to that SAME rejection without ever running its own body — callers see the\n   *  original failure's error, not a fresh one. This is intentional, not a bug to route around: a\n   *  fsOutbox instance whose disk state may be compromised should not keep pretending to work.\n   *  Recovery (probe-and-fallback to memoryOutbox, lock steal) is `fsOutbox()`'s seam, not this class's. */\n  private tail: Promise<void> = Promise.resolve();\n  private opened = false;\n  private closed = false;\n\n  constructor(\n    private readonly dir: string,\n    private readonly fsync: boolean,\n    stats: { flushes: number; fsyncs: number } = { flushes: 0, fsyncs: 0 },\n  ) {\n    this.stats = stats;\n  }\n\n  private get journalPath() {\n    return join(this.dir, \"journal.jsonl\");\n  }\n\n  /** Replay the journal into memory; truncate a torn tail; quarantine corrupt middles; compact. */\n  private async openOnce(): Promise<void> {\n    if (this.opened) return;\n    this.opened = true;\n    await mkdir(this.dir, { recursive: true });\n    let raw = \"\";\n    try {\n      raw = await readFile(this.journalPath, \"utf8\");\n    } catch {\n      /* fresh dir — no journal yet */\n    }\n    let validBytes = 0;\n    // A flush always writes `line + \"\\n\"` as ONE buffer and fsyncs only after that write\n    // completes — so a journal missing its trailing newline PROVES the very last line was never\n    // acknowledged (append()'s promise for it never resolved), regardless of whether the bytes\n    // that did land happen to parse as valid JSON. Accepting a parseable-but-unterminated last\n    // line would glue whatever a LATER session appends onto its tail, corrupting an entry that\n    // WAS legitimately acknowledged (see the finding this fixes: torn-newline glue).\n    const hasTrailingNewline = raw.endsWith(\"\\n\");\n    const lines = raw.length === 0 ? [] : raw.split(\"\\n\");\n    for (let i = 0; i < lines.length; i++) {\n      const line = lines[i]!;\n      if (line === \"\") {\n        // the split artifact after a final newline, or a blank line mid-file (skip)\n        if (i < lines.length - 1) validBytes += 1;\n        continue;\n      }\n      const isLast = i === lines.length - 1;\n      if (isLast && !hasTrailingNewline) {\n        // Torn tail, unconditionally: never attempt to parse it — its missing newline alone\n        // proves it was never durably acknowledged. Truncate back to the last known-good byte.\n        await truncate(this.journalPath, validBytes);\n        continue;\n      }\n      try {\n        const op = JSON.parse(line) as JournalOp;\n        applyOp(this.state, op);\n        this.opCount++;\n        validBytes += Buffer.byteLength(line, \"utf8\") + 1;\n      } catch {\n        // A parse-failing line here always HAS its trailing newline (an unterminated final line is\n        // intercepted pre-parse above; a file ending \"\\n\" makes split's last element \"\"), so its\n        // write completed and the corruption is content-level: quarantine and continue.\n        appendFileSync(join(this.dir, \"journal.quarantine\"), line + \"\\n\");\n        validBytes += Buffer.byteLength(line, \"utf8\") + 1;\n      }\n    }\n    this.handle = await open(this.journalPath, \"a\");\n    // Open-time compaction bounds a journal that grew across prior sessions.\n    if (this.opCount > this.state.entries.size + this.state.meta.size) await this.compact();\n  }\n\n  private ready(): Promise<void> {\n    this.tail = this.tail.then(() => this.openOnce());\n    return this.tail;\n  }\n\n  /** Eagerly hydrate the journal. `fsOutbox()`'s probe awaits this BEFORE treating the\n   *  instance as live, so an open/hydrate failure (corrupt journal, failed truncate, disk error)\n   *  surfaces to the probe — which can then release the lock and degrade to `memoryOutbox()` — in\n   *  place of the old lazy-on-first-method-call shape, where the failure only surfaced after the\n   *  probe had already resolved to this fs store, fail-stopping the instance instead of falling\n   *  back per the spec's error-handling table. */\n  async open(): Promise<void> {\n    await this.ready();\n  }\n\n  private write(op: JournalOp): Promise<void> {\n    this.pending.push(JSON.stringify(op) + \"\\n\");\n    this.opCount++;\n    if (!this.flushScheduled) {\n      this.flushScheduled = true;\n      this.tail = this.tail.then(async () => {\n        await this.openOnce();\n        this.flushScheduled = false;\n        const batch = this.pending.splice(0);\n        if (batch.length === 0) return;\n        // close() chains its ENTIRE body (drain -> compact-if-excess -> closed=true ->\n        // handle.close) as a single link on `this.tail` too, so `this.closed` can only ever\n        // become true strictly BEFORE or AFTER this whole flush runs — never mid-flush. Seeing it\n        // true here means this batch lost the race entirely (queued after close() had already\n        // completed its own tail link): reject rather than silently `return`ing a \"success\" for\n        // ops that were never written — see OutboxClosedError's doc comment.\n        if (this.closed) throw new OutboxClosedError();\n        await this.handle!.write(batch.join(\"\"));\n        this.stats.flushes++;\n        if (this.fsync) {\n          await this.handle!.sync();\n          this.stats.fsyncs++;\n        }\n        if (this.opCount > COMPACT_THRESHOLD) await this.compact();\n      });\n    }\n    return this.tail;\n  }\n\n  /** Rewrite live state tmp → fsync → rename → dir fsync. Failure leaves the old journal intact. */\n  private async compact(): Promise<void> {\n    const tmpPath = join(this.dir, \"journal.tmp\");\n    try {\n      const lines: string[] = [];\n      for (const [clientId, meta] of this.state.meta) lines.push(JSON.stringify({ op: \"meta\", clientId, meta } satisfies JournalOp) + \"\\n\");\n      for (const entry of [...this.state.entries.values()].sort((a, b) => a.order - b.order))\n        lines.push(JSON.stringify({ op: \"append\", entry } satisfies JournalOp) + \"\\n\");\n      const tmp = await open(tmpPath, \"w\");\n      await tmp.write(lines.join(\"\"));\n      await tmp.sync();\n      await tmp.close();\n      await this.handle?.close();\n      await rename(tmpPath, this.journalPath);\n      const dirHandle = await open(this.dir, \"r\").catch(() => undefined);\n      if (dirHandle) {\n        await dirHandle.sync().catch(() => {});\n        await dirHandle.close();\n      }\n      this.handle = await open(this.journalPath, \"a\");\n      this.opCount = this.state.entries.size + this.state.meta.size;\n    } catch {\n      await rm(tmpPath, { force: true }).catch(() => {});\n      // Unconditionally restore a WORKING append handle, regardless of `this.handle`'s current\n      // truthiness: a failure partway through the steps above (write/sync/rename to the tmp file\n      // failing AFTER `this.handle?.close()` already ran) leaves `this.handle` closed-but-set —\n      // the old `if (!this.handle)` guard would then skip reopening entirely, and every later\n      // write would throw against a dead handle forever. Close-if-present (best-effort; it may\n      // already be closed) then always reopen fresh.\n      await this.handle?.close().catch(() => {});\n      this.handle = await open(this.journalPath, \"a\");\n    }\n  }\n\n  async append(entry: OutboxEntry): Promise<void> {\n    // Hydrate first if this is the very first call on this instance: applying `entry` to\n    // `this.state` BEFORE the journal replay would run means the replay (which mutates the SAME\n    // `this.state` object) could land AFTER this fresher write, letting a stale on-disk value win\n    // over the one just set — a state inversion. `updateStatus`/`dequeue`/`deleteMeta` already\n    // guard the same way.\n    if (!this.opened) await this.ready();\n    applyOp(this.state, { op: \"append\", entry: structuredClone(entry) });\n    await this.write({ op: \"append\", entry });\n  }\n\n  async updateStatus(clientId: string, seq: number, status: OutboxEntryStatus, error?: OutboxEntryError): Promise<void> {\n    if (!this.opened) await this.ready();\n    if (!this.state.entries.has(key(clientId, seq))) return; // silent no-op, contract behavior\n    applyOp(this.state, { op: \"status\", clientId, seq, status, error });\n    await this.write({ op: \"status\", clientId, seq, status, ...(error !== undefined ? { error } : {}) });\n  }\n\n  async dequeue(clientId: string, seq: number): Promise<void> {\n    if (!this.opened) await this.ready();\n    if (!this.state.entries.has(key(clientId, seq))) return;\n    applyOp(this.state, { op: \"dequeue\", clientId, seq });\n    await this.write({ op: \"dequeue\", clientId, seq });\n  }\n\n  async loadAll(): Promise<HydrateResult> {\n    await this.ready();\n    const all = [...this.state.entries.values()].sort((a, b) => a.order - b.order);\n    const { entries, dropped } = dropStaleVersion(all);\n    for (const e of dropped) {\n      applyOp(this.state, { op: \"dequeue\", clientId: e.clientId, seq: e.seq });\n      // Loss-safe, so the rejection is deliberately swallowed rather than surfaced: `e` is\n      // ALREADY removed from `this.state` and already returned to the caller inside `dropped` —\n      // the caller has already treated it as gone either way. If this particular disk write fails\n      // (e.g. transient disk-full), the stale-version row simply survives on disk to be dropped\n      // again, idempotently, on the NEXT hydrate. Leaving this unhandled would surface as an\n      // `unhandledRejection`, which several Electron/Node hosts treat as fatal — worse than a\n      // silently-retried cleanup.\n      void this.write({ op: \"dequeue\", clientId: e.clientId, seq: e.seq }).catch(() => {});\n    }\n    return { entries: entries.map((e) => structuredClone(e)), dropped };\n  }\n\n  async getMeta(clientId: string): Promise<OutboxMeta | undefined> {\n    await this.ready();\n    const m = this.state.meta.get(clientId);\n    return m ? structuredClone(m) : undefined;\n  }\n\n  async setMeta(clientId: string, meta: OutboxMeta): Promise<void> {\n    // Same first-open-ordering hazard as append() — see its comment.\n    if (!this.opened) await this.ready();\n    applyOp(this.state, { op: \"meta\", clientId, meta: structuredClone(meta) });\n    await this.write({ op: \"meta\", clientId, meta });\n  }\n\n  async listMetaClientIds(): Promise<string[]> {\n    await this.ready();\n    return [...this.state.meta.keys()];\n  }\n\n  async deleteMeta(clientId: string): Promise<void> {\n    if (!this.opened) await this.ready();\n    applyOp(this.state, { op: \"metaDelete\", clientId });\n    await this.write({ op: \"metaDelete\", clientId });\n  }\n\n  persist(): void {\n    // No-op: no eviction advisory exists on a filesystem.\n  }\n\n  /** NOTE for `finally`-block callers: under the fail-stop tail, `close()` PROPAGATES a prior\n   *  tail rejection (a racing op's flush error) rather than masking it — `await storage.close?.()`\n   *  in cleanup paths should tolerate a rejecting close (`.catch` it if the original error is\n   *  already being handled elsewhere). */\n  async close(): Promise<void> {\n    // The ENTIRE body runs as ONE link chained onto `this.tail` — not \"await ready(), then do\n    // more stuff off-tail\" as before. That old shape let `this.closed = true` and the final\n    // `compact()`/`handle.close()` run OUTSIDE the serialization every other disk mutation\n    // respects: a flush or compact racing concurrently with close() could interleave file-handle\n    // use with it (both touching `journal.tmp`/the append handle), and `closed` could flip true\n    // mid-flush, letting that flush's `return` resolve its callers' promises without ever writing\n    // their batch (see OutboxClosedError's doc comment for the fix on that half). Chaining the\n    // whole thing as one tail link makes \"final drain, then compact-if-excess, then mark closed,\n    // then close the handle\" atomic relative to every other operation in this class: anything\n    // already chained onto `this.tail` before this call runs first (the drain); anything chained\n    // after (including a `write()` racing close()) runs only once this ENTIRE body — including\n    // `this.closed = true` — has completed, and correctly observes `closed`.\n    this.tail = this.tail.then(async () => {\n      await this.openOnce(); // a close() before any op ever ran still needs a real handle to close\n      // Final compaction: a threshold-triggered mid-stream compact() resets opCount to the live\n      // state size, so a trailing run of ops shorter than COMPACT_THRESHOLD (e.g. ending the\n      // session right after crossing the threshold once) never crosses it again and would\n      // otherwise sit uncompacted on disk. Mirror openOnce's same excess check so a closed queue\n      // is always left compacted at rest.\n      if (this.opCount > this.state.entries.size + this.state.meta.size) await this.compact();\n      this.closed = true;\n      await this.handle?.close();\n      this.handle = undefined;\n    });\n    return this.tail;\n  }\n}\n\n/** Dirs opened (and locked) by THIS process — makes a same-process double-open deterministic and\n *  distinguishes a genuinely-live own-pid lock from one left by a previous boot that recycled our\n *  pid. Keyed by resolved dir path. */\nconst openDirs = new Set<string>();\n/** Lockfile paths for the best-effort exit hook (SIGKILL still leaks; the next open steals). */\nconst liveLocks = new Set<string>();\nlet exitHookRegistered = false;\n\nexport class OutboxLockHeldError extends Error {\n  readonly code = \"OUTBOX_LOCK_HELD\";\n  constructor(holder: number) {\n    super(`outbox dir is locked by live pid ${holder} — one writer per dir; falling back to memory`);\n    this.name = \"OutboxLockHeldError\";\n  }\n}\n\n/** Residual risk (standard for this unlink-based pidfile lock family, not a bug to fix here): a\n *  dead-pid classification and the `rm` that steals it are two separate steps — a THIRD process\n *  could win a fresh `wx` lock in the gap between them, and this attempt's `rm` would then delete\n *  that third process's live lockfile out from under it (TOCTOU). The receipts (exact-match\n *  `(identity, clientId, seq)` dedup atomic with commit) remain the actual safety net regardless;\n *  this lock is a best-effort single-writer optimization, not the correctness boundary. */\nasync function acquireLock(dir: string): Promise<string> {\n  const lockPath = join(dir, \"lock\");\n  for (let attempt = 0; attempt < 2; attempt++) {\n    try {\n      await writeFile(lockPath, JSON.stringify({ pid: process.pid, createdAt: Date.now() }), { flag: \"wx\" });\n      liveLocks.add(lockPath);\n      if (!exitHookRegistered) {\n        exitHookRegistered = true;\n        process.once(\"exit\", () => {\n          for (const p of liveLocks) {\n            try {\n              unlinkSync(p);\n            } catch {\n              /* already gone */\n            }\n          }\n        });\n      }\n      return lockPath;\n    } catch (e) {\n      if ((e as NodeJS.ErrnoException).code !== \"EEXIST\") throw e;\n      let stale = false;\n      try {\n        const { pid } = JSON.parse(await readFile(lockPath, \"utf8\")) as { pid?: unknown };\n        if (typeof pid !== \"number\") stale = true;\n        // Recycled pid from a prior boot vs. a genuinely-live lock THIS process already holds:\n        // keyed on `liveLocks` (only ever populated by this function's own happy-path write below,\n        // i.e. a lock we actually acquired), not `openDirs` — `openDirs` is registered synchronously\n        // at the top of fsOutbox()'s probe (before this function is even called), so by the time an\n        // own-pid EEXIST lands here `openDirs` already contains `dir` for THIS very attempt and\n        // would misclassify every fresh own-pid lockfile as \"live\" instead of \"recycled\".\n        else if (pid === process.pid) stale = !liveLocks.has(lockPath);\n        else {\n          try {\n            process.kill(pid, 0); // signal 0: existence probe only\n          } catch (killErr) {\n            if ((killErr as NodeJS.ErrnoException).code === \"ESRCH\") stale = true;\n            else throw new OutboxLockHeldError(pid); // EPERM: alive but not ours\n          }\n          if (!stale) throw new OutboxLockHeldError(pid);\n        }\n      } catch (parseOrHeld) {\n        if (parseOrHeld instanceof OutboxLockHeldError) throw parseOrHeld;\n        stale = true; // unreadable/garbage\n      }\n      if (!stale) throw new OutboxLockHeldError(-1);\n      await rm(lockPath, { force: true });\n      // loop: one retry of wx\n    }\n  }\n  throw new OutboxLockHeldError(-1);\n}\n\n/** The final shape: an async probe (lock the dir, hydrate the journal) wrapped in the same\n *  resolved/ready delegation `indexedDBOutbox()` uses (`outbox-storage.ts`) — every call made\n *  before the probe settles queues behind it; every call after routes directly. A same-process\n *  double-open on the same dir, a live foreign-pid lock, or any `openOnce()` failure (a truncate\n *  error, disk-full, etc.) all degrade to a fresh `memoryOutbox()` rather than throwing — a durable\n *  outbox that can't get its lock still has to behave like *an* outbox (verdict-consistent\n *  probe-and-fallback), just without cross-reload durability. `onFallback` fires exactly once for\n *  whichever reason won. */\nexport function fsOutbox(opts: FsOutboxOptions): OutboxStorage & { stats: { flushes: number; fsyncs: number } } {\n  const dir = resolve(opts.dir);\n  const stats = { flushes: 0, fsyncs: 0 };\n\n  let resolved: OutboxStorage | undefined;\n  const ready: Promise<OutboxStorage> = (async (): Promise<OutboxStorage> => {\n    if (openDirs.has(dir)) throw new OutboxLockHeldError(process.pid); // same-process double-open\n    // Register synchronously, before the first await: two same-process fsOutbox() calls in the\n    // same synchronous frame would otherwise both pass the `has()` check above (neither has\n    // registered yet), racing each other for the lock instead of one deterministically falling\n    // back via the registry hit. Every failure path below deregisters on its way out.\n    openDirs.add(dir);\n    let lockPath: string | undefined;\n    try {\n      await mkdir(dir, { recursive: true });\n      lockPath = await acquireLock(dir);\n      const store = new FsOutboxStorage(dir, opts.fsync !== false, stats);\n      // Eager hydrate: openOnce() runs lazily-but-awaited here rather than being left to the first\n      // method call AFTER this probe has already resolved to `store` — that shape would fail-stop\n      // the instance on an open/hydrate error instead of degrading to memoryOutbox() as the spec's\n      // error table mandates. Hydrating here, inside this try, routes that failure through the same\n      // catch below as a lock failure: lock released, dir deregistered, then onFallback + memory\n      // fallback.\n      await store.open();\n      const innerClose = store.close.bind(store);\n      store.close = async () => {\n        try {\n          await innerClose();\n        } finally {\n          // Fail-stop: release the lock and deregister the dir even if the inner (tail-chained)\n          // close rejected — a poisoned journal tail must not wedge this dir locked forever. The\n          // original rejection, if any, still propagates to the caller after this finally runs.\n          openDirs.delete(dir);\n          liveLocks.delete(lockPath!);\n          await unlink(lockPath!).catch(() => {});\n        }\n      };\n      return store;\n    } catch (err) {\n      // Any failure after the dir was registered (mkdir, lock acquisition, or the eager hydrate\n      // above) must not leave the dir wedged: deregister it always, and release the lock too if\n      // this attempt actually acquired one (a legitimately-held foreign lock is left untouched —\n      // acquireLock() never assigns `lockPath` when it throws OutboxLockHeldError).\n      openDirs.delete(dir);\n      if (lockPath) {\n        liveLocks.delete(lockPath);\n        await unlink(lockPath).catch(() => {});\n      }\n      throw err;\n    }\n  })().catch((err: unknown) => {\n    opts.onFallback?.(err);\n    return memoryOutbox();\n  });\n  void ready.then((impl) => {\n    resolved = impl;\n  });\n  const impl = async (): Promise<OutboxStorage> => resolved ?? ready;\n\n  return {\n    stats,\n    append: async (entry) => (await impl()).append(entry),\n    updateStatus: async (clientId, seq, status, error) => (await impl()).updateStatus(clientId, seq, status, error),\n    dequeue: async (clientId, seq) => (await impl()).dequeue(clientId, seq),\n    loadAll: async () => (await impl()).loadAll(),\n    getMeta: async (clientId) => (await impl()).getMeta(clientId),\n    setMeta: async (clientId, meta) => (await impl()).setMeta(clientId, meta),\n    listMetaClientIds: async () => (await impl()).listMetaClientIds?.() ?? [],\n    deleteMeta: async (clientId) => (await impl()).deleteMeta?.(clientId),\n    persist: () => {\n      void impl().then((i) => i.persist());\n    },\n    close: async () => (await impl()).close?.(),\n  };\n}\n"],"mappings":"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","names":["impl"]}

package/dist/outbox-storage-C6VHkXs9.d.ts

@@ -0,0 +1,191 @@
+import { JSONValue } from '@helipod/values';
+
+/**
+ * The `OutboxStorage` seam — the client's first storage API (verdict §(d), `docs/dev/research/
+ * offline-outbox/verdict.md`). Two implementations: `memoryOutbox()` (the default — preserves
+ * today's behavior byte-for-byte; nothing persists across a reload) and `indexedDBOutbox()`
+ * (probe-and-fallback: real durability in a browser, transparently degrades to `memoryOutbox()`
+ * wherever IndexedDB is unavailable or fails to open — Node, private-mode Safari, a corrupt
+ * origin). Durability is opt-in constructor config (`new HelipodClient(transport, { outbox:
+ * indexedDBOutbox() })`); a client constructed without `outbox` never touches this file's runtime
+ * branches that matter — `memoryOutbox()`'s Maps are just as ephemeral as the pre-outbox client.
+ *
+ * Persisted record shape is verdict §(d) verbatim: `{clientId, seq, requestId, udfPath, args, seed,
+ * order, status, identityFingerprint, outboxVersion, enqueuedAt}`. `order` is an explicit column —
+ * Map/array insertion order does not survive IndexedDB, and the drain (a later task) needs a
+ * persisted total order across the WHOLE shared queue (every clientId sharing this database), not
+ * just within one clientId's entries.
+ *
+ * Identity (verdict §(d) "Identity", hazard 8): **one clientId per tab-session, minted at client
+ * construction, never reused across a reload.** A fresh `HelipodClient` instance always mints a
+ * BRAND NEW clientId — there is no reseed protocol, so there is nothing to get wrong (hazard 8:
+ * "reload resets counters — dissolved structurally"). Entries persisted under an OLDER clientId
+ * from a previous session are untouched by minting a new one; they hydrate and drain under their
+ * own **recorded** `(clientId, seq)` pair later (a later task's drain). The "-or-loaded" half of
+ * `mintIdentity` concerns `nextSeq`, not `clientId`: a fresh clientId's meta row does not exist, so
+ * `nextSeq` starts at 0 — but the loader still calls `getMeta` first rather than assuming absence,
+ * so a colliding clientId (astronomically unlikely — see `defaultMintClientId`) resumes from its
+ * recorded `nextSeq` instead of silently reusing a seq that already named a payload (verdict §(b)'s
+ * governing invariant: the map `(clientId, seq) -> payload` is written exactly once).
+ */
+
+type OutboxEntryStatus = "unsent" | "inflight" | "parked" | "completed" | "failed";
+/** T5 (R9): the terminal verdict recorded alongside a `"failed"` durable entry — surfaced through
+ *  `client.pendingMutations()`/`usePendingMutations()` and `onMutationFailed`. */
+interface OutboxEntryError {
+    message: string;
+    code?: string;
+}
+/** One durable outbox record — the persisted twin of `PendingMutation` (`./mutation-log`), plus
+ *  the fields only a durable queue needs (`clientId`, `seq`, `order`, `identityFingerprint`,
+ *  `outboxVersion`, `enqueuedAt`). `args`/`seed` are the fields whose omission would make a
+ *  hydrated replay non-deterministic (verdict D2) — everything else (`touched`, the `update`
+ *  closure) is recomputed or looked up in the optimistic-updater registry, never persisted. */
+interface OutboxEntry {
+    clientId: string;
+    seq: number;
+    requestId: string;
+    udfPath: string;
+    args: JSONValue;
+    seed: {
+        entropy: string;
+        now: number;
+    };
+    /** Global position across the WHOLE shared queue (every clientId) — the drain's FIFO key. */
+    order: number;
+    status: OutboxEntryStatus;
+    /** SHA-256 of the `SetAuth` token at enqueue time; absent for an unauthenticated mutation. Set
+     *  at flush-time by a later task; carried as a plain field here so the schema is stable from
+     *  day one (verdict §(g) hazard 9). */
+    identityFingerprint?: string;
+    outboxVersion: number;
+    enqueuedAt: number;
+    /** T5 (R9): set (via `updateStatus`'s optional 4th argument) when `status` transitions to
+     *  `"failed"` — a terminal, server-recorded verdict a live `mutation()` promise may have no
+     *  awaiter for (a hydrated cross-reload entry, or a retried one). Absent for every other status. */
+    error?: OutboxEntryError;
+}
+interface OutboxMeta {
+    /** In-memory-serial cursor for this clientId's NEXT mutation, loaded once at mint time. */
+    nextSeq: number;
+    deployment?: string;
+}
+/** The result of a full-queue hydrate. `dropped` holds entries whose `outboxVersion` didn't match
+ *  the running code's `OUTBOX_VERSION` — removed from storage as a side effect of the hydrate
+ *  itself, returned so the caller can settle them with a terminal verdict rather than silently
+ *  discarding a promise's fate (verdict §(g) hazard 10: "outboxVersion stamp, drop-with-verdict at
+ *  hydrate"). */
+interface HydrateResult {
+    /** Current-version entries, in persisted `order`. */
+    entries: OutboxEntry[];
+    /** Stale-version entries deleted during this hydrate. */
+    dropped: OutboxEntry[];
+}
+/** The seam. Every method is safe to call concurrently — the IndexedDB implementation
+ *  write-behind-batches same-microtask calls into one transaction (see `outbox-idb.ts`). */
+interface OutboxStorage {
+    /** Durably record a new entry. The caller must NOT await this before sending the mutation on the
+     *  wire — "the send never waits for the append" (verdict §(d)); this promise exists so a caller
+     *  CAN confirm durability later (e.g. park-eligibility at transport close). */
+    append(entry: OutboxEntry): Promise<void>;
+    /** Mutate only `status` (and, when given, `error` — T5's R9 terminal-failure record; every other
+     *  field is preserved verbatim). Called with `status: "failed"` INSTEAD OF `dequeue()` on a
+     *  terminal failure (verdict §(d) R9: "failed entries persist until dismissed/retried") — every
+     *  other status transition (`"inflight"`/`"unsent"`/`"parked"`) omits `error`. */
+    updateStatus(clientId: string, seq: number, status: OutboxEntryStatus, error?: OutboxEntryError): Promise<void>;
+    /** Remove a fully-settled entry. */
+    dequeue(clientId: string, seq: number): Promise<void>;
+    /** Hydrate the whole shared queue, across every clientId, in persisted `order`. */
+    loadAll(): Promise<HydrateResult>;
+    getMeta(clientId: string): Promise<OutboxMeta | undefined>;
+    setMeta(clientId: string, meta: OutboxMeta): Promise<void>;
+    /** OPTIONAL (verdict §(g) hazard 1 / Task 4's dead-meta prune): every clientId with a meta row.
+     *  The drain uses it at hydrate to reclaim rows for clientIds that are neither the current session
+     *  nor have any live queue entries — one such tiny row otherwise accrues per prior tab-session and
+     *  every `onClientReset`. Optional so a minimal `OutboxStorage` double (which never prunes) stays
+     *  valid; both shipped backends implement it. */
+    listMetaClientIds?(): Promise<string[]>;
+    /** OPTIONAL companion to {@link listMetaClientIds} — delete one dead meta row. */
+    deleteMeta?(clientId: string): Promise<void>;
+    /** Advisory `navigator.storage.persist()` request — fire-and-forget, no return value, and no
+     *  behavior anywhere ever branches on whether the grant is honored (verdict §(g) hazard 3: "zero
+     *  behavior branches on the grant"). A no-op for the memory backend. */
+    persist(): void;
+    /** OPTIONAL: flush pending writes and release any backing resources (fs lock, IDB handle).
+     *  Additive like `listMetaClientIds` — callers guard with `?.`. Nothing in the client core
+     *  calls it; it exists for host shutdown/relaunch flows (Electron window cycling) and tests.
+     *  A client that never calls it loses nothing (backends self-heal: exit hooks, stale-lock
+     *  steal, IDB's own connection lifecycle). */
+    close?(): Promise<void>;
+}
+/** Default cap on how many outbox-tracked entries (`unsent`/`inflight`/`parked` — not yet fully
+ *  settled) may sit in `client.ts`'s live log at once, per verdict §(d) "Enqueue": "bounded
+ *  (default 1000)". Overridable via `new HelipodClient(transport, { outboxMaxQueueSize })`. */
+declare const DEFAULT_OUTBOX_MAX_QUEUE_SIZE = 1000;
+/** Thrown (as a rejected `mutation()` promise, never a synchronous throw) when the durable outbox
+ *  is at capacity. Verdict §(d): the NEW enqueue is rejected, not the oldest queued one — "the new
+ *  write has a live awaiter [this very call]; the oldest durable promise may not [e.g. it survived
+ *  a reload, where there is no live JS promise for it at all until the registry rebuilds a layer]."
+ *  A coded error (`.code`) so callers can distinguish this from every other mutation failure. */
+declare class OutboxOverflowError extends Error {
+    readonly code = "OUTBOX_OVERFLOW";
+    constructor(message?: string);
+}
+/** Rejection for a parked mutation the server disowned on `ConnectAck{known: false}` — the client's
+ *  presented history matched neither a record nor a floor (a swept/foreign/reset timeline), so the
+ *  client re-mints its identity (`onClientReset`). A parked entry was in-flight when the socket
+ *  dropped: its outcome is genuinely unknowable and, since the server has no dedup record for it,
+ *  a blind resend under a fresh clientId could double-apply — so it rejects LOUDLY (verdict §(d)
+ *  Retention: "parked entries reject loudly"). Coded so apps can distinguish it from every other
+ *  failure. `unsent` entries (never hit the wire) are safe to re-enqueue instead and are NOT
+ *  rejected. */
+declare class OfflineClientResetError extends Error {
+    readonly code = "OFFLINE_CLIENT_RESET";
+    constructor(message?: string);
+}
+/** The in-memory default — what a client gets when it passes no `outbox` at all. Nothing here
+ *  survives past this `HelipodClient` instance's lifetime, which is exactly today's (pre-outbox)
+ *  behavior: a reload has no durable queue to hydrate, because there never was one. */
+declare function memoryOutbox(): OutboxStorage;
+interface IndexedDBOutboxOptions {
+    /** Injectable for tests / non-default globals — defaults to `globalThis.indexedDB`. */
+    indexedDB?: IDBFactory;
+    dbName?: string;
+    /** Best-effort, fire-and-forget notification whenever the adapter falls back to memory — e.g.
+     *  no IndexedDB in this runtime, or `open()` failed (private-mode Safari, a corrupt origin). The
+     *  fallback itself is never gated on this callback existing or succeeding. */
+    onFallback?: (reason: unknown) => void;
+}
+/** Probe-and-fallback (verdict §(g) hazard 5): if IndexedDB isn't available in this runtime at
+ *  all, or `open()` fails for any reason, every method transparently delegates to a fresh
+ *  `memoryOutbox()` instead — same interface, same call sites, only durability is lost. The probe
+ *  is asynchronous (an IDB `open()` can only fail asynchronously), so calls made before the
+ *  outcome is known queue behind the open attempt; every call after routes directly with no added
+ *  latency. */
+declare function indexedDBOutbox(opts?: IndexedDBOutboxOptions): OutboxStorage;
+/** Not `crypto.randomUUID()` unconditionally — some test/SSR runtimes lack it. Collision odds are
+ *  irrelevant either way: `mintIdentity` re-reads `getMeta` for whatever id comes out, so even a
+ *  freak collision resumes from a recorded `nextSeq` rather than silently reusing a seq.
+ *
+ *  Exported (beyond `mintIdentity`'s internal default) so `client.ts` can mint a clientId
+ *  SYNCHRONOUSLY at construction — `mutation()` must stay fully synchronous (T1's open concern),
+ *  so the clientId every entry stamps cannot wait on `mintIdentity`'s async `getMeta`/`setMeta`
+ *  round-trip. `client.ts` mints with this directly, then feeds the SAME id into `mintIdentity` via
+ *  `opts.mintClientId` so the durable meta row it persists names the id actually in use. */
+declare function defaultMintClientId(): string;
+/**
+ * Mint this tab-session's clientId and establish its `nextSeq` cursor in the outbox's meta store.
+ * Per the file doc's identity model: ALWAYS mints a fresh clientId — never reuses one from a prior
+ * session. Returns `{clientId, nextSeq}`; the caller (client construction) keeps `nextSeq` as an
+ * in-memory serial counter from here on (verdict §(d): "seqs minted serially in-memory per tab") —
+ * it is not re-read from storage again this session.
+ */
+declare function mintIdentity(storage: OutboxStorage, opts?: {
+    deployment?: string;
+    mintClientId?: () => string;
+}): Promise<{
+    clientId: string;
+    nextSeq: number;
+}>;
+
+export { DEFAULT_OUTBOX_MAX_QUEUE_SIZE as D, type HydrateResult as H, type IndexedDBOutboxOptions as I, type OutboxEntry as O, type OutboxStorage as a, OfflineClientResetError as b, type OutboxEntryError as c, type OutboxEntryStatus as d, type OutboxMeta as e, OutboxOverflowError as f, defaultMintClientId as g, mintIdentity as h, indexedDBOutbox as i, memoryOutbox as m };

package/dist/react.d.ts

@@ -0,0 +1,114 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Value } from '@helipod/values';
+import { H as HelipodClient, j as OptimisticLocalStore, c as AnyFunctionReference, F as FunctionArgs, h as FunctionReturnType, g as FunctionReference, r as PendingMutationEntry } from './client-mJZjEkhK.js';
+import '@helipod/sync';
+import './outbox-storage-C6VHkXs9.js';
+
+/**
+ * `useNotifications()` / `<Inbox>` — the typed reactive in-app inbox helper (Global Constraints:
+ * "the reactive in-app inbox is the flagship"). Wraps the well-known `@helipod/notifications`
+ * component query/mutation paths (`notifications:inbox`/`unreadCount`/`markRead`/`markAllRead`) so
+ * consumers get a live feed + unread count + typed mark-read callbacks with zero per-app codegen.
+ * Component functions aren't in an app's generated `Api`, so typing lives HERE (well-known paths),
+ * while the server-side `ctx.notifications.send` is typed via the component's `contextType`
+ * augmentation.
+ */
+
+/** An inbox row as delivered to the UI (mirrors the server `InboxItem`). */
+interface InboxNotification {
+    _id: string;
+    title: string;
+    body: string;
+    data?: Record<string, unknown>;
+    read: boolean;
+    readAt?: number;
+    createdAt: number;
+    messageId: string;
+}
+interface UseNotificationsResult {
+    notifications: InboxNotification[];
+    unreadCount: number;
+    markRead: (id: string) => Promise<void>;
+    markAllRead: () => Promise<void>;
+}
+/** Live inbox feed + unread count + mark-read callbacks. `undefined` first-frame results coalesce to
+ *  `[]`/`0` so consumers never branch on the loading sentinel. */
+declare function useNotifications(opts?: {
+    limit?: number;
+}): UseNotificationsResult;
+interface InboxProps {
+    limit?: number;
+    /** Render prop — headless: you own the markup, we own the reactive data + callbacks. */
+    children: (state: UseNotificationsResult) => ReactNode;
+}
+/** A headless `<Inbox>` render helper: `<Inbox>{({ notifications, unreadCount, markRead }) => …}</Inbox>`. */
+declare function Inbox(props: InboxProps): ReactNode;
+/** N3 — a caller's own `(category, channel|category-wide)` preference row, as delivered to the UI
+ *  (mirrors the server `getPreferences` return; `channel` absent = category-wide). */
+interface NotificationPreference {
+    category: string;
+    channel?: "email" | "sms" | "in_app" | "push";
+    enabled: boolean;
+}
+interface UseNotificationPreferencesResult {
+    preferences: NotificationPreference[];
+    setPreference: (args: NotificationPreference) => Promise<void>;
+}
+/** N3 — live view of the caller's own notification preferences + a setter. Server-resolved identity
+ *  (same ownership model as `useNotifications`'s inbox) — there is no `userId` arg to pass. */
+declare function useNotificationPreferences(): UseNotificationPreferencesResult;
+/** Register this device's push token for the CURRENT authenticated caller (self-only, server-
+ *  resolved — see `docs/superpowers/specs/2026-04-13-notifications-push-channel-design.md`).
+ *  Acquiring the actual OS token (Expo `getExpoPushTokenAsync()`, a native FCM/APNs SDK, or a web
+ *  `PushManager.subscribe`) is the caller's responsibility — this is a thin wire call, nothing
+ *  more, matching `useNotifications`'s scope boundary for the inbox. A plain async function (not a
+ *  hook): registration typically happens once at app-boot/permission-grant time, not on every
+ *  render. */
+declare function registerForPush(client: HelipodClient, args: {
+    token: string;
+    provider: "expo" | "fcm" | "apns";
+    platform?: "ios" | "android" | "web";
+}): Promise<void>;
+/** Unregister this device's push token (e.g. on sign-out / permission revoke). */
+declare function unregisterForPush(client: HelipodClient, args: {
+    token: string;
+}): Promise<void>;
+
+declare function HelipodProvider(props: {
+    client: HelipodClient;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useHelipodClient(): HelipodClient;
+/** Subscribe to a reactive query; returns `undefined` until the first result arrives. */
+declare function useQuery<Q extends AnyFunctionReference<any, any>>(ref: Q, args?: FunctionArgs<Q>): FunctionReturnType<Q> | undefined;
+declare function useQuery<T = Value>(ref: FunctionReference | string, args?: Record<string, Value>): T | undefined;
+/** The optimistic-update closure a `withOptimisticUpdate` call receives — the typed public store. */
+type OptimisticUpdateHandler<Args> = (store: OptimisticLocalStore, args: Args) => void;
+/**
+ * The callable `useMutation` returns: calling it runs the mutation; `.withOptimisticUpdate(fn)`
+ * returns a NEW callable with `fn` bound (Convex-verbatim — it does not mutate the receiver, so
+ * `useMutation(ref)` itself stays reusable without an optimistic update).
+ */
+interface MutationCallback<Args = Record<string, Value>, Returns = Value> {
+    (args?: Args): Promise<Returns>;
+    withOptimisticUpdate(updater: OptimisticUpdateHandler<Args>): MutationCallback<Args, Returns>;
+}
+/** Returns a callable that runs a mutation and resolves with its return value; `.withOptimisticUpdate(fn)` chains an optimistic update (verdict §(b)). */
+declare function useMutation<Q extends AnyFunctionReference<any, any>>(ref: Q): MutationCallback<FunctionArgs<Q>, FunctionReturnType<Q>>;
+declare function useMutation<T = Value>(ref: FunctionReference | string): MutationCallback<Record<string, Value>, T>;
+/** Returns a callback that runs an action and resolves with its return value. Not reactive — mirrors `useMutation`, not `useQuery`. */
+declare function useAction<Q extends AnyFunctionReference<any, any>>(ref: Q): (args?: FunctionArgs<Q>) => Promise<FunctionReturnType<Q>>;
+declare function useAction<T = Value>(ref: FunctionReference | string): (args?: Record<string, Value>) => Promise<T>;
+/**
+ * T5 (R9) — a live snapshot of the durable outbox: `[]` until the first read resolves (and forever,
+ * without an `outbox` configured — `HelipodClient.pendingMutations()`'s own no-outbox behavior).
+ * Re-reads on every `client.onOutboxChange` notification — every local outbox-mutating op AND, when
+ * a `BroadcastChannel` is available, an incoming cross-tab nudge from ANOTHER tab sharing the same
+ * durable store (verdict §(d) "Observability": "usePendingMutations() reactive... a BroadcastChannel
+ * nudge cross-tab"). See `docs/enduser/offline.md`'s pending-tray recipe for the documented pattern
+ * (`packages/client/test/pending-tray-recipe.test.tsx` is its compiling fixture).
+ */
+declare function usePendingMutations(): PendingMutationEntry[];
+
+export { HelipodProvider, Inbox, type InboxNotification, type InboxProps, type MutationCallback, type NotificationPreference, type OptimisticUpdateHandler, type UseNotificationPreferencesResult, type UseNotificationsResult, registerForPush, unregisterForPush, useAction, useHelipodClient, useMutation, useNotificationPreferences, useNotifications, usePendingMutations, useQuery };

package/dist/react.js

@@ -0,0 +1,139 @@
+import {
+  getFunctionPath
+} from "./chunk-I7ZJFW4E.js";
+import "./chunk-DW55SNHW.js";
+
+// src/react.tsx
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { convexToJson } from "@helipod/values";
+
+// src/notifications.tsx
+var INBOX_PATH = "notifications:inbox";
+var UNREAD_PATH = "notifications:unreadCount";
+var MARK_READ_PATH = "notifications:markRead";
+var MARK_ALL_PATH = "notifications:markAllRead";
+function useNotifications(opts) {
+  const notifications = useQuery(INBOX_PATH, { limit: opts?.limit ?? 50 }) ?? [];
+  const unreadCount = useQuery(UNREAD_PATH, {}) ?? 0;
+  const markReadFn = useMutation(MARK_READ_PATH);
+  const markAllFn = useMutation(MARK_ALL_PATH);
+  return {
+    notifications,
+    unreadCount,
+    markRead: async (id) => {
+      await markReadFn({ id });
+    },
+    markAllRead: async () => {
+      await markAllFn({});
+    }
+  };
+}
+function Inbox(props) {
+  return props.children(useNotifications({ limit: props.limit }));
+}
+var PREFS_GET = "notifications:getPreferences";
+var PREFS_SET = "notifications:setPreference";
+function useNotificationPreferences() {
+  const preferences = useQuery(PREFS_GET, {}) ?? [];
+  const setFn = useMutation(PREFS_SET);
+  return {
+    preferences,
+    setPreference: async (args) => {
+      await setFn(args);
+    }
+  };
+}
+var REGISTER_PUSH_PATH = "notifications:registerPushToken";
+var UNREGISTER_PUSH_PATH = "notifications:unregisterPushToken";
+async function registerForPush(client, args) {
+  await client.mutation(REGISTER_PUSH_PATH, args);
+}
+async function unregisterForPush(client, args) {
+  await client.mutation(UNREGISTER_PUSH_PATH, args);
+}
+
+// src/react.tsx
+import { jsx } from "react/jsx-runtime";
+var ClientContext = createContext(null);
+function HelipodProvider(props) {
+  return /* @__PURE__ */ jsx(ClientContext.Provider, { value: props.client, children: props.children });
+}
+function useHelipodClient() {
+  const client = useContext(ClientContext);
+  if (!client) throw new Error("useHelipodClient must be used within <HelipodProvider>");
+  return client;
+}
+function argsKey(ref, args) {
+  return `${getFunctionPath(ref)}|${JSON.stringify(convexToJson(args))}`;
+}
+function useQuery(ref, args = {}) {
+  const client = useHelipodClient();
+  const [value, setValue] = useState(void 0);
+  const key = argsKey(ref, args);
+  useEffect(() => {
+    setValue(void 0);
+    const unsubscribe = client.subscribe(ref, args, (v) => setValue(v));
+    return unsubscribe;
+  }, [client, key]);
+  return value;
+}
+function createMutationCallback(client, path, updater) {
+  const withUpdateCache = /* @__PURE__ */ new WeakMap();
+  const call = ((args) => client.mutation(
+    path,
+    args ?? {},
+    updater ? { optimisticUpdate: updater } : {}
+  ));
+  call.withOptimisticUpdate = (next) => {
+    let bound = withUpdateCache.get(next);
+    if (!bound) {
+      bound = createMutationCallback(client, path, next);
+      withUpdateCache.set(next, bound);
+    }
+    return bound;
+  };
+  return call;
+}
+function useMutation(ref) {
+  const client = useHelipodClient();
+  const path = getFunctionPath(ref);
+  return useMemo(() => createMutationCallback(client, path), [client, path]);
+}
+function useAction(ref) {
+  const client = useHelipodClient();
+  const path = getFunctionPath(ref);
+  return useCallback((args = {}) => client.action(path, args), [client, path]);
+}
+function usePendingMutations() {
+  const client = useHelipodClient();
+  const [entries, setEntries] = useState([]);
+  useEffect(() => {
+    let cancelled = false;
+    const refresh = () => {
+      void client.pendingMutations().then((next) => {
+        if (!cancelled) setEntries(next);
+      });
+    };
+    refresh();
+    const unsubscribe = client.onOutboxChange(refresh);
+    return () => {
+      cancelled = true;
+      unsubscribe();
+    };
+  }, [client]);
+  return entries;
+}
+export {
+  HelipodProvider,
+  Inbox,
+  registerForPush,
+  unregisterForPush,
+  useAction,
+  useHelipodClient,
+  useMutation,
+  useNotificationPreferences,
+  useNotifications,
+  usePendingMutations,
+  useQuery
+};
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react.tsx","../src/notifications.tsx"],"sourcesContent":["/**\n * React bindings — `useQuery` subscribes a component to a reactive query (re-rendering on\n * every server push), `useMutation` returns a callback that runs a mutation. The headline DX:\n * a component that calls `useQuery(api.messages.list, { conversationId })` updates live when\n * anyone sends a message, with zero manual wiring.\n *\n * T5 adds `useMutation(ref).withOptimisticUpdate(fn)` (Convex-verbatim chaining, verdict §(b)) and\n * threads T3's `FunctionArgs`/`FunctionReturnType` generics through all three hooks: passing a\n * codegen-generated ref (`api.messages.send`, typed against the app's `_generated/api.d.ts`) infers\n * typed args/return; the client's own untyped `{ __path }` ref or a raw string path fall back to\n * the pre-existing `Record<string, Value>`/`Value` shape with an explicit `T` override, unchanged.\n */\nimport { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from \"react\";\nimport { convexToJson, type Value } from \"@helipod/values\";\nimport { HelipodClient, type PendingMutationEntry } from \"./client\";\nimport { getFunctionPath, type AnyFunctionRef, type FunctionReference } from \"./api\";\nimport type { AnyFunctionReference, FunctionArgs, FunctionReturnType } from \"./function-types\";\nimport type { OptimisticLocalStore } from \"./optimistic-store\";\nimport type { OptimisticUpdate } from \"./layered-store\";\n\nconst ClientContext = createContext<HelipodClient | null>(null);\n\nexport function HelipodProvider(props: { client: HelipodClient; children: ReactNode }) {\n  return <ClientContext.Provider value={props.client}>{props.children}</ClientContext.Provider>;\n}\n\nexport function useHelipodClient(): HelipodClient {\n  const client = useContext(ClientContext);\n  if (!client) throw new Error(\"useHelipodClient must be used within <HelipodProvider>\");\n  return client;\n}\n\nfunction argsKey(ref: AnyFunctionRef, args: Record<string, Value>): string {\n  return `${getFunctionPath(ref)}|${JSON.stringify(convexToJson(args as Value))}`;\n}\n\n/** Subscribe to a reactive query; returns `undefined` until the first result arrives. */\nexport function useQuery<Q extends AnyFunctionReference<any, any>>(ref: Q, args?: FunctionArgs<Q>): FunctionReturnType<Q> | undefined;\nexport function useQuery<T = Value>(ref: FunctionReference | string, args?: Record<string, Value>): T | undefined;\nexport function useQuery(ref: AnyFunctionRef, args: Record<string, Value> = {}): unknown {\n  const client = useHelipodClient();\n  const [value, setValue] = useState<Value | undefined>(undefined);\n  const key = argsKey(ref, args);\n\n  useEffect(() => {\n    setValue(undefined);\n    const unsubscribe = client.subscribe(ref as FunctionReference | string, args, (v) => setValue(v));\n    return unsubscribe;\n    // `key` captures ref+args identity; re-subscribe only when it changes.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [client, key]);\n\n  return value;\n}\n\n/** The optimistic-update closure a `withOptimisticUpdate` call receives — the typed public store. */\nexport type OptimisticUpdateHandler<Args> = (store: OptimisticLocalStore, args: Args) => void;\n\n/**\n * The callable `useMutation` returns: calling it runs the mutation; `.withOptimisticUpdate(fn)`\n * returns a NEW callable with `fn` bound (Convex-verbatim — it does not mutate the receiver, so\n * `useMutation(ref)` itself stays reusable without an optimistic update).\n */\nexport interface MutationCallback<Args = Record<string, Value>, Returns = Value> {\n  (args?: Args): Promise<Returns>;\n  withOptimisticUpdate(updater: OptimisticUpdateHandler<Args>): MutationCallback<Args, Returns>;\n}\n\n/**\n * Builds one mutation callable. A `WeakMap` cache keyed by the `updater` function reference lives\n * inside this closure (persisted across renders via the `useMemo` below) — calling\n * `.withOptimisticUpdate(sameUpdaterRef)` again on a later render returns the SAME bound callable\n * (identity does not churn) as long as the caller's `updater` reference is itself stable (e.g.\n * module-scoped or `useCallback`-memoized); a fresh inline closure every render churns by\n * necessity — there is no way to detect two closures are \"the same update\" without a reference.\n */\nfunction createMutationCallback<Args, Returns>(\n  client: HelipodClient,\n  path: string,\n  updater?: OptimisticUpdateHandler<Args>,\n): MutationCallback<Args, Returns> {\n  const withUpdateCache = new WeakMap<OptimisticUpdateHandler<Args>, MutationCallback<Args, Returns>>();\n  const call = ((args?: Args) =>\n    client.mutation(\n      path,\n      (args ?? {}) as Record<string, Value>,\n      updater ? { optimisticUpdate: updater as unknown as OptimisticUpdate } : {},\n    ) as Promise<Returns>) as MutationCallback<Args, Returns>;\n  call.withOptimisticUpdate = (next: OptimisticUpdateHandler<Args>) => {\n    let bound = withUpdateCache.get(next);\n    if (!bound) {\n      bound = createMutationCallback<Args, Returns>(client, path, next);\n      withUpdateCache.set(next, bound);\n    }\n    return bound;\n  };\n  return call;\n}\n\n/** Returns a callable that runs a mutation and resolves with its return value; `.withOptimisticUpdate(fn)` chains an optimistic update (verdict §(b)). */\nexport function useMutation<Q extends AnyFunctionReference<any, any>>(\n  ref: Q,\n): MutationCallback<FunctionArgs<Q>, FunctionReturnType<Q>>;\nexport function useMutation<T = Value>(ref: FunctionReference | string): MutationCallback<Record<string, Value>, T>;\nexport function useMutation(ref: AnyFunctionRef): MutationCallback<any, any> {\n  const client = useHelipodClient();\n  const path = getFunctionPath(ref);\n  return useMemo(() => createMutationCallback(client, path), [client, path]);\n}\n\n/** Returns a callback that runs an action and resolves with its return value. Not reactive — mirrors `useMutation`, not `useQuery`. */\nexport function useAction<Q extends AnyFunctionReference<any, any>>(ref: Q): (args?: FunctionArgs<Q>) => Promise<FunctionReturnType<Q>>;\nexport function useAction<T = Value>(ref: FunctionReference | string): (args?: Record<string, Value>) => Promise<T>;\nexport function useAction(ref: AnyFunctionRef): (args?: Record<string, Value>) => Promise<Value> {\n  const client = useHelipodClient();\n  const path = getFunctionPath(ref);\n  return useCallback((args: Record<string, Value> = {}) => client.action(path, args), [client, path]);\n}\n\n/**\n * T5 (R9) — a live snapshot of the durable outbox: `[]` until the first read resolves (and forever,\n * without an `outbox` configured — `HelipodClient.pendingMutations()`'s own no-outbox behavior).\n * Re-reads on every `client.onOutboxChange` notification — every local outbox-mutating op AND, when\n * a `BroadcastChannel` is available, an incoming cross-tab nudge from ANOTHER tab sharing the same\n * durable store (verdict §(d) \"Observability\": \"usePendingMutations() reactive... a BroadcastChannel\n * nudge cross-tab\"). See `docs/enduser/offline.md`'s pending-tray recipe for the documented pattern\n * (`packages/client/test/pending-tray-recipe.test.tsx` is its compiling fixture).\n */\nexport function usePendingMutations(): PendingMutationEntry[] {\n  const client = useHelipodClient();\n  const [entries, setEntries] = useState<PendingMutationEntry[]>([]);\n\n  useEffect(() => {\n    let cancelled = false;\n    const refresh = () => {\n      void client.pendingMutations().then((next) => {\n        if (!cancelled) setEntries(next);\n      });\n    };\n    refresh();\n    const unsubscribe = client.onOutboxChange(refresh);\n    return () => {\n      cancelled = true;\n      unsubscribe();\n    };\n  }, [client]);\n\n  return entries;\n}\n\n// Reactive in-app inbox helper (@helipod/notifications) — see ./notifications.\nexport { useNotifications, Inbox, useNotificationPreferences, registerForPush, unregisterForPush } from \"./notifications\";\nexport type { InboxNotification, UseNotificationsResult, InboxProps, NotificationPreference, UseNotificationPreferencesResult } from \"./notifications\";\n","/**\n * `useNotifications()` / `<Inbox>` — the typed reactive in-app inbox helper (Global Constraints:\n * \"the reactive in-app inbox is the flagship\"). Wraps the well-known `@helipod/notifications`\n * component query/mutation paths (`notifications:inbox`/`unreadCount`/`markRead`/`markAllRead`) so\n * consumers get a live feed + unread count + typed mark-read callbacks with zero per-app codegen.\n * Component functions aren't in an app's generated `Api`, so typing lives HERE (well-known paths),\n * while the server-side `ctx.notifications.send` is typed via the component's `contextType`\n * augmentation.\n */\nimport type { ReactNode } from \"react\";\nimport type { Value } from \"@helipod/values\";\nimport { useQuery, useMutation } from \"./react\";\nimport type { HelipodClient } from \"./client\";\n\n/** An inbox row as delivered to the UI (mirrors the server `InboxItem`). */\nexport interface InboxNotification {\n  _id: string;\n  title: string;\n  body: string;\n  data?: Record<string, unknown>;\n  read: boolean;\n  readAt?: number;\n  createdAt: number;\n  messageId: string;\n}\n\nexport interface UseNotificationsResult {\n  notifications: InboxNotification[];\n  unreadCount: number;\n  markRead: (id: string) => Promise<void>;\n  markAllRead: () => Promise<void>;\n}\n\nconst INBOX_PATH = \"notifications:inbox\";\nconst UNREAD_PATH = \"notifications:unreadCount\";\nconst MARK_READ_PATH = \"notifications:markRead\";\nconst MARK_ALL_PATH = \"notifications:markAllRead\";\n\n/** Live inbox feed + unread count + mark-read callbacks. `undefined` first-frame results coalesce to\n *  `[]`/`0` so consumers never branch on the loading sentinel. */\nexport function useNotifications(opts?: { limit?: number }): UseNotificationsResult {\n  const notifications = useQuery<InboxNotification[]>(INBOX_PATH, { limit: opts?.limit ?? 50 }) ?? [];\n  const unreadCount = useQuery<number>(UNREAD_PATH, {}) ?? 0;\n  const markReadFn = useMutation<null>(MARK_READ_PATH);\n  const markAllFn = useMutation<null>(MARK_ALL_PATH);\n  return {\n    notifications,\n    unreadCount,\n    markRead: async (id: string) => { await markReadFn({ id }); },\n    markAllRead: async () => { await markAllFn({}); },\n  };\n}\n\nexport interface InboxProps {\n  limit?: number;\n  /** Render prop — headless: you own the markup, we own the reactive data + callbacks. */\n  children: (state: UseNotificationsResult) => ReactNode;\n}\n\n/** A headless `<Inbox>` render helper: `<Inbox>{({ notifications, unreadCount, markRead }) => …}</Inbox>`. */\nexport function Inbox(props: InboxProps): ReactNode {\n  return props.children(useNotifications({ limit: props.limit }));\n}\n\n/** N3 — a caller's own `(category, channel|category-wide)` preference row, as delivered to the UI\n *  (mirrors the server `getPreferences` return; `channel` absent = category-wide). */\nexport interface NotificationPreference {\n  category: string;\n  channel?: \"email\" | \"sms\" | \"in_app\" | \"push\";\n  enabled: boolean;\n}\n\nexport interface UseNotificationPreferencesResult {\n  preferences: NotificationPreference[];\n  setPreference: (args: NotificationPreference) => Promise<void>;\n}\n\nconst PREFS_GET = \"notifications:getPreferences\";\nconst PREFS_SET = \"notifications:setPreference\";\n\n/** N3 — live view of the caller's own notification preferences + a setter. Server-resolved identity\n *  (same ownership model as `useNotifications`'s inbox) — there is no `userId` arg to pass. */\nexport function useNotificationPreferences(): UseNotificationPreferencesResult {\n  const preferences = useQuery<NotificationPreference[]>(PREFS_GET, {}) ?? [];\n  const setFn = useMutation<null>(PREFS_SET);\n  return {\n    preferences,\n    setPreference: async (args: NotificationPreference) => {\n      await setFn(args as unknown as Record<string, Value>);\n    },\n  };\n}\n\nconst REGISTER_PUSH_PATH = \"notifications:registerPushToken\";\nconst UNREGISTER_PUSH_PATH = \"notifications:unregisterPushToken\";\n\n/** Register this device's push token for the CURRENT authenticated caller (self-only, server-\n *  resolved — see `docs/superpowers/specs/2026-04-13-notifications-push-channel-design.md`).\n *  Acquiring the actual OS token (Expo `getExpoPushTokenAsync()`, a native FCM/APNs SDK, or a web\n *  `PushManager.subscribe`) is the caller's responsibility — this is a thin wire call, nothing\n *  more, matching `useNotifications`'s scope boundary for the inbox. A plain async function (not a\n *  hook): registration typically happens once at app-boot/permission-grant time, not on every\n *  render. */\nexport async function registerForPush(client: HelipodClient, args: { token: string; provider: \"expo\" | \"fcm\" | \"apns\"; platform?: \"ios\" | \"android\" | \"web\" }): Promise<void> {\n  await client.mutation(REGISTER_PUSH_PATH, args as unknown as Record<string, Value>);\n}\n\n/** Unregister this device's push token (e.g. on sign-out / permission revoke). */\nexport async function unregisterForPush(client: HelipodClient, args: { token: string }): Promise<void> {\n  await client.mutation(UNREGISTER_PUSH_PATH, args as unknown as Record<string, Value>);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@helipod/client",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./outbox-fs": {
+      "types": "./dist/outbox-fs.d.ts",
+      "default": "./dist/outbox-fs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@helipod/id-codec": "0.1.0",
+    "@helipod/index-key-codec": "0.1.0",
+    "@helipod/sync": "0.1.0",
+    "@helipod/values": "0.1.0"
+  },
+  "devDependencies": {
+    "@helipod/docstore-sqlite": "0.1.0",
+    "@helipod/executor": "0.1.0",
+    "@helipod/query-engine": "0.1.0",
+    "@helipod/runtime-embedded": "0.1.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.10.5",
+    "@types/react": "^18.3.18",
+    "fake-indexeddb": "^6.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helipod-sh/helipod.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/helipod-sh/helipod"
+}