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

package/core/src/schema.ts

@@ -3,8 +3,19 @@ import { normalizePath } from "./paths.js";
 import { rebuildIndexes, listIndexedFields } from "./indexed-fields.js";
 import { findMixedTypeIndexedFieldNotes } from "./doctor.js";
 import { transaction } from "./txn.js";
+import { timestampToMs } from "./cursor.js";
 
-export const SCHEMA_VERSION = 25;
+export const SCHEMA_VERSION = 26;
+
+/**
+ * Deterministic last-resort epoch for a note whose `updated_at` AND
+ * `created_at` are both unparseable (vault#586). 0 (the Unix epoch) sorts such
+ * a row to the very start of the keyset walk — honest "oldest / unknown"
+ * placement — and, being a fixed constant, keeps the backfill idempotent (a
+ * re-run derives the identical value). NEVER null: a NULL `updated_at_ms`
+ * would sort unpredictably and break the `> ?` keyset predicate.
+ */
+const UNPARSEABLE_UPDATED_AT_MS = 0;
 
 export const SCHEMA_SQL = `
 -- Notes: the universal record.
@@ -26,6 +37,13 @@ export const SCHEMA_SQL = `
 -- (mcp, surface:NAME, agent:ID, operator/cli, api). Legacy rows stay NULL —
 -- we don't fabricate authors for writes that predate attribution. See
 -- migrateToV23.
