@openparachute/vault 0.7.1 → 0.7.2-rc.4

package/core/src/portable-md.ts

@@ -77,6 +77,7 @@ import { basename, join, relative, extname, dirname, resolve as resolvePath, sep
 import type { Store, Note, Link, Attachment } from "./types.js";
 import type { TagRecord } from "./tag-schemas.js";
 import { ParentCycleError } from "./tag-schemas.js";
+import { transactionAsync } from "./txn.js";
 
 // ---------------------------------------------------------------------------
 // Format constants
@@ -786,8 +787,23 @@ export class FsExportSink implements ExportSink {
         reason: `path-traversal: resolved write target "${fullResolved}" escapes export root "${this.rootResolved}"`,
       };
     }
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, content);
+    // Belt for already-poisoned vaults (vault#589 / FIX 2). A NUL-in-path note
+    // resolves WITHIN the export root (passing the traversal guard above) but
+    // then makes `writeFileSync` throw ("path contains null byte") — an
+    // uncaught throw here would abort the ENTIRE export, so one bad note breaks
+    // backup for every note. Any fs failure (NUL, EACCES, ENAMETOOLONG, …)
+    // becomes a skip-with-reason the caller records as a `skipped_notes` stat +
+    // a warning, exactly like the traversal skip, so the rest of the vault
+    // still exports.
+    try {
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, content);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `fs write failed for "${relPath}": ${(err as Error)?.message ?? String(err)}`,
+      };
+    }
     return { ok: true };
   }
 
@@ -812,8 +828,17 @@ export class FsExportSink implements ExportSink {
         reason: `path-traversal: dest "${destResolved}" escapes export root "${this.rootResolved}"`,
       };
     }
-    mkdirSync(dirname(destFull), { recursive: true });
-    copyFileSync(srcResolved, destResolved);
+    // Same belt as `writeText` (vault#589 / FIX 2): a NUL/otherwise-unwritable
+    // attachment dest must skip-with-reason, not abort the whole export.
+    try {
+      mkdirSync(dirname(destFull), { recursive: true });
+      copyFileSync(srcResolved, destResolved);
+    } catch (err) {
+      return {
+        ok: false,
+        reason: `fs copy failed for "${destRelPath}": ${(err as Error)?.message ?? String(err)}`,
+      };
+    }
     return { ok: true };
   }
 }
@@ -878,11 +903,29 @@ export async function exportVault(
     ...(opts.vaultName ? { name: opts.vaultName } : {}),
     ...(opts.vaultDescription ? { description: opts.vaultDescription } : {}),
   };
-  sink.writeText(join(SIDECAR_DIR, "vault.yaml"), emitYamlDoc(vaultMeta as unknown as Record<string, unknown>));
+  // The manifest is STRUCTURAL, not per-note: a portable-md export WITHOUT its
+  // `.parachute/vault.yaml` is unusable — restore (`importPortableVault`), CLI
+  // autodetect, and mirror-import all hard-reject a dir that lacks it. So the
+  // skip-with-warn belt that hardens per-note writes (vault#589 / FIX 2b) is
+  // exactly WRONG here: a discarded `{ok:false}` would produce a manifest-less
+  // "success" — a silently-broken backup. Fail LOUDLY instead. (Per-note
+  // content/attachment writes below stay skip-with-warn — one poisoned note
+  // must not abort the whole export.)
+  const manifestPath = join(SIDECAR_DIR, "vault.yaml");
+  const manifestWrite = sink.writeText(manifestPath, emitYamlDoc(vaultMeta as unknown as Record<string, unknown>));
+  if (!manifestWrite.ok) {
+    throw new Error(
+      `export aborted: failed to write the vault manifest "${manifestPath}": ${manifestWrite.reason}. ` +
+      `A portable-md export without its manifest is unusable (restore/import hard-rejects it), so this fails loudly rather than producing a manifest-less "success".`,
+    );
+  }
 
   // 2. Per-tag schemas. Only tags carrying at least one schema-shaped
   // field (description, fields, relationships, parent_names) get a file;
