@openparachute/vault 0.7.0-rc.8 → 0.7.1

package/core/src/store.ts

@@ -1,5 +1,5 @@
 import { Database } from "bun:sqlite";
-import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage } from "./types.js";
+import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage, AggregateRow } from "./types.js";
 import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
@@ -10,7 +10,12 @@ import {
   reconcileDeclaredIndexes,
   type PrunedField,
 } from "./indexed-fields.js";
-import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
+import {
+  syncWikilinks,
+  resolveUnresolvedWikilinks,
+  resolveOrQueueLink,
+  clearQueuedLink,
+} from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
 import { transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
@@ -27,6 +32,7 @@ import {
 import {
   loadSchemaConfig,
   validateNote as runValidateNote,
+  resolveNoteSchemas,
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
@@ -104,6 +110,94 @@ export class BunSqliteStore implements Store {
     return runValidateNote(this.getSchemaConfig(), note);
   }
 
+  /**
+   * Auto-link sync for `type: "reference"` schema fields
+   * (vault#typed-reference-field — see `docs/design/typed-reference-field.md`
+   * for the full design + known gaps).
+   *
+   * A `reference`-typed field is BOTH an indexed value (handled by the
+   * ordinary metadata write — no special casing needed there, see
+   * `tag-schemas.ts`'s `VALID_FIELD_TYPES`) AND a graph link. This method
+   * maintains the second half: for every field the note's EFFECTIVE schema
+   * (its own tags + ancestors, same resolution `validateNoteAgainstSchemas`
+   * uses) declares `type: "reference"`, resolve the field's current metadata
+   * value to a note (reusing the SAME `resolveOrQueueLink` machinery
+   * structured `links` entries use — id, then path/title, with lazy
+   * forward-ref queueing on a miss) and maintain a `links` edge from this
+   * note to that target, `relationship` = the field name.
+   *
+   * Called from `createNote`/`updateNote`/`createNotes` — the single
+   * chokepoint both MCP and REST funnel through — AFTER the note row itself
+   * is written, so `note.tags`/`note.metadata` reflect the final state.
+   *
+   * `priorMetadata` is the note's metadata BEFORE this write (`undefined` on
+   * create). For each reference field, if its value is unchanged from
+   * `priorMetadata`, nothing is touched — the existing link (if any) already
+   * reflects it, and re-running the resolve/queue machinery on every
+   * unrelated write (e.g. a content-only edit) would be wasted work. When
+   * the value DID change (set, changed, or removed), every existing link +
+   * queued forward-ref under that field's relationship name is cleared
+   * first, then re-established from the new value — this makes the field's
+   * current value the single source of truth for "this field's link"
+   * without needing to track the specific prior target.
+   *
+   * Known gaps (see the design doc): only scalar (`cardinality: "one"`,
+   * the default) reference values are linked — an array value is left as a
+   * validated-like-string-per-item... actually an array value simply isn't
+   * a string, so no link is created for it (the write still succeeds; a
+   * `type_mismatch`/`cardinality_mismatch` warning surfaces via the normal
+   * `validation_status` path). A tag gaining a `reference` field declaration
+   * does NOT retroactively link notes that already carry a matching value —
+   * only writes that actually touch the field (going forward) sync.
+   */
+  private syncReferenceFieldLinks(
+    note: Note,
+    priorMetadata: Record<string, unknown> | undefined,
+  ): void {
+    const resolution = resolveNoteSchemas(this.getSchemaConfig(), { tags: note.tags ?? [] });
+    if (resolution.mergedFields.size === 0) return;
+
+    const metadata = note.metadata ?? {};
+    const prior = priorMetadata ?? {};
+
+    for (const [fieldName, { spec }] of resolution.mergedFields) {
+      if (spec.type !== "reference") continue;
+
+      const nextValue = metadata[fieldName];
+      const priorValue = prior[fieldName];
+      if (nextValue === priorValue) continue; // unchanged — link (if any) already reflects it
+
+      // Re-establish this field's link from scratch: drop whatever it
+      // previously pointed at (a resolved link, and/or a queued forward-ref)
+      // before applying the new value. See this method's doc comment for why
+      // "clear then recreate" is safe and simpler than tracking the prior
+      // resolved target.
+      linkOps.deleteLinksBySourceRelationship(this.db, note.id, fieldName);
+      clearQueuedLink(this.db, note.id, fieldName);
+
+      if (typeof nextValue === "string" && nextValue.trim() !== "") {
+        // Resolves now, or queues a lazy forward-ref on a miss — same
+        // contract as a structured `links` entry (core/src/mcp.ts,
+        // src/routes.ts). A queued forward-ref backfills automatically via
+        // `resolveUnresolvedWikilinks` the moment a matching note is
+        // created, and surfaces to callers today via the existing
+        // `has_broken_links`/`broken_links` query-notes filters (both read
+        // the same `unresolved_wikilinks` table this queues into) — see the
+        // design doc for the follow-up to also surface an inline
+        // `unresolved_link`/`ambiguous_link` warning on the create/update
+        // response itself. An `"ambiguous"` outcome (vault#570 — the field's
+        // value matched ≥2 notes, e.g. two notes sharing an H1 title) is
+        // treated the same as a miss here: no link is created, and nothing
+        // is queued (mirrors `resolveOrQueueLink`'s own "don't guess"
+        // contract for structured links).
+        const outcome = resolveOrQueueLink(this.db, note.id, nextValue, fieldName);
+        if (outcome.status === "resolved") {
+          linkOps.createLink(this.db, note.id, outcome.note_id, fieldName);
+        }
+      }
+    }
+  }
+
   /**
    * Drop the tag-hierarchy cache if the mutated path is in the `_tags/*`
    * namespace. Called from create/update/delete — old path is passed
@@ -135,6 +229,11 @@ export class BunSqliteStore implements Store {
       resolveUnresolvedWikilinks(this.db, note.path, note.id);
     }
 
+    // Reference-field auto-link (vault#typed-reference-field) — no prior
+    // metadata on a fresh create. Cheap no-op when nothing on the note's
+    // effective schema declares `type: "reference"`.
+    this.syncReferenceFieldLinks(note, undefined);
+
     this.invalidateConfigCachesForPath(note.path);
     this.hooks.dispatch("created", note, this);
 
@@ -171,9 +270,17 @@ export class BunSqliteStore implements Store {
     },
   ): Promise<Note> {
     let oldPath: string | undefined;
-    if (updates.path !== undefined) {
+    // Reference-field auto-link sync (vault#typed-reference-field) needs the
+    // PRE-write metadata to detect which reference fields actually changed —
+    // read it now, before `noteOps.updateNote` overwrites the row. Only
+    // needed when this call touches `metadata` at all (a content/tags/path-
+    // only update can't have changed a reference field's value, so this read
+    // is skipped on the common non-metadata-touching path).
+    let priorMetadataForRefs: Record<string, unknown> | undefined;
+    if (updates.path !== undefined || updates.metadata !== undefined) {
       const existing = noteOps.getNote(this.db, id);
-      oldPath = existing?.path;
+      if (updates.path !== undefined) oldPath = existing?.path;
+      if (updates.metadata !== undefined) priorMetadataForRefs = existing?.metadata;
     }
 
     const note = noteOps.updateNote(this.db, id, updates);
@@ -192,6 +299,13 @@ export class BunSqliteStore implements Store {
       resolveUnresolvedWikilinks(this.db, note.path, id);
     }
 
+    // Reference-field auto-link sync (vault#typed-reference-field). Only
+    // when this call actually touched `metadata` — see the read above for
+    // why a content/tags/path-only update is skipped.
+    if (updates.metadata !== undefined) {
+      this.syncReferenceFieldLinks(note, priorMetadataForRefs);
+    }
+
     // Invalidate before the hook dispatch so any handler that re-queries
     // the hierarchy from inside its own logic sees post-write state.
     // `metadata` updates can change the `parents` field on a config note
@@ -311,6 +425,13 @@ export class BunSqliteStore implements Store {
     return noteOps.queryNotesPaged(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
   }
 
+  async aggregateNotes(opts: QueryOpts): Promise<AggregateRow[]> {
+    // Same bare-tag normalization + hierarchy expansion `queryNotes` gets —
+    // `opts.tags`/`excludeTags` filter the aggregate's input set the same
+    // way they'd filter a normal query's result list.
+    return noteOps.aggregateNotes(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
+  }
+
   /**
    * If `tags` are present, attach a parallel `_tagsExpanded` array where
    * each input tag is replaced with `{tag} ∪ descendants(tag)`. The SQL
@@ -554,6 +675,9 @@ export class BunSqliteStore implements Store {
       // would leave the hierarchy cache stale until the next singleton
       // write happened to bust it.
       this.invalidateConfigCachesForPath(note.path);
+      // Same reference-field auto-link sync as singleton createNote
+      // (vault#typed-reference-field) — no prior metadata on a fresh create.
+      this.syncReferenceFieldLinks(note, undefined);
       this.hooks.dispatch("created", note, this);
     }
     return notes;
@@ -735,7 +859,7 @@ export class BunSqliteStore implements Store {
         const mapped = indexedFieldOps.mapFieldType(spec.type);
         if (!mapped) {
           throw new indexedFieldOps.IndexedFieldError(
-            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+            `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
           );
         }
         // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).

package/core/src/tag-schemas.ts

@@ -255,15 +255,23 @@ export function validateFieldDefault(field: string, spec: TagFieldSchema): TagFi
 
 /**
  * The full recognized vocabulary for `TagFieldSchema.type` — storage/
- * advisory validation accepts all six; only `string`/`integer`/`boolean`
- * are INDEXABLE (that narrower subset is `indexed-fields.ts`'s `TYPE_MAP`,
- * enforced separately via `mapFieldType` for `indexed: true` fields).
- * Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
+ * advisory validation accepts all seven; only `string`/`integer`/`boolean`/
+ * `reference` are INDEXABLE (that narrower subset is `indexed-fields.ts`'s
+ * `TYPE_MAP`, enforced separately via `mapFieldType` for `indexed: true`
+ * fields). Matches `defaultMatchesType`'s switch and `schema-defaults.ts`'s
  * `SchemaField.type` union — kept in lockstep by hand across the two
  * deliberately-decoupled modules (see `validateFieldDefault`'s doc comment
  * for why they don't cross-import).
+ *
+ * `reference` (vault#typed-reference-field) is a dual-write field type: the
+ * value is stored + validated exactly like `string` (an id/path/title the
+ * caller passes), AND the write path (`core/src/store.ts` — see
+ * `BunSqliteStore.syncReferenceFieldLinks`) additionally resolves that value
+ * to a note and maintains a graph `links` edge from this note to the
+ * resolved target, with `relationship` set to the field name. See
+ * `docs/design/typed-reference-field.md` for the full design + known gaps.
  */
-export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object"] as const;
+export const VALID_FIELD_TYPES = ["string", "number", "integer", "boolean", "array", "object", "reference"] as const;
 
 /**
  * Validate that a field's declared `type` is one of the six recognized
@@ -320,7 +328,7 @@ export function collectOwnFieldDefaultAndTypeViolations(
   return violations;
 }
 
-/** Same six-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
+/** Same seven-type vocabulary as `TagFieldSchema.type`'s doc comment. Unknown/unset types pass (nothing to check against). */
 function defaultMatchesType(value: unknown, type: string): boolean {
   switch (type) {
     case "string":
@@ -335,6 +343,11 @@ function defaultMatchesType(value: unknown, type: string): boolean {
       return Array.isArray(value);
     case "object":
       return !!value && typeof value === "object" && !Array.isArray(value);
+    // `reference` stores/validates like `string` — the value is the
+    // id/path/title the write path resolves to a target note. See
+    // VALID_FIELD_TYPES's doc comment.
+    case "reference":
+      return typeof value === "string";
     default:
       return true;
   }
@@ -754,7 +767,7 @@ export function collectTagFieldViolations(
         violations.push({
           field: fieldName,
           reason: "unsupported_indexed_type",
-          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
+          message: `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean, reference)`,
         });
       } else {
         try {

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 {
@@ -141,6 +170,15 @@ export interface QueryOpts {
   // `hasLinks` checks both directions — inbound or outbound counts as "has links".
   hasTags?: boolean;
   hasLinks?: boolean;
+  /**
+   * Presence filter on the `unresolved_wikilinks` table (vault#555):
+   * `true` → only notes with at least one dangling outbound link (a
+   * `[[wikilink]]` or structured `links` target that never resolved to a
+   * note); `false` → only notes with none. Safe on a vault where the
+   * `unresolved_wikilinks` table has never been created (no note has ever
+   * had a broken link) — `true` matches nothing, `false` is a no-op.
+   */
+  hasBrokenLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
   /**
@@ -215,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;
 }
 
 /**
@@ -337,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,