+-- updated_at_ms (v26, vault#586) is the integer millisecond-epoch mirror of
+-- updated_at, and the SINGLE source of truth for cursor keyset ordering. The
+-- keyset walk-order, boundary predicate, and watermark all read this one
+-- numeric column, so they can't diverge the way three separate readings of the
+-- TEXT updated_at did on aged/imported vaults with non-canonical timestamps.
+-- Maintained on every write (createNote / updateNote / restore / cascades) via
+-- core/src/cursor.ts timestampToMs; existing rows backfilled by migrateToV26.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
@@ -37,7 +55,8 @@ CREATE TABLE IF NOT EXISTS notes (
   created_by TEXT,
   created_via TEXT,
   last_updated_by TEXT,
-  last_updated_via TEXT
+  last_updated_via TEXT,
+  updated_at_ms INTEGER
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -529,6 +548,12 @@ export function initSchema(db: Database): void {
   // porter stemming, repopulate from every existing note. See vault#551.
   migrateToV25(db);
 
+  // Migrate v25 → v26: add the integer `notes.updated_at_ms` column — the
+  // single source of truth for cursor keyset ordering — plus its
+  // (updated_at_ms, id) index, and backfill every existing row from its
+  // `updated_at` string with a UTC-correct parse. See vault#586.
+  migrateToV26(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1491,6 +1516,107 @@ function migrateToV25(db: Database): void {
   );
 }
 
+/**
+ * Migrate v25 → v26: integer `notes.updated_at_ms` as the single source of
+ * truth for cursor keyset ordering (vault#586).
+ *
+ * THE BUG this closes: the `(updated_at, id)` cursor keyset used THREE
+ * inconsistent orderings of `updated_at` that agree only when every timestamp
+ * is canonical `.toISOString()` output — TEXT-lexicographic walk order, a
+ * canonical-ISO boundary string compared as TEXT, and a `Date.parse`-derived
+ * millis watermark that read space-form timestamps in LOCAL time. Import
+ * stores frontmatter timestamps VERBATIM, so aged/imported vaults carry
+ * non-canonical `updated_at` (`2024-11-02 14:30:00` space-form, `+02:00`
+ * offset, no-`Z`) — under which the three orderings diverge and cursor
+ * pagination silently skipped notes, re-delivered rows in a loop, or 400'd the
+ * whole walk. A single integer column makes walk-order, keyset boundary, and
+ * watermark ONE numeric ordering.
+ *
+ * Backfill parse (`timestampToMs`) is UTC-correct — it does NOT use
+ * `Date.parse` for zone-less forms (the live bug was space-form read as LOCAL
+ * time). A genuinely unparseable `updated_at` falls back to the row's
+ * `created_at` ms, then to a stable sentinel ({@link UNPARSEABLE_UPDATED_AT_MS})
+ * — never NULL, never a throw.
+ *
+ * ALL-OR-NOTHING (matches the #565 migrateToV25 pattern): the ALTER + backfill
+ * run inside a SINGLE `transaction`. If the ALTER committed but the backfill
+ * then crashed, a column-presence-only guard would see the column on the next
+ * boot and skip — leaving rows with NULL `updated_at_ms` and a permanently
+ * broken keyset. Wrapping the whole sequence means a rollback removes the
+ * column too, so the next boot re-detects "not migrated" and re-runs cleanly.
+ * The index create lives OUTSIDE the wrapped block (`CREATE INDEX IF NOT
+ * EXISTS`) so a fresh vault — column already present from SCHEMA_SQL — still
+ * gets the index.
+ *
+ * SELF-HEALING (generalist review nit 1): the backfill is NOT gated on column
+ * absence — it runs whenever ANY row has a NULL `updated_at_ms`, via a single
+ * `WHERE updated_at_ms IS NULL` pass that serves BOTH the fresh-ALTER case
+ * (every row NULL right after ADD COLUMN) AND the leak case (a row that slipped
+ * in with NULL while the column already existed). The leak is real: a
+ * schema-v2-era vault upgrades through `migrateFromV2`, whose
+ * `INSERT INTO notes … SELECT` omits `updated_at_ms`, landing rows with NULL
+ * even though SCHEMA_SQL created the column — a column-presence guard would
+ * skip them forever (the exact keyset-invisibility class this migration
+ * closes). Steady state (column present, zero NULLs) does a single cheap
+ * COUNT and no writes.
+ */
+function migrateToV26(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+
+  const needsColumn = !hasColumn(db, "notes", "updated_at_ms");
+  // Backfill runs when the column is being added OR when any existing row
+  // carries a NULL keyset key (self-heal). A steady-state boot short-circuits
+  // here on the cheap COUNT and touches nothing.
+  let pending = needsColumn;
+  if (!needsColumn) {
+    const nulls = (
+      db.prepare("SELECT COUNT(*) AS n FROM notes WHERE updated_at_ms IS NULL").get() as { n: number }
+    ).n;
+    pending = nulls > 0;
+  }
+
+  if (pending) {
+    let backfilled = 0;
+    let fellBack = 0;
+    transaction(db, () => {
+      if (needsColumn) {
+        db.exec("ALTER TABLE notes ADD COLUMN updated_at_ms INTEGER");
+      }
+      // One `WHERE updated_at_ms IS NULL` pass covers both cases: right after
+      // ALTER every row is NULL; on a self-heal only the leaked rows are.
+      const rows = db.prepare(
+        "SELECT id, created_at, updated_at FROM notes WHERE updated_at_ms IS NULL",
+      ).all() as { id: string; created_at: string | null; updated_at: string | null }[];
+      const update = db.prepare("UPDATE notes SET updated_at_ms = ? WHERE id = ?");
+      for (const row of rows) {
+        // `updated_at` is the ordering authority; fall back to `created_at`
+        // (legacy rows can carry NULL updated_at), then the stable sentinel.
+        let ms = timestampToMs(row.updated_at);
+        if (ms === null) {
+          ms = timestampToMs(row.created_at);
+          fellBack++;
+        }
+        if (ms === null) ms = UNPARSEABLE_UPDATED_AT_MS;
+        update.run(ms, row.id);
+        backfilled++;
+      }
+    });
+    if (backfilled > 0) {
+      console.log(
+        `[vault] migrated to schema v26 (vault#586): backfilled updated_at_ms for ${backfilled} note(s)` +
+          (needsColumn ? "" : " (self-heal — NULL keyset keys on an existing column)") +
+          (fellBack > 0 ? ` (${fellBack} fell back to created_at / sentinel for an unparseable updated_at)` : "") +
+          `.`,
+      );
+    }
+  }
+
+  // Index lives outside the ALTER transaction (idx_tokens_vault_name /
+  // idx_notes_updated precedent): a fresh vault has the column from SCHEMA_SQL
+  // but not yet the index, so this ensures it for both paths. Idempotent.
+  db.exec("CREATE INDEX IF NOT EXISTS idx_notes_updated_ms ON notes(updated_at_ms, id)");
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/seed-packs.ts

@@ -50,7 +50,7 @@ import type { Store, TagFieldSchema } from "./types.ts";
  * here — a description is vault metadata, not a pack note.
  */
 export const DEFAULT_VAULT_DESCRIPTION =
-  'This is a brand-new personal vault — just its starter guides so far; the person it belongs to is probably new to Parachute. Before helping them set it up, read the "Getting Started" note — it\'s your onboarding brief. Short version: start with a conversation, not a filing system; learn how they want to use this and where their notes live today; do one small real thing first. When the vault has real structure, replace this description (vault-info { description: "..." }) with a current picture of what lives here and how to work it — so every future session, yours or another AI\'s, starts oriented.';
+  'This is a brand-new personal vault — just its starter guides so far; the person it belongs to is probably new to Parachute. Before helping them set it up, read the "Getting Started" note — it\'s your onboarding brief. Short version: start with a conversation, not a filing system; learn how they want to use this and where their notes live today; do one small real thing first. When the vault has real structure, replace this description (vault-info { description: "..." } — an admin-scope action) with a current picture of what lives here and how to work it — so every future session, yours or another AI\'s, starts oriented.';
 
 /**
  * The `vault-info` description a vault gets when it was **imported/restored** —
@@ -59,7 +59,7 @@ export const DEFAULT_VAULT_DESCRIPTION =
  * text with a current picture.
  */
 export const IMPORTED_VAULT_DESCRIPTION =
-  'This vault was imported — it arrived with its own notes, tags, and history. Orient before you write: vault-info { include_stats: true }, list-tags, read a sample, and read "Getting Started" if present. Your first job is to learn the shape that\'s already here and reflect it back to the person — not to propose new structure cold. When you understand it, replace this description (vault-info { description: "..." }) with a current picture.';
+  'This vault was imported — it arrived with its own notes, tags, and history. Orient before you write: vault-info { include_stats: true }, list-tags, read a sample, and read "Getting Started" if present. Your first job is to learn the shape that\'s already here and reflect it back to the person — not to propose new structure cold. When you understand it, replace this description (vault-info { description: "..." } — an admin-scope action) with a current picture.';
 
 // ---------------------------------------------------------------------------
 // Pack shape
@@ -392,16 +392,20 @@ description) so the next one picks up where you left off.
 ### If this vault already has content
 
 Some vaults arrive full — an import, a restore, months of use. Then your first
-job is to **learn it, not seed it**: \`vault-info { include_stats: true }\`,
-\`list-tags\`, read a sample (\`query-notes { search: "..." }\`), then reflect the
-shape back to the person and ask what's missing or wrong. Propose structure
-only once you can describe what's already there.
+job is to **learn it, not seed it**: \`vault-info\` — a single call now returns
+a compact \`map\` (every tag's note count, every top-level path's note count,
+total notes) alongside the schema catalog, so you get the shape of a strange
+vault in one round trip; add \`include_stats: true\` only if you also want the
+deeper monthly distribution. Then \`list-tags\` and read a sample
+(\`query-notes { search: "..." }\`), and reflect the shape back to the person
+and ask what's missing or wrong. Propose structure only once you can describe
+what's already there.
 
 ### Close the loop: describe the vault
 
 When the first real structure lands, update the vault description —
-\`vault-info { description: "..." }\` — so every future session (yours or another
-AI's) starts oriented: what this vault is for, its main tags, its conventions.
+\`vault-info { description: "..." }\`, an \`admin\`-scope action — so every future
+session (yours or another AI's) starts oriented: what this vault is for, its main tags, its conventions.
 The default description says "brand-new vault"; once that stops being true,
 replace it. Keep it a few sentences (the projection carries the schema detail,
 and this note carries the richer conventions — see "Adapt this note"). Bringing
@@ -419,16 +423,44 @@ small welcome web and the \`capture\` tag the Notes surface uses; no other
 predefined tags or schema. You and the operator design the structure that fits
 *their* life and work. The vault is the engine; the meaning is yours to bring.
 
-Core moves you already have as MCP tools:
-- \`create-note\` / \`update-note\` / \`delete-note\` — write notes (single or batch).
-- \`query-notes\` — by id/path, by tag, full-text \`search\`, or graph \`near\` a note.
-- \`list-tags\` / \`update-tag\` / \`delete-tag\` — manage the tag vocabulary + schemas.
-- \`find-path\` — shortest link path between two notes.
-- \`vault-info\` — refresh the live schema/stats projection any time.
+Core moves, grouped by the scope each needs — \`tools/list\` shows exactly the
+ones your token can call (see "What your scope allows" below):
+- **Read:** \`query-notes\` (by id/path, by tag, full-text \`search\`, or graph
+  \`near\` a note), \`list-tags\`, \`find-path\` (shortest link path between two
+  notes), \`vault-info\` (the live schema projection + a compact \`map\` — tag
+  counts, top-level path-bucket counts, total notes — so you orient in one
+  call), \`doctor\` (read-only integrity scan).
+- **Write:** \`create-note\` / \`update-note\` / \`delete-note\` — author notes,
+  single or batch.
+- **Admin:** \`update-tag\` / \`delete-tag\` / \`rename-tag\` / \`merge-tags\` /
+  \`prune-schema\` (the tag vocabulary + schemas), \`vault-info { description }\`
+  (the vault's own description), \`manage-token\` (mint scoped child tokens).
 
 \`[[wikilinks]]\` in note content auto-link to the note at that path — use them
 freely; they resolve even if the target is created later.
 
+## What your scope allows
+
+Your connection carries one of three scopes, and it shapes what you can do here
+— by design, so the person can grant exactly as much authority as they mean to:
+
+- **\`read\`** — explore and answer: query notes, read tags, traverse the graph,
+  run \`doctor\`. You can't change anything.
+- **\`write\`** — everything read can do, plus author content: create, update,
+  and delete notes. You can capture and edit freely, but you *can't* reshape the
+  vault's structure — renaming/merging/deleting tags, editing schemas, and
+  rewriting the vault description all need admin.
+- **\`admin\`** — everything, including that restructuring, plus minting scoped
+  child tokens.
+
+If a tool this guide mentions fails with "Unknown tool" — or a normally-visible
+tool refuses one argument with "Forbidden" (e.g. \`vault-info { description }\`
+for a non-admin) — that's your scope, not a bug: the action sits above your
+tier. Don't fight it: tell the person plainly
+what you'd do with more access ("I can add notes, but reorganizing your tags
+needs admin — want to grant it?") and let them decide. Most people connect with
+admin, so usually you'll have the whole set.
+
 ## Tags vs paths vs schemas — the design vocabulary
 
 These three axes are the heart of vault design. Use the right one for the job:
@@ -447,7 +479,7 @@ These three axes are the heart of vault design. Use the right one for the job:
   path, tags, or both.
 
 - **Schemas = typed metadata fields.** Attach a schema to a tag (via
-  \`update-tag\`) to declare typed metadata fields — e.g. \`#meeting\` with a
+  \`update-tag\`, an \`admin\`-scope move) to declare typed metadata fields — e.g. \`#meeting\` with a
   \`held_on\` date, \`#person\` with an \`email\`. Each field can **optionally** be
   marked \`indexed: true\` to make it **queryable with operators** (\`query-notes
   { tag: "meeting", metadata: { held_on: { gte: "2026-01-01" } } }\`); indexing
@@ -503,6 +535,14 @@ Testers of this vault independently reinvented these — start from them instead
   text is escaped, not parsed as FTS5 syntax, so punctuation like "didn't" or
   "18.6" just works. Pass \`search_mode: "advanced"\` only when you actually
   want FTS5 boolean/phrase/prefix syntax.
+- **A front-door "Map" note.** Once a vault grows past a few dozen notes,
+  keep one note (path \`Map\`, or whatever fits) as a human-legible index —
+  the tags and top-level paths that matter and what each means, with
+  wikilinks into anchor notes. It's the "why" companion to \`vault-info\`'s
+  auto-computed \`map\` (tag/path-bucket counts, the "what's there"): the
+  counts tell a fresh AI the shape of the vault in one call, this note tells
+  it what that shape MEANS. Update it when the vault's structure shifts;
+  link to it from the vault description so it's easy to find.
 
 ## Write gotchas
 

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,8 +10,14 @@ 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 { timestampToMs } from "./cursor.js";
 import { transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
 import {
@@ -27,6 +33,7 @@ import {
 import {
   loadSchemaConfig,
   validateNote as runValidateNote,
+  resolveNoteSchemas,
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
@@ -104,6 +111,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 +230,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 +271,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 +300,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
@@ -246,9 +361,18 @@ export class BunSqliteStore implements Store {
     // the importer write a specific historical timestamp. Skips hooks
     // by design: this isn't a user-edit, it's a state restoration.
     // See vault#308 PR 2.
+    //
+    // This is THE path by which non-canonical timestamps (space-form,
+    // `+02:00` offset, no-`Z`) land in a vault — frontmatter is preserved
+    // VERBATIM (byte-identical re-export round-trip), so `updated_at` is NOT
+    // canonicalized here. The keyset ordering key `updated_at_ms` (vault#586)
+    // is derived UTC-correctly from that verbatim value: `timestampToMs` does
+    // NOT read space-form as local time. A genuinely unparseable `updated_at`
+    // falls back to `created_at`'s ms, then to 0 — never NULL, never a throw.
+    const updatedAtMs = timestampToMs(updatedAt) ?? timestampToMs(createdAt) ?? 0;
     this.db
-      .prepare("UPDATE notes SET created_at = ?, updated_at = ? WHERE id = ?")
-      .run(createdAt, updatedAt, id);
+      .prepare("UPDATE notes SET created_at = ?, updated_at = ?, updated_at_ms = ? WHERE id = ?")
+      .run(createdAt, updatedAt, updatedAtMs, id);
   }
 
   async deleteNote(id: string): Promise<void> {
@@ -311,6 +435,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 +685,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 +869,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 {