-  // tags that are just-a-name don't pollute the sidecar.
+  // tags that are just-a-name don't pollute the sidecar. Schemas are
+  // structural too — a dropped schema sidecar silently loses a tag's
+  // definition from the backup — so a write failure here also fails loudly
+  // (and never increments `schemasWritten` on a failed write).
   const tagRecords = await store.listTagRecords();
   let schemasWritten = 0;
   for (const tag of tagRecords) {
@@ -895,7 +938,14 @@ export async function exportVault(
     if (tag.parent_names !== undefined && tag.parent_names.length > 0) {
       doc.parent_names = tag.parent_names;
     }
-    sink.writeText(join(SIDECAR_DIR, "schemas", filename), emitYamlDoc(doc));
+    const schemaPath = join(SIDECAR_DIR, "schemas", filename);
+    const schemaWrite = sink.writeText(schemaPath, emitYamlDoc(doc));
+    if (!schemaWrite.ok) {
+      throw new Error(
+        `export aborted: failed to write schema sidecar "${schemaPath}" for tag "${tag.tag}": ${schemaWrite.reason}. ` +
+        `Tag schemas are structural — a partial export would silently drop a schema definition — so this fails loudly.`,
+      );
+    }
     schemasWritten++;
   }
 
@@ -1643,6 +1693,17 @@ export interface ImportStats {
    * imports — the cycle is warned, not fatal. Empty in the common case.
    */
   skipped_schema_parents: Array<{ tag: string; parent_names: string[]; reason: string }>;
+  /**
+   * Content files skipped because their frontmatter `id` couldn't be used as
+   * a note key (vault#589 / FIX 3): a DUPLICATE id (a later file shares an id
+   * with one already imported — the first wins, deterministically, since
+   * `listContentFiles()` walks in sorted path order) or a BLANK id
+   * (whitespace-only, e.g. `"   "`). Without this the later duplicate silently
+   * clobbered the earlier note (data loss folded into "updated N") and a
+   * blank id seeded a bogus map key. Each entry names the offending id, the
+   * skipped file's path, and why. Empty in the common case.
+   */
+  skipped_duplicate_ids: Array<{ id: string; path: string | undefined; reason: string }>;
   /** Set when the caller passed `blowAway: true`; counts notes removed. */
   notes_wiped: number;
   /**
@@ -1815,10 +1876,49 @@ export async function importVault(
     skipped_attachments: [],
     skipped_sidecars: [],
     skipped_schema_parents: [],
+    skipped_duplicate_ids: [],
     notes_wiped: 0,
     indexes_declared: 0,
   };
 
+  // Blow-away is all-or-nothing (vault#589 / FIX 1). A blow-away import wipes
+  // the vault (step 1) then replays every schema/note/link/attachment. If any
+  // replay step throws mid-flight — a `PathConflictError` from two source
+  // files sharing a path, a malformed record, a crash — an UNWRAPPED run would
+  // leave the vault wiped-and-partial with the originals gone for good. Wrap
+  // the wipe + the whole replay in ONE transaction so a failure rolls back to
+  // the exact pre-import vault. The transaction seam is re-entrant (SAVEPOINTs,
+  // vault#589) so the replay's own transactional writes (`upsertTagRecord`,
+  // `deleteTag` cascade, …) compose inside it rather than hitting SQLite's
+  // "cannot start a transaction within a transaction". Additive (non-blow-away)
+  // and dry-run imports are never destructive, so they replay unwrapped —
+  // exactly as before. Hook dispatch stays best-effort/reconciled: no
+  // registered hook does synchronous destructive work (the mirror arms a
+  // debounce; transcription only fires on attachment `created` and kicks an
+  // idempotent worker), so a rollback can't leave a half-applied side effect
+  // the sweep won't reconcile.
+  if (opts.blowAway && !opts.dryRun) {
+    await transactionAsync(store.db, () => importVaultReplay(store, source, opts, stats));
+  } else {
+    await importVaultReplay(store, source, opts, stats);
+  }
+
+  return stats;
+}
+
+/**
+ * The replay body of {@link importVault} — wipe (blow-away only) then restore
+ * schemas → notes → links → attachments → wikilinks → indexes, mutating the
+ * shared `stats`. Split out so `importVault` can run it either bare or inside a
+ * single `transactionAsync` (the atomic blow-away path); the restoration order
+ * and every skip/warn policy are unchanged from the pre-split code.
+ */
+async function importVaultReplay(
+  store: Store,
+  source: ImportSource,
+  opts: ImportEngineOptions,
+  stats: ImportStats,
+): Promise<void> {
   // 1. Optional wipe. Notes are deleted via the public Store API so hooks
   // fire (callers depend on `attachment.deleted` hooks for assets-dir
   // cleanup; we don't bypass that on blow-away). Deleted in bounded batches
@@ -2049,6 +2149,39 @@ export async function importVault(
       ...(links ? { links: links as PortableLink[] } : {}),
       ...(attachments ? { attachments: attachments as PortableAttachmentRef[] } : {}),
     };
+
+    // FIX 3 (vault#589) — guard the `seenNotes` key before it's set:
+    //   - A whitespace-only id ("   ") slips past the `!id` truthiness guard
+    //     above (non-empty string) but is not a real note key. Skip it rather
+    //     than seeding a bogus map entry / clobbering a real note.
+    //   - A DUPLICATE id means a LATER content file carries an id already
+    //     imported from an earlier file. The old `Map.set` silently
+    //     last-wins-clobbered the first note (data loss, folded into
+    //     "updated N"). Keep the FIRST (deterministic — `listContentFiles()`
+    //     returns sorted paths) and skip the later, recording the collision.
+    // Both cases land in `skipped_duplicate_ids` + a per-file `console.warn`
+    // so the operator sees the collision instead of it vanishing.
+    if (id.trim() === "") {
+      stats.skipped_duplicate_ids.push({
+        id,
+        path: portable.path,
+        reason: "blank (whitespace-only) id is not a valid note key",
+      });
+      // eslint-disable-next-line no-console
+      console.warn(`[import] skipped "${relPath}": blank (whitespace-only) \`id\` in frontmatter`);
+      continue;
+    }
+    if (seenNotes.has(id)) {
+      const kept = seenNotes.get(id)!;
+      stats.skipped_duplicate_ids.push({
+        id,
+        path: portable.path,
+        reason: `duplicate id "${id}" — already imported from an earlier file${kept.path ? ` (path="${kept.path}")` : ""}; kept the first, skipped this one`,
+      });
+      // eslint-disable-next-line no-console
+      console.warn(`[import] skipped "${relPath}": duplicate id "${id}" (kept the first file's note; this file's content is NOT imported)`);
+      continue;
+    }
     seenNotes.set(id, portable);
 
     if (opts.dryRun) {
@@ -2232,8 +2365,6 @@ export async function importVault(
       }
     }
   }
-
-  return stats;
 }
 
 /**

package/core/src/query-operators.ts

@@ -101,13 +101,69 @@ function toBinding(field: string, op: string, value: unknown): SQLQueryBindings
   );
 }
 
+/**
+ * Best-effort lookup of a metadata field's declared `type` across every tag
+ * schema — used ONLY to sharpen the {@link requireIndexedField} error hint
+ * below when the field was never indexed. Scans `tags.fields` directly
+ * rather than going through `indexed_fields` (which by construction has no
+ * row for a type that can never BE indexed, e.g. `"number"`) or a
+ * per-note schema resolution (scoped to one note's tags, not "any tag
+ * anywhere"). Only reached on the FIELD_NOT_INDEXED error path — a full
+ * table scan here is fine since it runs once per rejected call, never on a
+ * hot path. Returns the type from the FIRST tag found declaring `field`
+ * (a cross-tag type conflict on the same field name is its own separate
+ * validation elsewhere, not this function's job); `undefined` when no tag
+ * declares this field name, or its `fields` JSON doesn't parse.
+ */
+function findDeclaredFieldType(db: Database, field: string): string | undefined {
+  const rows = db.prepare(
+    `SELECT fields FROM tags WHERE fields IS NOT NULL`,
+  ).all() as { fields: string | null }[];
+  for (const row of rows) {
+    if (!row.fields) continue;
+    try {
+      const parsed: unknown = JSON.parse(row.fields);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      const spec = (parsed as Record<string, unknown>)[field];
+      if (spec === null || typeof spec !== "object" || Array.isArray(spec)) continue;
+      const type = (spec as Record<string, unknown>).type;
+      if (typeof type === "string") return type;
+    } catch {
+      // Malformed `fields` JSON on some other tag — not this lookup's job
+      // to validate; skip and keep scanning.
+    }
+  }
+  return undefined;
+}
+
 /**
  * Look up `field` in `indexed_fields` or throw a loud error suggesting the
  * caller declare it via `update-tag` with `indexed: true`.
+ *
+ * That generic advice is IMPOSSIBLE to satisfy for a field whose schema
+ * declares `type: "number"` (a float) — only `integer`/`boolean` are
+ * indexable numeric shapes (see `indexed-fields.ts`'s `TYPE_MAP`), so
+ * `update-tag` with `indexed: true` on a `number` field itself throws
+ * "unsupported type ... for indexing". An agent that only sees the generic
+ * hint has no escape from that loop (LB — round-4 bug hunt). When the
+ * declared type is `"number"`, swap in a hint that names the actual fix:
+ * store the value as an integer (e.g. cents instead of dollars) and index
+ * THAT field instead.
  */
 export function requireIndexedField(db: Database, field: string): IndexedField {
   const row = getIndexedField(db, field);
   if (!row) {
+    if (findDeclaredFieldType(db, field) === "number") {
+      throw new QueryError(
+        `metadata field "${field}" is not indexed, and can never be: it's declared type: "number" (a float), and only integer/boolean fields are indexable numeric types. "declare indexed: true" will not work on this field.`,
+        "FIELD_NOT_INDEXED",
+        {
+          error_type: "field_not_indexed",
+          field,
+          hint: `"${field}" is a float ("number") field — float fields can't be server-side indexed, filtered with operators, used in order_by, or summed via aggregate. Store the value as an integer instead (e.g. cents rather than dollars) and declare indexed: true on THAT field to enable those.`,
+        },
+      );
+    }
     throw new QueryError(
       `metadata field "${field}" is not indexed. To use operator queries or order_by on this field, declare it via update-tag with indexed: true.`,
       "FIELD_NOT_INDEXED",

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
@@ -404,8 +404,8 @@ 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
@@ -423,18 +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 projection any time; the base call
-  includes a compact \`map\` (tag counts, top-level path-bucket counts, total
-  notes) so you can orient in this one call — no flag needed.
+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:
@@ -453,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

package/core/src/store.ts

@@ -15,8 +15,10 @@ import {
   resolveUnresolvedWikilinks,
   resolveOrQueueLink,
   clearQueuedLink,
+  requeueInboundWikilinksForDelete,
 } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
+import { timestampToMs } from "./cursor.js";
 import { transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
 import {
@@ -360,9 +362,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> {
@@ -372,6 +383,13 @@ export class BunSqliteStore implements Store {
     // by design, hooks subscribing to "deleted" receive a DeletedNoteRef,
     // not a Note.
     const existing = noteOps.getNote(this.db, id);
+    // LB6: re-queue inbound wikilink edges BEFORE the FK cascade drops the
+    // `links` rows, so recreating a note at this path/title auto-heals the
+    // edge instead of leaving every referencing note's `[[link]]` dead until
+    // it's individually re-saved. See requeueInboundWikilinksForDelete's doc
+    // comment for why this must run pre-delete and what it deliberately
+    // excludes (typed `links`, not just wikilinks).
+    requeueInboundWikilinksForDelete(this.db, id);
     noteOps.deleteNote(this.db, id);
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
     // Dispatch even when `existing` was null — the caller asked for a

package/core/src/tag-hierarchy.ts

@@ -372,6 +372,19 @@ export function computeExpandedTagCounts(
 export function findHierarchyCycles(h: TagHierarchy): string[] {
   const cycles: string[] = [];
   for (const tag of h.childrenOf.keys()) {
+    // Direct self-edge (`parent_names` lists the tag itself) — checked
+    // separately from the descendant-set gate below because
+    // `getTagDescendants` can't see it: its traversal seeds `result` with
+    // `{tag}` and then skips re-expanding any child already present in
+    // `result` (the visited-set that makes runtime traversal cycle-safe) —
+    // so a bare `X -> X` edge never grows `descendants` past size 1, and
+    // `descendants.size > 1` alone silently reports it clean. Only
+    // reachable via guard-bypassing data (a direct DB write, or an import
+    // that skips `upsertTagRecord`'s write-time cycle guard).
+    if (h.childrenOf.get(tag)?.has(tag)) {
+      cycles.push(tag);
+      continue;
+    }
     const descendants = getTagDescendants(h, tag);
     if (descendants.has(tag) && descendants.size > 1) {
       // tag reaches itself through a non-trivial path