@openparachute/vault 0.7.0-rc.9 → 0.7.2-rc.3

package/core/src/txn.test.ts

@@ -89,9 +89,12 @@ describe("transaction (sync)", () => {
     expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
   });
 
-  it("preserves the callback error even when ROLLBACK also fails", () => {
+  it("preserves the callback error when ROLLBACK fails for the expected 'already-resolved' reason", () => {
     const callbackErr = new Error("callback boom");
-    const rollbackErr = new Error("rollback boom");
+    // The one swallowed case: the txn was already resolved, so ROLLBACK is a
+    // no-op that reports "no transaction is active". The ORIGINAL callback
+    // error is the root cause and must still propagate.
+    const rollbackErr = new Error("cannot rollback - no transaction is active");
     const { db } = fakeDb({ rollbackThrows: rollbackErr });
     let thrown: unknown;
     try {
@@ -101,6 +104,22 @@ describe("transaction (sync)", () => {
     }
     expect(thrown).toBe(callbackErr);
   });
+
+  it("re-throws an UNEXPECTED ROLLBACK failure instead of silently masking it (vault#589 NIT 2)", () => {
+    const callbackErr = new Error("callback boom");
+    // A rollback failure that is NOT the benign "already-resolved" case (a
+    // corrupt connection / lost write lock) means the transaction may NOT have
+    // rolled back — surfacing it beats a false "clean rollback".
+    const rollbackErr = new Error("database disk image is malformed");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      transaction(db, () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(rollbackErr);
+  });
 });
 
 describe("transaction — native transactionSync preference (DO backend)", () => {
@@ -214,9 +233,9 @@ describe("transactionAsync", () => {
     expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
   });
 
-  it("preserves the callback error even when ROLLBACK also fails", async () => {
+  it("preserves the callback error when ROLLBACK fails for the expected 'already-resolved' reason", async () => {
     const callbackErr = new Error("callback boom");
-    const rollbackErr = new Error("rollback boom");
+    const rollbackErr = new Error("cannot rollback - no transaction is active");
     const { db } = fakeDb({ rollbackThrows: rollbackErr });
     let thrown: unknown;
     try {
@@ -226,4 +245,81 @@ describe("transactionAsync", () => {
     }
     expect(thrown).toBe(callbackErr);
   });
+
+  it("re-throws an UNEXPECTED ROLLBACK failure instead of silently masking it (vault#589 NIT 2)", async () => {
+    const callbackErr = new Error("callback boom");
+    const rollbackErr = new Error("database disk image is malformed");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      await transactionAsync(db, async () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(rollbackErr);
+  });
+});
+
+describe("transaction — re-entrancy via SAVEPOINTs (vault#589)", () => {
+  it("a nested sync transaction uses SAVEPOINT/RELEASE, not a second BEGIN", () => {
+    const { db, calls } = fakeDb();
+    const out = transaction(db, () => {
+      const inner = transaction(db, () => "inner");
+      expect(inner).toBe("inner");
+      return "outer";
+    });
+    expect(out).toBe("outer");
+    expect(calls).toEqual([
+      "BEGIN IMMEDIATE",
+      "SAVEPOINT parachute_sp_1",
+      "RELEASE parachute_sp_1",
+      "COMMIT",
+    ]);
+  });
+
+  it("an inner throw rolls back to the savepoint; the outer can still commit", () => {
+    const db = freshDb();
+    transaction(db, () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'keep')");
+      try {
+        transaction(db, () => {
+          db.exec("INSERT INTO t (id, v) VALUES (2, 'drop')");
+          throw new Error("inner boom");
+        });
+      } catch {
+        // Outer decides to continue past the failed nested block.
+      }
+      db.exec("INSERT INTO t (id, v) VALUES (3, 'keep2')");
+    });
+    // Only the savepoint'd insert (2) was undone; 1 and 3 committed.
+    const ids = (db.prepare("SELECT id FROM t ORDER BY id").all() as { id: number }[]).map((r) => r.id);
+    expect(ids).toEqual([1, 3]);
+  });
+
+  it("an UNCAUGHT inner throw rolls back the WHOLE outer transaction", () => {
+    const db = freshDb();
+    expect(() =>
+      transaction(db, () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        transaction(db, () => {
+          db.exec("INSERT INTO t (id, v) VALUES (2, 'b')");
+          throw new Error("boom");
+        });
+      }),
+    ).toThrow("boom");
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+  });
+
+  it("transactionAsync composes a nested sync transaction via SAVEPOINT (the atomic blow-away shape)", async () => {
+    const { db, calls } = fakeDb();
+    await transactionAsync(db, async () => {
+      transaction(db, () => "nested-sync-write");
+    });
+    expect(calls).toEqual([
+      "BEGIN IMMEDIATE",
+      "SAVEPOINT parachute_sp_1",
+      "RELEASE parachute_sp_1",
+      "COMMIT",
+    ]);
+  });
 });

package/core/src/txn.ts

@@ -14,12 +14,40 @@
  * one of them only ever wrote, so acquiring the write lock eagerly is a
  * strict improvement (no lazy busy-upgrade) and never a semantic change.
  *
- * **Nesting is unsupported**, matching the pre-seam code exactly: SQLite
- * throws "cannot start a transaction within a transaction" on a nested
- * `BEGIN`, and none of the migrated call sites nest (a batch wraps individual
- * `createNote`s, none of which open their own transaction). If a nested
- * caller ever appears, the fix is SAVEPOINT-based re-entrancy *in the bun
- * implementation here* — the call sites stay untouched.
+ * **Nesting via SAVEPOINTs** (vault#589): the outermost `transaction` /
+ * `transactionAsync` on a connection opens a real `BEGIN IMMEDIATE`; a nested
+ * call (one whose connection is already inside a transaction) opens a
+ * `SAVEPOINT` instead, so composing an atomic block out of primitives that
+ * each open their own transaction never hits SQLite's "cannot start a
+ * transaction within a transaction". This is the re-entrancy the original
+ * seam anticipated ("the fix is SAVEPOINT-based re-entrancy in the bun
+ * implementation here — the call sites stay untouched"). The nesting depth is
+ * tracked per connection in {@link txnDepth}; a non-nested caller (depth 0 →
+ * 1) is byte-for-byte the old `BEGIN … COMMIT` / `ROLLBACK` path, so existing
+ * single-level callers are unaffected. The motivating nested caller is the
+ * atomic blow-away import (`importVault` wrapping schema/note/link writes,
+ * several of which open their own `transaction`).
+ *
+ * The `transactionSync` (Durable-Object) delegate path is unchanged — a DO
+ * backend supplies its own natively re-entrant primitive, so the SAVEPOINT
+ * bookkeeping here only governs the bun `BEGIN` path.
+ *
+ * **Shared-connection invariant (load-bearing for {@link transactionAsync}).**
+ * The bun backend is a single synchronous connection. A `transactionAsync`
+ * body — AND anything it calls — must not `await` genuine, slow I/O while the
+ * transaction is open: every `await` yields the event loop, and any work that
+ * runs during that yield and touches the store (a concurrent request, a
+ * mutation hook that writes before its first real await) will `SAVEPOINT`-JOIN
+ * this open transaction on the shared connection — committing/rolling back
+ * with it, its writes cross-wiped by a `ROLLBACK TO`. The blow-away import
+ * (the sole `transactionAsync` wrapping non-batch work) is safe by
+ * construction: its replay awaits only already-resolved promises over the
+ * synchronous bun store, so it never actually yields to unrelated work
+ * mid-transaction, and the mutation hooks it fires do no synchronous store
+ * writes (they defer via `queueMicrotask` and arm debounces / kick idempotent
+ * workers — see hooks.ts). Any NEW `transactionAsync` caller must preserve
+ * this: keep the body's awaits confined to the same synchronous connection,
+ * never awaiting network/disk/subprocess I/O with the transaction open.
  */
 
 /** The minimal DB surface the transaction seam needs — kept structural (no
@@ -38,6 +66,79 @@ export interface TxnCapableDb {
   transactionSync?<T>(fn: () => T): T;
 }
 
+/**
+ * Per-connection nesting depth for the bun `BEGIN` path. Keyed on the db
+ * handle so two connections track independently; a `WeakMap` so a dropped
+ * connection's entry is collected. Depth 0 = no open transaction; the first
+ * `transaction`/`transactionAsync` opens `BEGIN IMMEDIATE` and sets depth 1;
+ * each further nested call opens a `SAVEPOINT` and bumps the depth. See the
+ * file header (vault#589).
+ */
+const txnDepth = new WeakMap<TxnCapableDb, number>();
+
+/** One entry on the nesting stack: whether this frame owns the outer
+ *  `BEGIN … COMMIT`/`ROLLBACK` (outermost) or a `SAVEPOINT` (nested), plus the
+ *  depth to restore on exit. */
+interface TxnFrame {
+  outermost: boolean;
+  savepoint: string | null;
+  priorDepth: number;
+}
+
+/** Open a transaction frame: `BEGIN IMMEDIATE` at depth 0, else a uniquely
+ *  named `SAVEPOINT`. Bumps {@link txnDepth} only after the SQL succeeds. */
+function enterTxn(db: TxnCapableDb): TxnFrame {
+  const priorDepth = txnDepth.get(db) ?? 0;
+  if (priorDepth === 0) {
+    db.exec("BEGIN IMMEDIATE");
+    txnDepth.set(db, 1);
+    return { outermost: true, savepoint: null, priorDepth };
+  }
+  const savepoint = `parachute_sp_${priorDepth}`;
+  db.exec(`SAVEPOINT ${savepoint}`);
+  txnDepth.set(db, priorDepth + 1);
+  return { outermost: false, savepoint, priorDepth };
+}
+
+/** Commit a frame: `COMMIT` for the outermost, `RELEASE` for a savepoint
+ *  (which merges its writes into the enclosing transaction). */
+function commitTxn(db: TxnCapableDb, frame: TxnFrame): void {
+  if (frame.outermost) db.exec("COMMIT");
+  else db.exec(`RELEASE ${frame.savepoint}`);
+  txnDepth.set(db, frame.priorDepth);
+}
+
+/** Roll a frame back: `ROLLBACK` for the outermost (whole transaction),
+ *  `ROLLBACK TO` + `RELEASE` for a savepoint (unwind just this frame; the
+ *  error still propagates so an enclosing frame decides its own fate).
+ *  Best-effort — if the COMMIT itself threw, the transaction is already
+ *  resolved and these throw "no transaction"/"no such savepoint"; swallow so
+ *  the original error propagates. */
+function rollbackTxn(db: TxnCapableDb, frame: TxnFrame): void {
+  try {
+    if (frame.outermost) {
+      db.exec("ROLLBACK");
+    } else {
+      db.exec(`ROLLBACK TO ${frame.savepoint}`);
+      db.exec(`RELEASE ${frame.savepoint}`);
+    }
+  } catch (rollbackErr) {
+    // Only swallow the ONE expected case: the COMMIT/RELEASE itself already
+    // resolved the transaction, so there's nothing left to unwind — SQLite
+    // reports "cannot rollback - no transaction is active" / "no such
+    // savepoint". Any OTHER rollback failure is a real problem (a corrupt
+    // connection, a lost write lock) and must not be masked — re-throw it so
+    // the caller sees a failed rollback rather than a false success. Depth is
+    // restored first so the connection's bookkeeping stays consistent even on
+    // the re-throw path.
+    txnDepth.set(db, frame.priorDepth);
+    const msg = String((rollbackErr as Error)?.message ?? rollbackErr);
+    if (/no transaction is active|no such savepoint/i.test(msg)) return;
+    throw rollbackErr;
+  }
+  txnDepth.set(db, frame.priorDepth);
+}
+
 /**
  * Run `fn` inside a single write transaction, committing its result or
  * rolling back on throw. Synchronous — the callback must not await (see
@@ -55,20 +156,13 @@ export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
   if (typeof db.transactionSync === "function") {
     return db.transactionSync(fn);
   }
-  db.exec("BEGIN IMMEDIATE");
+  const frame = enterTxn(db);
   try {
     const result = fn();
-    db.exec("COMMIT");
+    commitTxn(db, frame);
     return result;
   } catch (err) {
-    // Best-effort rollback — if the COMMIT itself threw the transaction is
-    // already resolved and ROLLBACK would throw "no transaction is active";
-    // swallow that so the original error is the one that propagates.
-    try {
-      db.exec("ROLLBACK");
-    } catch {
-      // no active transaction to roll back
-    }
+    rollbackTxn(db, frame);
     throw err;
   }
 }
@@ -86,20 +180,21 @@ export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
  * so it cannot wrap an `async` body that awaits the Store facade between writes.
  * A DO backend that needs an atomic async batch has to reshape the batch as a
  * synchronous unit (or use an async DO transaction primitive) — out of scope
- * for this seam; the raw `BEGIN IMMEDIATE` path stays the single implementation.
+ * for this seam; the bun `BEGIN IMMEDIATE` path stays the single implementation.
+ *
+ * Re-entrant (vault#589): if the connection is already inside a transaction —
+ * e.g. the atomic blow-away import wraps this around store writes that
+ * themselves call {@link transaction} — a nested call opens a SAVEPOINT rather
+ * than a second `BEGIN`. See the file header.
  */
 export async function transactionAsync<T>(db: TxnCapableDb, fn: () => Promise<T>): Promise<T> {
-  db.exec("BEGIN IMMEDIATE");
+  const frame = enterTxn(db);
   try {
     const result = await fn();
-    db.exec("COMMIT");
+    commitTxn(db, frame);
     return result;
   } catch (err) {
-    try {
-      db.exec("ROLLBACK");
-    } catch {
-      // no active transaction to roll back
-    }
+    rollbackTxn(db, frame);
     throw err;
   }
 }

package/core/src/types.ts

@@ -118,6 +118,35 @@ export interface VaultStats {
   contentBytes: number;
 }
 
+// ---- Vault Map (front-door structural orientation) ----
+
+/** One counted bucket in a `VaultMap` — a tag name or a top-level path segment. */
+export interface VaultMapEntry {
+  name: string;
+  count: number;
+}
+
+/**
+ * Compact structural map of a vault: counts only, no content. Designed so a
+ * fresh reader (human or AI) orients in ONE `vault-info` call without also
+ * needing `include_stats: true` — see `getVaultMap` (core/src/notes.ts) for
+ * the SQL and the scope-aware `tagFilter` contract.
+ */
+export interface VaultMap {
+  /** Total notes in scope (all notes when unfiltered). */
+  total_notes: number;
+  /** Every tag currently carried by at least one in-scope note, with its membership count. Sorted by count desc, then name. */
+  tags: VaultMapEntry[];
+  /**
+   * Every top-level path segment (the text before the first `/`, or the
+   * whole path when it has none) among in-scope notes that HAVE a path, with
+   * its note count. Sorted by count desc, then name.
+   */
+  path_buckets: VaultMapEntry[];
+  /** In-scope notes with no `path` set — excluded from `path_buckets` (nothing to bucket). */
+  unfiled_notes: number;
+}
+
 // ---- Query Options ----
 
 export interface QueryOpts {
@@ -224,6 +253,54 @@ export interface QueryOpts {
    * treat the string as opaque.
    */
   cursor?: string;
+  /**
+   * Aggregation / rollup mode (top new-feature ask from a UX round). When
+   * present, `aggregateNotes` applies every OTHER filter on this `QueryOpts`
+   * (tags, metadata, date range, write-attribution, ids, ...) exactly as
+   * `queryNotes` would, then groups the matching notes and returns
+   * `[{group, value}]` instead of note rows. `cursor` / `orderBy` / `sort` /
+   * `limit` / `offset` are ignored in aggregate mode — a rollup returns one
+   * row per group, not a paginated note list.
+   */
+  aggregate?: AggregateSpec;
+}
+
+/**
+ * Aggregation / rollup spec — `QueryOpts.aggregate`. Mirrored by the
+ * `query-notes` MCP tool's `aggregate` param and the REST
+ * `?aggregate[group_by]=…&aggregate[op]=…&aggregate[field]=…` params.
+ */
+export interface AggregateSpec {
+  /**
+   * What to group by: an indexed metadata field name (declared
+   * `indexed: true` in a tag schema — same FIELD_NOT_INDEXED contract
+   * `metadata` operator queries and `order_by` use), or the special value
+   * `"tag"` to group by tag membership. Under `"tag"`, a note carrying N of
+   * the tags in the (filtered) result set contributes to N separate groups
+   * — this is a membership rollup, not a partition.
+   */
+  group_by: string;
+  /** `"count"` — number of matching notes per group. `"sum"` — sum of `field` per group. */
+  op: "count" | "sum";
+  /**
+   * Required when `op` is `"sum"`; ignored for `"count"`. Must be an
+   * indexed metadata field with SQLite storage type `INTEGER` (i.e. declared
+   * `type: "integer"` or `type: "boolean"` — the only indexable numeric
+   * shapes; a plain `type: "number"` field is never indexable, see
+   * `mapFieldType`, and a `TEXT`-backed field can't be summed).
+   */
+  field?: string;
+}
+
+/**
+ * One rollup row from `aggregateNotes`. `group` is the group_by value (the
+ * tag name under `group_by: "tag"`, or the indexed field's stored value) —
+ * `null` collects notes where the group_by field is absent/unset (SQL NULL
+ * groups together, standard GROUP BY behavior). `value` is the count/sum.
+ */
+export interface AggregateRow {
+  group: string | number | boolean | null;
+  value: number;
 }
 
 /**
@@ -346,6 +423,18 @@ export interface Store {
    * agent loop can persist a single watermark and keep polling.
    */
   queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage>;
+  /**
+   * Aggregation / rollup query. Applies every OTHER filter in `opts` (tags,
+   * metadata, date range, write-attribution, `ids`, ...) exactly as
+   * `queryNotes` would, then groups by `opts.aggregate.group_by` ("tag" or
+   * an indexed metadata field) and returns `[{group, value}]` — one row per
+   * group, count or sum per `opts.aggregate.op`. `cursor`/`orderBy`/`sort`/
+   * `limit`/`offset` on `opts` are ignored. Throws `QueryError` (code
+   * `FIELD_NOT_INDEXED`) when `group_by`/`field` isn't a declared indexed
+   * field, or `INVALID_QUERY` for a malformed `aggregate` spec (missing
+   * `field` on a `"sum"`, a non-numeric `field`, ...).
+   */
+  aggregateNotes(opts: QueryOpts): Promise<AggregateRow[]>;
   /**
    * `mode` (vault#551 — literal-by-default): "literal" (default) escapes +
    * phrase-quotes the query so FTS5 punctuation syntax (hyphen = NOT, an

package/core/src/ulid.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Unit tests for the ULID generator (vault#ulid-ids), pinned in isolation
+ * from the Store. Integration coverage (new notes get ULID ids, mixed
+ * old-format + ULID cursor pagination, old-format id round-trip) lives in
+ * core.test.ts under `describe("ULID ids for new notes ...")`.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { generateUlid, ULID_REGEX } from "./ulid.js";
+
+describe("generateUlid", () => {
+  it("produces a 26-character Crockford base32 string", () => {
+    const id = generateUlid();
+    expect(id).toHaveLength(26);
+    expect(id).toMatch(ULID_REGEX);
+  });
+
+  it("never emits the excluded Crockford letters (I, L, O, U)", () => {
+    for (let i = 0; i < 500; i++) {
+      const id = generateUlid();
+      expect(id).not.toMatch(/[ILOU]/);
+    }
+  });
+
+  it("the first 10 chars encode a timestamp close to Date.now()", () => {
+    const before = Date.now();
+    const id = generateUlid();
+    const after = Date.now();
+
+    const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    let time = 0;
+    for (const ch of id.slice(0, 10)) {
+      time = time * 32 + CROCKFORD.indexOf(ch);
+    }
+    expect(time).toBeGreaterThanOrEqual(before);
+    expect(time).toBeLessThanOrEqual(after);
+  });
+
+  it("is monotonically increasing under plain string compare, even across a tight loop", () => {
+    const ids = Array.from({ length: 1000 }, () => generateUlid());
+    for (let i = 1; i < ids.length; i++) {
+      expect(ids[i]! > ids[i - 1]!).toBe(true);
+    }
+  });
+
+  it("produces no duplicates across many calls", () => {
+    const ids = new Set(Array.from({ length: 5000 }, () => generateUlid()));
+    expect(ids.size).toBe(5000);
+  });
+
+  it("two IDs minted back-to-back share the same 10-char timestamp prefix (same ms) or the second sorts strictly after", () => {
+    const a = generateUlid();
+    const b = generateUlid();
+    expect(b > a).toBe(true);
+  });
+});

package/core/src/ulid.ts

@@ -0,0 +1,116 @@
+/**
+ * ULID generator (vault#ulid-ids) — monotonic, lexicographically
+ * time-sortable, Crockford base32, opaque, collision-resistant identifiers.
+ *
+ * Spec: https://github.com/ulid/spec
+ *
+ *   - 48-bit millisecond timestamp, encoded as the first 10 Crockford
+ *     base32 characters (most-significant digit first).
+ *   - 80-bit randomness, encoded as the remaining 16 characters.
+ *   - 26 characters total.
+ *
+ * Monotonicity: when two IDs are minted within the SAME millisecond, the
+ * random component of the second is the first's incremented by 1
+ * (odometer-style carry across base32 digits) rather than re-rolled, so
+ * lexicographic string order matches generation order even at IDgen rates
+ * far above 1kHz. This mirrors the reference `ulid` package's
+ * `monotonicFactory`.
+ *
+ * This is a small, dependency-light, hand-rolled implementation rather than
+ * a pull of the `ulid` npm package — the algorithm is short enough (~60
+ * lines) that inlining it avoids a new supply-chain dependency for what is,
+ * cryptographically, just "48 bits of time + 80 bits of randomness, base32
+ * encoded."
+ *
+ * Randomness source: `crypto.getRandomValues` (Web Crypto — available as a
+ * global in Bun), not `Math.random`. This module is runtime application
+ * code (invoked from note/attachment creation), not a workflow/sandbox
+ * script, so Web Crypto is available; it's also simply better randomness
+ * than `Math.random` for anything used as a public, collision-resistant
+ * identifier.
+ */
+
+const CROCKFORD_BASE32 = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const BASE = CROCKFORD_BASE32.length; // 32
+const TIME_LEN = 10; // 10 chars * 5 bits = 50 bits, enough for the 48-bit timestamp
+const RANDOM_LEN = 16; // 16 chars * 5 bits = 80 bits
+const TIME_MAX = 2 ** 48 - 1;
+
+/** Encode a non-negative integer as a fixed-length Crockford base32 string. */
+function encodeTime(time: number, length: number): string {
+  let t = time;
+  let str = "";
+  for (let i = length; i > 0; i--) {
+    const mod = t % BASE;
+    str = CROCKFORD_BASE32[mod]! + str;
+    t = (t - mod) / BASE;
+  }
+  return str;
+}
+
+/** Draw `length` cryptographically-random Crockford base32 characters. */
+function randomChars(length: number): string {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let str = "";
+  for (let i = 0; i < length; i++) {
+    // Each byte (0-255) mod 32 introduces a slight bias (256 isn't a
+    // multiple of 32... actually 256 = 8*32, so this is exactly uniform).
+    str += CROCKFORD_BASE32[bytes[i]! % BASE];
+  }
+  return str;
+}
+
+/**
+ * Increment a Crockford base32 string by 1, odometer-style: rightmost digit
+ * first, carrying leftward on overflow. Used to derive the next monotonic
+ * ID within the same millisecond.
+ *
+ * Throws if every digit is already the max ('Z') — i.e. the full 80-bit
+ * random space has been exhausted within a single millisecond. That would
+ * require minting 2^80 (~1.2e24) IDs in under a millisecond, several orders
+ * of magnitude beyond any realistic write rate; this is a defensive bound,
+ * not a real-world concern.
+ */
+function incrementBase32(str: string): string {
+  const chars = str.split("");
+  for (let i = chars.length - 1; i >= 0; i--) {
+    const idx = CROCKFORD_BASE32.indexOf(chars[i]!);
+    if (idx < BASE - 1) {
+      chars[i] = CROCKFORD_BASE32[idx + 1]!;
+      return chars.join("");
+    }
+    chars[i] = CROCKFORD_BASE32[0]!;
+  }
+  throw new Error("ULID random component overflow — 2^80 IDs minted within a single millisecond");
+}
+
+// Monotonic state, process-local (matches generateId()'s prior idCounter
+// approach — a single vault process is the unit of monotonicity; a cursor's
+// tiebreaker doesn't require cross-process ordering, just a stable total
+// order per id string).
+let lastTime = 0;
+let lastRandom = "";
+
+/**
+ * Generate a monotonic ULID. See module doc for the algorithm.
+ *
+ * Exported separately from `generateId()` (in notes.ts) so it's testable in
+ * isolation (monotonicity, format, charset) without pulling in the Store.
+ */
+export function generateUlid(): string {
+  const now = Math.min(Date.now(), TIME_MAX);
+  if (now <= lastTime && lastRandom) {
+    // Same (or earlier — clock skew) millisecond as the last mint: keep
+    // `lastTime` as-is and bump the random component to preserve strict
+    // monotonicity.
+    lastRandom = incrementBase32(lastRandom);
+  } else {
+    lastTime = now;
+    lastRandom = randomChars(RANDOM_LEN);
+  }
+  return encodeTime(lastTime, TIME_LEN) + lastRandom;
+}
+
+/** 26-char Crockford base32 (`0-9A-HJKMNP-TV-Z`, case-insensitive by spec — we always emit uppercase). */
+export const ULID_REGEX = /^[0-9A-HJKMNP-TV-Z]{26}$/;

package/core/src/vault-projection.ts

@@ -32,7 +32,7 @@ import {
 } from "./tag-schemas.ts";
 import { DEFAULT_TAG_NAME } from "./tag-hierarchy.ts";
 import * as noteOps from "./notes.ts";
-import type { VaultStats } from "./types.ts";
+import type { VaultStats, VaultMap } from "./types.ts";
 import { GETTING_STARTED_PATH } from "./seed-packs.ts";
 
 /**
@@ -103,6 +103,17 @@ export interface VaultProjection {
   getting_started?: string;
   /** Included when the caller requests stats; omitted otherwise. */
   stats?: VaultStats;
+  /**
+   * Compact structural map — total note count, tag counts, top-level
+   * path-bucket counts (front-door orientation). ALWAYS present (unlike
+   * `stats`): it's three cheap grouped-COUNT queries, so a fresh reader
+   * orients in one `vault-info` call without also passing
+   * `include_stats: true`. See `noteOps.getVaultMap`. Scope-aware callers
+   * (tag-scoped tokens) get a RECOMPUTED map from the server layer — see
+   * `applyTagScopeWrappers` in src/mcp-tools.ts — because path-bucket counts
+   * can't be reconstructed by post-hoc filtering an unscoped rollup.
+   */
+  map: VaultMap;
 }
 
 // ---------------------------------------------------------------------------
@@ -182,6 +193,12 @@ export const QUERY_HINTS: readonly string[] = [
  *   - `stats`: included when `opts.includeStats === true`. Uses the
  *     existing `getVaultStats` shape unchanged — camelCase keys, full
  *     monthly distribution.
+ *
+ *   - `map`: ALWAYS included (unlike `stats`) — `getVaultMap`'s cheap
+ *     total-notes / tag-counts / path-bucket-counts rollup, computed
+ *     vault-wide (unscoped). See the `VaultProjection.map` doc comment for
+ *     why a tag-scoped caller's map is recomputed one layer up rather than
+ *     filtered here.
  */
 export function buildVaultProjection(
   db: Database,
@@ -233,6 +250,7 @@ export function buildVaultProjection(
     tags,
     indexed_fields,
     query_hints: [...QUERY_HINTS],
+    map: noteOps.getVaultMap(db),
   };
 
   // A2: point any connected AI at the seeded onboarding guide (a path pointer,