@openparachute/vault 0.7.6 → 0.7.7

package/core/src/schema.ts

@@ -388,6 +388,9 @@ CREATE INDEX IF NOT EXISTS idx_mcp_mint_ledger_session ON mcp_mint_ledger(parent
  * on every open. Migrations occasionally disable it transiently (see
  * migrateToV14's BEGIN IMMEDIATE block); the boot path re-enables.
  *
+ * `busy_timeout` is likewise per-connection. See {@link BUSY_TIMEOUT_MS} for
+ * why a zero default is wrong for a daemon-plus-CLI deployment.
+ *
  * WAL requires a filesystem that supports memory-mapped shared-memory
  * (the `-shm` sidecar). NFS, some FUSE mounts, and a few Docker volume
  * drivers don't qualify and silently fall back to the prior journal mode
@@ -397,6 +400,30 @@ CREATE INDEX IF NOT EXISTS idx_mcp_mint_ledger_session ON mcp_mint_ledger(parent
  */
 const APPLY_PRAGMAS_LOGGED = new WeakSet<Database>();
 
+/**
+ * How long SQLite parks on a locked database before giving up with
+ * SQLITE_BUSY (vault#527).
+ *
+ * The default is 0 — a contended write fails INSTANTLY. That's the wrong
+ * default for this product's actual deployment shape: the daemon holds a live
+ * WAL connection on :1940 while the operator runs a CLI command (`add-pack`,
+ * `schema migrate-field`, an import) against the same file from another
+ * process. Under WAL, readers never block, but two WRITERS still serialize —
+ * and with no timeout the CLI's write loses the instant it overlaps the
+ * daemon's, surfacing as an error whose only remedy is "please re-run".
+ *
+ * Five seconds is far longer than any single vault write (these are
+ * millisecond-scale row inserts) so it costs nothing on an uncontended box,
+ * while comfortably covering an overlapping daemon transaction. It is not a
+ * substitute for retry logic on a genuinely long-held lock — it's the
+ * difference between "wait your turn" and "fail immediately", which is the
+ * behaviour a single-file embedded database should have had from the start.
+ *
+ * Per-connection (not persistent), so it must be re-applied on every open —
+ * which is why it lives here rather than in a migration.
+ */
+export const BUSY_TIMEOUT_MS = 5000;
+
 export interface ConnectionPragmaResult {
   /** True when the connection ended up in WAL mode. False means the FS doesn't support WAL. */
   wal: boolean;
@@ -457,6 +484,11 @@ export function applyConnectionPragmas(db: Database): ConnectionPragmaResult {
 
   try { db.exec("PRAGMA foreign_keys = ON"); } catch {}
 
+  // Deliberately NOT gated on the WAL branch: SQLITE_BUSY is not WAL-specific,
+  // and a rollback-journal DB (the NFS/FUSE fallback above) serializes harder,
+  // so it needs the grace more, not less.
+  try { db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`); } catch {}
+
   return { wal, journalMode };
 }
 

package/core/src/seed-packs.ts

@@ -780,6 +780,32 @@ matter to the operator; surface the indexed fields they filter on. If the vault
 doesn't yet have the structure a surface wants, that's a signal to design tags +
 schemas first.
 
+## Deploying your surface
+
+A surface is a **static build** — there's no server to run. \`bun run build\`
+produces a \`dist/\` of plain HTML/JS/CSS that any static host serves: GitHub
+Pages, Cloudflare Pages, Netlify, an S3 bucket.
+
+For **GitHub Pages**, push the BUILT FILES to a \`gh-pages\` branch (or a
+\`docs/\` folder on your default branch) and point Settings → Pages at it.
+Deliberately: **don't reach for an Actions workflow.** Some agent GitHub
+integrations can't write \`.github/workflows/*\` — the push comes back 403 —
+and a static build doesn't need CI at all. Build locally, publish the output.
+
+Two things must line up or the deployed surface will load and then fail to
+sign in:
+
+- the **hub origin** your surface points at has to be reachable from wherever
+  the browser is (a \`localhost\` hub won't answer a page served from GitHub
+  Pages);
+- that surface's **origin must be trusted by the hub** for CORS + as an OAuth
+  redirect origin.
+
+Both trace back to the same place the \`createVaultSurface\` config above does:
+\`vault-info\`'s **"This vault's coordinates"** block reports this vault's hub
+origin and name. If sign-in fails from the deployed URL but works from
+\`localhost\`, suspect the origin allowlist before the code.
+
 ## Adapt this note
 
 When you build a surface for this vault, record it here: what it's for, the
@@ -1045,6 +1071,12 @@ export interface ApplySeedPackResult {
  * rows — so a re-run can never duplicate, and never clobbers a note the
  * operator/AI has since edited or recreated.
  *
+ * The per-note check is check-then-create, so two appliers running at once
+ * can both see "absent" and both try to create. The loser's path-UNIQUE
+ * rejection is caught and reported as a SKIP (vault#527) — same outcome the
+ * non-racing branch reports, because the note it would have written is there.
+ * Only a path conflict is absorbed; see `isPathConflict`.
+ *
  * **Tag description preservation** (Aaron-ratified 2026-07-17): a pack writes
  * a tag's `description` only when (a) the tag has no prior description (new
  * tag, or an existing bare row nothing ever described), or (b) the prior
@@ -1112,13 +1144,50 @@ export async function applySeedPack(
       result.skippedNotes.push(note.path);
       continue;
     }
-    await store.createNote(note.content, {
-      path: note.path,
-      tags: note.tags,
-      metadata: note.metadata,
-    });
+    try {
+      await store.createNote(note.content, {
+        path: note.path,
+        tags: note.tags,
+        metadata: note.metadata,
+      });
+    } catch (err) {
+      // Lost a check-then-create race (vault#527). The `getNoteByPath` above
+      // said absent, but another applier committed that path before our
+      // insert landed, and the path UNIQUE index rejected us. The OUTCOME is
+      // the one this applier already promises — a note exists at that path
+      // and we didn't clobber it — so report it the same way the non-racing
+      // branch does, as a skip, rather than aborting the pack mid-way with a
+      // raw constraint error the operator can only answer by re-running.
+      //
+      // Narrow by design: ONLY a path conflict is absorbed. Any other create
+      // failure still propagates, per this function's "errors propagate"
+      // contract above.
+      if (!isPathConflict(err)) throw err;
+      result.skippedNotes.push(note.path);
+      continue;
+    }
     result.seededNotes.push(note.path);
   }
 
   return result;
 }
+
+/**
+ * Is this the store's "a note already uses that path" rejection?
+ *
+ * Duck-typed on the STABLE `error_type` / `code` contract (vault#554) rather
+ * than `instanceof PathConflictError`, because this module is deliberately
+ * import-type-only — it carries no runtime dependency on `notes.ts`/`bun:sqlite`
+ * so the cloud Durable Object can share it. Both fields are pinned public API
+ * on the self-host class and on the REST/MCP error mapping, so matching them
+ * is not a guess about internals.
+ */
+function isPathConflict(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { error_type?: unknown; code?: unknown; name?: unknown };
+  return (
+    e.error_type === "path_conflict" ||
+    e.code === "PATH_CONFLICT" ||
+    e.name === "PathConflictError"
+  );
+}

package/core/src/sql-in.ts

@@ -36,6 +36,8 @@
  * and is the conservative floor everywhere.
  */
 
+import type { SqliteType } from "./indexed-fields.js";
+
 /**
  * Chunk size for standalone `IN (?, ?, …)` id-lists. 90 leaves headroom
  * under the DO 100-param cap for statements whose only bound params are the
@@ -70,7 +72,35 @@ export function chunkForInClause<T>(items: readonly T[], size = IN_PARAM_CHUNK):
  */
 export const IN_VIA_JSON_EACH = "(SELECT value FROM json_each(?))";
 
-/** Serialize an id-set for the single {@link IN_VIA_JSON_EACH} bound param. */
-export function jsonEachParam(values: readonly (string | number)[]): string {
+/**
+ * Like {@link IN_VIA_JSON_EACH}, but CASTs each `json_each` value to the
+ * target column's declared SQLite storage type before the `IN` comparison.
+ *
+ * A placeholder list `IN (?, ?, …)` applied the LEFT column's type affinity
+ * to each bound value for free — a bound `5` compared against a TEXT-affinity
+ * column matched the stored `'5'`. Values arriving out of a `json_each`
+ * subquery do NOT get that conversion, so a numeric `5` from `{ in: [5] }`
+ * silently stopped matching a TEXT-affinity indexed column (vault#676). The
+ * explicit CAST restores the old cross-type match in BOTH directions
+ * (TEXT column / numeric value AND INTEGER column / string value), mirroring
+ * exactly what the placeholder list got implicitly. `sqliteType` is a fixed
+ * enum ("TEXT" | "INTEGER") from `indexed_fields`, never user input, so
+ * interpolating it into the SQL is safe.
+ */
+export function inViaJsonEachCast(sqliteType: SqliteType): string {
+  return `(SELECT CAST(value AS ${sqliteType}) FROM json_each(?))`;
+}
+
+/**
+ * Serialize a value-set for the single {@link IN_VIA_JSON_EACH} bound param.
+ *
+ * Accepts `boolean`/`null` as well as ids because the metadata `in`/`not_in`
+ * operators route through this too (vault#536), and those take any primitive
+ * the caller can put in a metadata field. `bigint` is deliberately NOT
+ * accepted — `JSON.stringify` throws on it — so callers must narrow first.
+ */
+export function jsonEachParam(
+  values: readonly (string | number | boolean | null)[],
+): string {
   return JSON.stringify(values);
 }

package/core/src/store.ts

@@ -832,55 +832,22 @@ export class BunSqliteStore implements Store {
     return { ...opts, _tagsExpanded: expanded } as QueryOpts;
   }
 
-  async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]> {
-    // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
-    // filters before expansion, so `#manual` and `manual` resolve identically.
-    if (opts?.tags && opts.tags.length > 0) {
-      opts = { ...opts, tags: opts.tags.map(stripTagHash).filter((t) => t !== "") };
-    }
-    // Same tag-expansion treatment as queryNotes, along the SAME `expand` axis
-    // (vault tag `expand` axis) — searching `#manual` should match notes
-    // tagged with any descendant under "subtypes", any `manual/*` under
-    // "namespace", etc. The underlying FTS path already uses `IN (...)` for
-    // tags, so we flatten the per-input expansions into a single union (search
-    // semantics are "any tag matches").
-    //
-    // `_default` collapse is a SUBTYPES-axis concept (the universal *parent*):
-    // when `_default` is among the requested tags and a `_default` row exists,
-    // the OR collapses to "every note" — drop the tag filter entirely so the
-    // search hits the full corpus and untagged notes are reachable. It fires
-    // only on the subtypes/both axes (mirrors `expandQueryTags`).
-    if (opts?.tags && opts.tags.length > 0) {
-      const mode: TagExpandMode = opts.expand ?? DEFAULT_TAG_EXPAND_MODE;
-      const subtypeAxis = mode === "subtypes" || mode === "both";
-      const hierarchy = this.getTagHierarchy();
-      if (subtypeAxis && hierarchy.allTags.has(DEFAULT_TAG_NAME) && opts.tags.includes(DEFAULT_TAG_NAME)) {
-        const { tags: _drop, expand: _e, ..._rest } = opts;
-        return noteOps.searchNotes(this.db, query, _rest);
-      }
-      // Subtypes fast-path: with no declared hierarchy there are no
-      // descendants, so the tags pass through unchanged (byte-identical to
-      // pre-axis behavior). `exact` likewise needs no expansion.
-      // Namespace/both must still run (lexical expansion is independent of
-      // `parent_names`).
-      const skipExpansion =
-        mode === "exact" || (mode === "subtypes" && hierarchy.childrenOf.size === 0);
-      if (!skipExpansion) {
-        const expanded = new Set<string>();
-        for (const t of opts.tags) {
-          for (const x of getTagExpansion(hierarchy, t, mode)) expanded.add(x);
-        }
-        const { expand: _e, ..._rest } = opts;
-        return noteOps.searchNotes(this.db, query, { ..._rest, tags: Array.from(expanded) });
-      }
-    }
-    // Strip the internal `expand` before passing to noteOps (it has no field
-    // for it; harmless but keep the boundary clean).
-    if (opts && "expand" in opts) {
-      const { expand: _e, ..._rest } = opts;
-      return noteOps.searchNotes(this.db, query, _rest);
-    }
-    return noteOps.searchNotes(this.db, query, opts);
+  async searchNotes(query: string, opts?: QueryOpts & { mode?: SearchMode }): Promise<Note[]> {
+    // Same bare-tag strip + hierarchy expansion queryNotes uses, so
+    // `search` + `tag: "manual"` still matches declared descendants
+    // (vault#227) and `#tag` / `tag` resolve identically. Default
+    // `tagMatch` to `"any"` when the caller didn't set it — historical FTS
+    // tag semantics are a single IN (...) ("any tag matches"), which also
+    // makes `_default` collapse drop the whole tag filter (OR + universal
+    // parent = every note).
+    const incoming = opts ?? {};
+    const withTagMatch: QueryOpts & { mode?: SearchMode } = {
+      ...incoming,
+      tagMatch: incoming.tagMatch ?? (incoming.tags && incoming.tags.length > 0 ? "any" : undefined),
+    };
+    const expanded = this.expandQueryTags(this.normalizeQueryTags(withTagMatch));
+    const { expand: _e, ...rest } = expanded as QueryOpts & { mode?: SearchMode };
+    return noteOps.searchNotes(this.db, query, rest);
   }
 
   /**

package/core/src/test-preload.ts

@@ -1,8 +1,53 @@
 // Isolate PARACHUTE_HOME so tests never touch the real ~/.parachute directory.
 // This must run before any `./config.ts` import resolves CONFIG_DIR.
+//
+// The override is UNCONDITIONAL, and that is the entire point. This file used
+// to read `if (!process.env.PARACHUTE_HOME)` — polite, and exactly backwards:
+// the dangerous case is an *inherited* PARACHUTE_HOME, because on a developer
+// box the inherited value is the live install. A machine whose shell profile
+// carries `export PARACHUTE_HOME="$HOME/.parachute"` (a normal thing to have —
+// it is also how parachute-hub launches the daemon) handed `bun test` a
+// pointer straight at the real vault data dir, and this guard stepped politely
+// aside. On 2026-08-22 two runs wrote ~158 real vault directories into a live
+// install — `tagscope-*`, `mint-*`, `retier-*`, `ledger-*`, plus a `solo`
+// vault from the mirror-routes tests.
+//
+// Nothing legitimate depends on the ambient value surviving. `config.ts`
+// re-reads `process.env.PARACHUTE_HOME` on every call (see the "Historical
+// note" above `configDirPath`), and every test that needs a particular home
+// either assigns it at run time or passes it explicitly to the child it
+// spawns. Docker and CI set PARACHUTE_HOME for the *server*, never for
+// `bun test`.
 import { mkdtempSync } from "fs";
-import { tmpdir } from "os";
+import { homedir, tmpdir } from "os";
 import { join } from "path";
-if (!process.env.PARACHUTE_HOME) {
-  process.env.PARACHUTE_HOME = mkdtempSync(join(tmpdir(), "parachute-test-home-"));
+
+const TEST_HOME = mkdtempSync(join(tmpdir(), "parachute-test-home-"));
+process.env.PARACHUTE_HOME = TEST_HOME;
+
+// Tripwire, and a live one: `mkdtempSync` builds on `tmpdir()`, which honors
+// TMPDIR. An operator or CI that points TMPDIR inside the parachute home
+// (`TMPDIR=~/.parachute/tmp` is not exotic) would have this file dutifully
+// create the suite's "isolated" home *inside the live install*, which is the
+// failure this preload exists to prevent, arrived at by another road. Assert
+// the temp home is neither the real home nor nested under it.
+//
+// The check on `process.env.PARACHUTE_HOME` itself is deliberately NOT here:
+// it was just assigned two lines up, so any such comparison is dead code that
+// reads as live defense. `configDirPath()` in `src/config.ts` carries the real
+// runtime tripwire, at the one function that resolves the root.
+const REAL_HOME = join(homedir(), ".parachute");
+if (TEST_HOME === REAL_HOME || TEST_HOME.startsWith(REAL_HOME + "/")) {
+  throw new Error(
+    `[test-preload] refusing to run the test suite: the temp home ${TEST_HOME} is inside ` +
+      `the live install at ${REAL_HOME} — check TMPDIR. Tests would create real vaults ` +
+      `there; that happened on 2026-08-22.`,
+  );
 }
+
+// No cleanup handler on purpose. `bun test` dispatches neither `exit` nor
+// `beforeExit` (verified on Bun 1.3.14 — a handler registered here never runs,
+// even on a clean green exit), so a cleanup hook would be a comment promising
+// something that does not happen. Each run therefore leaves one empty-ish
+// `parachute-test-home-*` under tmpdir(); the OS reaps them, and a dropping in
+// tmpdir is a rounding error next to a dropping in someone's real vault.

package/core/src/types.ts

@@ -188,6 +188,13 @@ export interface QueryOpts {
   hasBrokenLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  /**
+   * Exclude notes whose path matches any of these prefixes. Same matching
+   * as `pathPrefix` (`n.path LIKE prefix || '%'`, ASCII case-insensitive).
+   * Repeatable. A note with no path is not excluded (it isn't under the
+   * prefix). vault#628 — `.parachute/` system-space is the first client.
+   */
+  excludePathPrefix?: string[];
   /**
    * Filter by file extension. Pass a single extension (e.g. `"csv"`) or
    * an array (e.g. `["csv", "yaml", "json"]`). Extension is compared
@@ -504,8 +511,13 @@ export interface Store {
    * rather than silently returning `[]`. `sort` (vault#551): omitted stays
    * FTS5 relevance ranking (default); an explicit "asc"/"desc" switches to
    * `created_at` ordering. See `core/src/search-query.ts`.
+   *
+   * Every other `QueryOpts` filter (excludeTags, dateFrom/dateFilter, path,
+   * metadata, …) composes the same way `queryNotes` / `semanticSearch` do
+   * (vault#647). Unspecified `tagMatch` defaults to `"any"` so historical
+   * FTS tag semantics (a single IN (...)) stay put.
    */
-  searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode; mode?: SearchMode; sort?: "asc" | "desc" }): Promise<Note[]>;
+  searchNotes(query: string, opts?: QueryOpts & { mode?: SearchMode }): Promise<Note[]>;
   /**
    * Semantic search (EXPERIMENTAL — see `QueryOpts.nearText`/`semantic`).
    * The one invocation point for the store's `EmbeddingProvider`: embeds

package/core/src/wikilinks.test.ts

@@ -7,6 +7,7 @@ import {
   resolveWikilink,
   resolveWikilinkDetailed,
   resolveUnresolvedWikilinks,
+  queueUnresolvedLink,
   listUnresolvedWikilinks,
   getContentWikilinkWarnings,
   resolveOrQueueLink,
@@ -630,6 +631,18 @@ describe("delete → recreate re-resolves inbound wikilinks (LB6)", () => {
     expect(getUnresolvedLinksForNote(db, b.id)).toHaveLength(0);
   });
 
+  it("re-heals a non-ASCII title that differs only in case (vault#589 COLLATE NOCASE is ASCII-only)", async () => {
+    const source = await store.createNote("see [[CAFÉ]]", { path: "A" });
+    expect(getUnresolvedLinksForNote(db, source.id).map((r) => r.target_path ?? r.target)).toEqual(["CAFÉ"]);
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(0);
+
+    const target = await store.createNote("# café\n\nbody", { path: "people/cafe" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(target.id);
+    expect(getUnresolvedLinksForNote(db, source.id)).toHaveLength(0);
+  });
+
   // The completed sweep must NOT mis-resolve an AMBIGUOUS target — matching
   // write-time's "don't guess" contract. A pending [[John Doe]] is swept when
   // a same-titled note is created; if TWO notes already share that H1 by the
@@ -766,3 +779,47 @@ describe("ensureRelationshipColumn — crash-safe rebuild", () => {
     expect(links.some((l) => l.targetId === targetA!.id && l.relationship === "wikilink")).toBe(true);
   });
 });
+
+describe("deferred resolution — ID leg (vault#591)", () => {
+  it("heals an ID-valued pending row when the target note is later created", async () => {
+    const source = await store.createNote("src", { path: "Src" });
+    const futureId = "tgt-id-591";
+    queueUnresolvedLink(db, source.id, futureId, "reference");
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(0);
+
+    const target = await store.createNote("tgt", { id: futureId, path: "Tgt" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(target.id);
+    expect(links[0]!.relationship).toBe("reference");
+    expect(getUnresolvedLinksForNote(db, source.id)).toHaveLength(0);
+  });
+
+  // Watch-fail: a shared ID-first verify lets a decoy whose id equals the
+  // pending bracket text short-circuit resolveLinkTargetDetailed. The
+  // titled note's sweep then sees detail.note_id !== noteId and leaves the
+  // row queued forever. Write-time resolveWikilinkDetailed has no ID leg,
+  // so a fresh save would heal to the titled note.
+  it("does not let an ID-named decoy steal a pending wikilink from a later titled note", async () => {
+    await store.createNote("decoy body", { id: "shadow", path: "people/decoy" });
+    const source = await store.createNote("see [[shadow]]", { path: "Src" });
+    expect(getUnresolvedLinksForNote(db, source.id).map((l) => l.target)).toEqual(["shadow"]);
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(0);
+
+    const titled = await store.createNote("# shadow\n\nreal.", { path: "people/shadow" });
+    const links = await store.getLinks(source.id, { direction: "outbound" });
+    expect(links).toHaveLength(1);
+    expect(links[0]!.targetId).toBe(titled.id);
+    expect(links[0]!.relationship).toBe("wikilink");
+    expect(getUnresolvedLinksForNote(db, source.id)).toHaveLength(0);
+  });
+
+  it("does not heal a pending wikilink against a later note whose id equals the bracket text", async () => {
+    const source = await store.createNote("see [[foo591]]", { path: "Src" });
+    expect(getUnresolvedLinksForNote(db, source.id).map((l) => l.target)).toEqual(["foo591"]);
+
+    await store.createNote("unrelated", { id: "foo591", path: "elsewhere" });
+    expect(await store.getLinks(source.id, { direction: "outbound" })).toHaveLength(0);
+    expect(getUnresolvedLinksForNote(db, source.id).map((l) => l.target)).toEqual(["foo591"]);
+  });
+});

package/core/src/wikilinks.ts

@@ -624,26 +624,27 @@ function syncUnresolvedWikilinks(
  * (a structured link queued via {@link queueUnresolvedLink} backfills with
  * the caller's original relationship, not "wikilink").
  *
- * Deferred resolution now covers all four legs of
- * {@link resolveWikilinkDetailed}: exact path, basename, H1 title, and the
- * explicit `path.ext` form. (Caveat: the candidate pre-filter below matches the
- * title/ext legs via SQL `COLLATE NOCASE`, which case-folds ASCII only — a
- * non-ASCII title differing from the target only in letter case is missed at
- * the candidate stage and re-heals on the source's next save instead. Rare;
- * tracked as a follow-up.) Before this, the sweep matched a pending row to
- * the new note by PATH TEXT ONLY (`target_path = path OR path LIKE
- * '%/'||target_path`) — so a `[[John Doe]]` that resolved at write time via
- * the H1-title fallback (its note's displayed title differs from its path,
- * e.g. `people/jdoe`), or a `[[Foo.csv]]` that resolved via the extension
- * leg, silently never re-healed on a delete→recreate (the exact LB6 gap) and
+ * Deferred resolution covers all four legs of
+ * {@link resolveWikilinkDetailed} (exact path, basename, H1 title, explicit
+ * `path.ext`) plus, for structured-link pending rows, the ID leg of
+ * {@link resolveLinkTargetDetailed} (vault#591). Verify picks the resolver
+ * by `row.relationship` so a wikilink row cannot heal via ID. (Caveat: the
+ * candidate pre-filter below matches the title/ext legs via SQL
+ * `COLLATE NOCASE`, which case-folds ASCII only — a non-ASCII title
+ * differing from the target only in letter case is missed at the candidate
+ * stage and re-heals on the source's next save instead. Rare; tracked as a
+ * follow-up.) Before this, the sweep matched a pending row to the new note
+ * by PATH TEXT ONLY (`target_path = path OR path LIKE '%/'||target_path`)
+ * — so a `[[John Doe]]` that resolved at write time via the H1-title
+ * fallback (its note's displayed title differs from its path, e.g.
+ * `people/jdoe`), or a `[[Foo.csv]]` that resolved via the extension leg,
+ * silently never re-healed on a delete→recreate (the exact LB6 gap) and
  * more broadly never backfilled when the target note was created AFTER the
- * referencing note. Each candidate pending row is now VERIFIED through
- * `resolveWikilinkDetailed` against the current DB — a row is healed only
- * when its target string actually resolves to THIS note. An AMBIGUOUS target
- * (≥2 notes now share the path/title) resolves to neither and stays queued,
- * identical to write-time's "don't guess" contract — this also closes the
- * pre-existing asymmetry where the path-only sweep would link an ambiguous
- * `[[Foo]]` to whichever colliding note happened to be created.
+ * referencing note. An AMBIGUOUS target (≥2 notes now share the
+ * path/title) resolves to neither and stays queued, identical to
+ * write-time's "don't guess" contract — this also closes the pre-existing
+ * asymmetry where the path-only sweep would link an ambiguous `[[Foo]]` to
+ * whichever colliding note happened to be created.
  *
  * Returns the number of links resolved.
  */
@@ -666,19 +667,45 @@ export function resolveUnresolvedWikilinks(
   let rows: { source_id: string; target_path: string; relationship: string }[];
   try {
     // Candidate pre-filter: every pending row whose `target_path` COULD
-    // resolve to this note under any resolveWikilinkDetailed leg — exact
-    // path, basename (target is the last path segment), H1 title, or the
-    // `path.ext` form. A `null` bind (no H1 heading / no extension) makes its
-    // clause never match (`target_path = NULL` is NULL, i.e. falsy in SQL).
-    // The verify step below is what enforces correctness; this clause only
-    // BOUNDS how many rows reach the (title-fallback-scanning) resolver.
+    // resolve to this note under any resolveLinkTargetDetailed leg — exact
+    // path, basename (target is the last path segment), H1 title, the
+    // `path.ext` form, or a raw note ID (vault#591: typed `reference` fields
+    // and ID-form structured links). A `null` bind (no H1 heading / no
+    // extension) makes its clause never match (`target_path = NULL` is NULL,
+    // i.e. falsy in SQL). The verify step below is what enforces correctness;
+    // this clause only BOUNDS how many rows reach the resolver.
     rows = db.prepare(`
       SELECT source_id, target_path, relationship FROM unresolved_wikilinks
       WHERE target_path = ? COLLATE NOCASE
          OR ? LIKE '%/' || target_path
          OR target_path = ? COLLATE NOCASE
          OR target_path = ? COLLATE NOCASE
-    `).all(notePath, notePath, h1Title, pathDotExt) as typeof rows;
+         OR target_path = ?
+    `).all(notePath, notePath, h1Title, pathDotExt, noteId) as typeof rows;
+
+    // vault#589: SQLite COLLATE NOCASE is ASCII-only. `[[CAFÉ]]` vs H1
+    // `café` is excluded by the SQL pre-filter even though
+    // findNotesByTitle folds with JS toLowerCase. Union remaining pending
+    // rows whose target Unicode-folds equal to the H1; verify still
+    // decides. The path.ext fold is omitted: write-time's extension leg
+    // also uses COLLATE NOCASE on path, so a unicode-only path.ext miss
+    // would fail verify too. (`[[FOO.CSV]]` vs `foo.csv` is ASCII and
+    // already caught by the SQL clause.)
+    if (h1Title) {
+      const all = db.prepare(
+        "SELECT source_id, target_path, relationship FROM unresolved_wikilinks",
+      ).all() as typeof rows;
+      const seen = new Set(rows.map((r) => `${r.source_id}\0${r.target_path}\0${r.relationship}`));
+      const h1 = h1Title.toLowerCase();
+      for (const row of all) {
+        const key = `${row.source_id}\0${row.target_path}\0${row.relationship}`;
+        if (seen.has(key)) continue;
+        if (row.target_path.toLowerCase() === h1) {
+          rows.push(row);
+          seen.add(key);
+        }
+      }
+    }
   } catch {
     return 0; // Table doesn't exist
   }
@@ -694,10 +721,17 @@ export function resolveUnresolvedWikilinks(
     // target string actually resolves to THIS note now. A miss or an
     // ambiguous result leaves the row queued (surfaced as a visible broken
     // link, and re-tried on the next matching note create).
-    const detail = resolveWikilinkDetailed(db, row.target_path);
-    if (!detail.resolved || detail.note_id !== noteId) continue;
-
+    // Resolver is picked by relationship (vault#591): wikilink rows go
+    // through resolveWikilinkDetailed (write-time has no ID leg).
+    // Structured-link rows go through resolveLinkTargetDetailed
+    // (ID-then-path). A shared ID-first resolver over-heals `[[foo591]]`
+    // against a later note with that id, and lets a decoy whose id equals
+    // the bracket text steal a pending wikilink from a later titled note.
     const relationship = row.relationship || WIKILINK_REL;
+    const detail = relationship === WIKILINK_REL
+      ? resolveWikilinkDetailed(db, row.target_path)
+      : resolveLinkTargetDetailed(db, row.target_path);
+    if (!detail.resolved || detail.note_id !== noteId) continue;
     linkOps.createLink(db, row.source_id, noteId, relationship);
     resolved++;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/attachment-tickets.test.ts

@@ -431,6 +431,68 @@ describe("attachment tickets — download lifecycle", () => {
     expect(secondRes.status).toBe(404);
   });
 
+  test("spend Content-Type is extension-derived, not the caller-asserted row mime (vault#617)", async () => {
+    const vaultName = freshVault("tickets-download-mime");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+
+    const uploadMint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "photo.png",
+      size_bytes: 4,
+      mime_type: "text/html",
+    });
+    const uploadRes = await routeReq(
+      new Request(uploadMint.url, {
+        method: "PUT",
+        headers: { "content-type": "text/html" },
+        body: new Uint8Array([137, 80, 78, 71]),
+      }),
+    );
+    const attachment = (await uploadRes.json()) as any;
+    expect(attachment.mimeType).toBe("text/html");
+
+    const downloadMint = await callTool(vaultName, "request-attachment-download", {
+      attachment_id: attachment.id,
+    });
+    const downloadRes = await routeReq(new Request(downloadMint.url, { method: "GET" }));
+    expect(downloadRes.status).toBe(200);
+    expect(downloadRes.headers.get("content-type")).toBe("image/png");
+    expect(downloadRes.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(downloadMint.mime_type).toBe("image/png");
+  });
+
+  test("uncurated extension with caller-asserted text/html serves octet-stream (vault#617)", async () => {
+    const vaultName = freshVault("tickets-download-octet");
+    const store = getVaultStore(vaultName);
+    const note = await store.createNote("# T\n", { path: "t" });
+
+    const uploadMint = await callTool(vaultName, "request-attachment-upload", {
+      note: note.id,
+      filename: "payload.bin",
+      size_bytes: 4,
+      mime_type: "text/html",
+    });
+    const uploadRes = await routeReq(
+      new Request(uploadMint.url, {
+        method: "PUT",
+        headers: { "content-type": "text/html" },
+        body: new Uint8Array([10, 20, 30, 40]),
+      }),
+    );
+    expect(uploadRes.status).toBe(201);
+    const attachment = (await uploadRes.json()) as any;
+
+    const downloadMint = await callTool(vaultName, "request-attachment-download", {
+      attachment_id: attachment.id,
+    });
+    const downloadRes = await routeReq(new Request(downloadMint.url, { method: "GET" }));
+    expect(downloadRes.status).toBe(200);
+    expect(downloadRes.headers.get("content-type")).toBe("application/octet-stream");
+    expect(downloadRes.headers.get("x-content-type-options")).toBe("nosniff");
+    expect(downloadMint.mime_type).toBe("application/octet-stream");
+  });
+
   test("path confinement: an attachment row pointing outside assetsDir can't be walked to via a download ticket", async () => {
     const vaultName = freshVault("tickets-confinement");
     const store = getVaultStore(vaultName);