@openparachute/vault 0.7.1 → 0.7.2-rc.3

package/core/src/portable-md.test.ts

@@ -29,6 +29,7 @@ import { buildVaultProjection } from "./vault-projection.js";
 import {
   CaseCollisionError,
   emitYamlDoc,
+  exportVault,
   exportVaultToDir,
   importPortableVault,
   noteToPortable,
@@ -41,7 +42,9 @@ import {
   supportsInlineFrontmatter,
   toPortableMarkdown,
   toSidecarYaml,
+  type ExportSink,
   type PortableNote,
+  type SinkWriteResult,
 } from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
@@ -416,6 +419,86 @@ describe("exportVaultToDir", async () => {
     expect(vault).toContain("name: test");
   });
 
+  // FIX 2(b) (vault#589) — a NUL-in-path note (a pre-fix poisoned row a
+  // write-capable token could have planted) must be SKIPPED with a warning +
+  // stat, never abort the whole export. Before the sink hardening the
+  // uncaught `writeFileSync` throw aborted the entire vault export, so one bad
+  // note broke backup/export for everyone.
+  //
+  // RED-without-fix: drop the try/catch from `FsExportSink.writeText` and this
+  // test's `exportVaultToDir` call throws (whole export aborts) instead of
+  // returning a partial-with-skip result. Verified manually during development.
+  it("hardened export sink: a NUL-in-path note is skipped, not fatal (vault#589)", async () => {
+    await store.createNote("clean one", { id: "c1", path: "clean/one" });
+    await store.createNote("clean two", { id: "c2", path: "clean/two" });
+    await store.createNote("poison", { id: "p1", path: "temp" });
+    // Simulate a pre-fix vault: inject a real NUL directly into the stored
+    // path, bypassing normalizePath (which now strips NUL). `char(0)` yields a
+    // NUL byte in the TEXT column that survives read-back into note.path.
+    store.db.prepare("UPDATE notes SET path = 'bad' || char(0) || 'path' WHERE id = ?").run("p1");
+
+    const outDir = join(tmpBase, "poisoned-out");
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-05-13T00:00:00.000Z" });
+
+    // The export completes and every OTHER note is written ...
+    expect(existsSync(join(outDir, "clean/one.md"))).toBe(true);
+    expect(existsSync(join(outDir, "clean/two.md"))).toBe(true);
+    expect(stats.notes).toBe(2); // only the two clean notes counted as written
+
+    // ... while the poisoned note is skipped-with-reason (fs write failure),
+    // surfaced as a stat rather than a thrown, aborted export.
+    expect(stats.skipped_traversal).toBeGreaterThanOrEqual(1);
+    const poisonSkip = stats.skipped_notes.find((s) => s.reason.includes("fs write failed"));
+    expect(poisonSkip).toBeTruthy();
+  });
+
+  // BLOCKER (vault#589 review) — the skip-with-warn export belt (FIX 2b) is
+  // correct ONLY for per-NOTE writes. The STRUCTURAL writes (the vault.yaml
+  // manifest + per-tag schema sidecars) are global: a dir missing
+  // `.parachute/vault.yaml` is hard-rejected at restore/import, so a discarded
+  // `{ok:false}` there would produce a manifest-less "success" — a silently
+  // broken backup. Those must FAIL LOUDLY.
+  //
+  // RED-without-fix: with the structural writes discarding the sink result,
+  // both `exportVault` calls RESOLVE (no throw) and the manifest/schema is
+  // silently absent. Verified manually during development.
+  it("aborts loudly when the manifest write fails (structural, not skip-with-warn)", async () => {
+    await store.createNote("n", { id: "n1", path: "p" });
+    // Stub sink that fails ONLY the manifest write; everything else succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath === join(SIDECAR_DIR, "vault.yaml")) {
+          return { ok: false, reason: "simulated EACCES on .parachute/" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/manifest/i);
+  });
+
+  it("aborts loudly when a schema sidecar write fails (structural, not skip-with-warn)", async () => {
+    await store.upsertTagSchema("task", { description: "A unit of work" });
+    await store.createNote("x", { id: "x1", tags: ["task"] });
+    // Fail ONLY the schema write; the manifest (and everything else) succeeds.
+    const sink: ExportSink = {
+      caseSensitive: true,
+      attachmentsEnabled: false,
+      writeText(relPath: string): SinkWriteResult {
+        if (relPath.startsWith(join(SIDECAR_DIR, "schemas"))) {
+          return { ok: false, reason: "simulated disk full" };
+        }
+        return { ok: true };
+      },
+      copyAttachment(): SinkWriteResult { return { ok: true }; },
+    };
+    await expect(exportVault(store, sink, { exportedAt: "2026-05-13T00:00:00.000Z" }))
+      .rejects.toThrow(/schema sidecar/i);
+  });
+
   it("writes per-tag schemas to .parachute/schemas/", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",
@@ -710,6 +793,84 @@ describe("importPortableVault", async () => {
     expect(await targetStore.getNote("k1")).toBeTruthy();
   });
 
+  // FIX 1 (vault#589) — blow-away must be all-or-nothing. Before the fix, the
+  // wipe + replay ran with NO enclosing transaction: a mid-replay throw (here a
+  // PathConflictError from two source files declaring the same `path`) left the
+  // vault WIPED + partially replayed, originals gone for good. The wrap rolls
+  // the whole thing back to the exact pre-import vault.
+  //
+  // RED-without-fix: temporarily change `importVault` to always call
+  // `importVaultReplay` unwrapped (drop the `transactionAsync`) and this test
+  // ends with 1 note (`n-first`), all three originals gone — the assertions
+  // below fail. Verified manually during development.
+  it("--blow-away is atomic — a mid-replay throw rolls back to the original vault (vault#589)", async () => {
+    // Target vault holds originals that MUST survive a failed restore.
+    const target = new SqliteStore(new Database(":memory:"));
+    await target.createNote("original one", { id: "orig1", path: "keep/one" });
+    await target.createNote("original two", { id: "orig2", path: "keep/two" });
+    await target.createNote("original three", { id: "orig3", path: "keep/three" });
+
+    // Hand-build a poisoned export: two notes declaring the SAME frontmatter
+    // `path` → the 2nd createNote throws PathConflictError mid-replay. Files
+    // walk in sorted order (first.md before second.md), so first.md lands, then
+    // second.md collides.
+    const inDir = join(tmpBase, "poison-collide");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: poison\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "first.md"), "---\nid: nfirst\npath: collide\n---\nfirst body\n");
+    writeFileSync(join(inDir, "second.md"), "---\nid: nsecond\npath: collide\n---\nsecond body\n");
+
+    // The blow-away import propagates the collision (rejects) ...
+    await expect(importPortableVault(target, { inDir, blowAway: true })).rejects.toThrow();
+
+    // ... and rolls back: all three ORIGINALS survive, and NONE of the
+    // poisoned import's notes landed. The vault is exactly as it was.
+    expect(await target.getNote("orig1")).toBeTruthy();
+    expect(await target.getNote("orig2")).toBeTruthy();
+    expect(await target.getNote("orig3")).toBeTruthy();
+    expect(await target.getNote("nfirst")).toBeNull();
+    expect(await target.getNote("nsecond")).toBeNull();
+    const all = await target.queryNotes({ limit: 100 });
+    expect(all.length).toBe(3);
+  });
+
+  // FIX 3 (vault#589) — duplicate-id and blank-id content files must be
+  // reported + skipped, not silently clobber (last-wins) or seed a bogus key.
+  it("reports duplicate + blank note ids instead of silently clobbering (vault#589)", async () => {
+    // Hand-build a tree: two files share id "dup" (distinct content); a third
+    // carries a whitespace-only id. Files walk sorted: aaa < bbb < ccc.
+    const inDir = join(tmpBase, "dup-ids");
+    mkdirSync(join(inDir, ".parachute"), { recursive: true });
+    writeFileSync(join(inDir, ".parachute", "vault.yaml"), "name: dup\nexport_format_version: 1\n");
+    writeFileSync(join(inDir, "aaa.md"), "---\nid: dup\npath: pa\n---\nfrom aaa\n");
+    writeFileSync(join(inDir, "bbb.md"), "---\nid: dup\npath: pb\n---\nfrom bbb\n");
+    writeFileSync(join(inDir, "ccc.md"), "---\nid: '   '\npath: pc\n---\nfrom ccc\n");
+
+    const target = new SqliteStore(new Database(":memory:"));
+    const stats = await importPortableVault(target, { inDir });
+
+    // Exactly ONE note created — the FIRST of the id collision (aaa) — and the
+    // collision is NOT folded into "updated".
+    expect(stats.notes_created).toBe(1);
+    expect(stats.notes_updated).toBe(0);
+    const kept = await target.getNote("dup");
+    expect(kept).toBeTruthy();
+    expect(kept!.content.trimEnd()).toBe("from aaa"); // first-wins, deterministic
+
+    // Both the duplicate (bbb) and the blank-id (ccc) file are reported as
+    // skipped — surfaced in stats, not absorbed into the created/updated count.
+    expect(stats.skipped_duplicate_ids.length).toBe(2);
+    const dupEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("duplicate id"));
+    expect(dupEntry).toBeTruthy();
+    expect(dupEntry!.path).toBe("pb");
+    const blankEntry = stats.skipped_duplicate_ids.find((s) => s.reason.includes("blank"));
+    expect(blankEntry).toBeTruthy();
+
+    // The whitespace-id file clobbered nothing — no bogus key, only "dup" exists.
+    const allNotes = await target.queryNotes({ limit: 100 });
+    expect(allNotes.length).toBe(1);
+  });
+
   it("restores tag schemas (description + fields)", async () => {
     await store.upsertTagSchema("task", {
       description: "A unit of work",

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/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