@openparachute/vault 0.7.2-rc.5 → 0.7.2-rc.7

package/core/src/core.test.ts

@@ -3,7 +3,7 @@ import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { initSchema } from "./schema.js";
-import { decodeCursor } from "./cursor.js";
+import { decodeCursor, timestampToMs } from "./cursor.js";
 import { traverseLinks } from "./links.js";
 import * as indexedFieldOps from "./indexed-fields.js";
 import { resolveLinkTarget } from "./wikilinks.js";
@@ -1493,11 +1493,15 @@ describe("queryNotes", async () => {
       await store.updateNote(b.id, { append: " edit" });
 
       // Pin each note's updated_at deterministically so the assertion isn't
-      // racing real wall-clock writes from the test harness.
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-01-15T00:00:00.000Z", a.id);
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-04-25T00:00:00.000Z", b.id);
+      // racing real wall-clock writes from the test harness. Mirror
+      // production (vault#586): EVERY write maintains `updated_at_ms` in
+      // lockstep with `updated_at` — the vault#585 fix compares the ms
+      // mirror, not the TEXT column, so a raw pin that only touched the
+      // TEXT column would silently stop affecting this filter.
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-01-15T00:00:00.000Z", Date.parse("2026-01-15T00:00:00.000Z"), a.id);
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", Date.parse("2026-04-25T00:00:00.000Z"), b.id);
 
       const results = await store.queryNotes({
         dateFilter: { field: "updated_at", from: "2026-04-01" },
@@ -1519,16 +1523,69 @@ describe("queryNotes", async () => {
     it("dateFilter on updated_at honors the upper-bound exclusive `to`", async () => {
       const a = await store.createNote("inside-window");
       const b = await store.createNote("after-window");
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-04-25T00:00:00.000Z", a.id);
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-05-15T00:00:00.000Z", b.id);
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", Date.parse("2026-04-25T00:00:00.000Z"), a.id);
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-05-15T00:00:00.000Z", Date.parse("2026-05-15T00:00:00.000Z"), b.id);
 
       const results = await store.queryNotes({
         dateFilter: { field: "updated_at", from: "2026-04-01", to: "2026-05-01" },
       });
       expect(results.map((n) => n.content)).toEqual(["inside-window"]);
     });
+
+    // ---- vault#585: date_filter on updated_at compares the ms mirror ----
+    //
+    // Simulates a post-vault#586-migration vault: `updated_at_ms` is
+    // correctly backfilled from the non-canonical stored `updated_at` TEXT
+    // via `timestampToMs` (exactly what `migrateToV26` does on import), but
+    // the TEXT column itself stays non-canonical — import stores frontmatter
+    // timestamps VERBATIM. Before vault#585, `date_filter` on `updated_at`
+    // still compared the RAW TEXT column lexicographically — wrong on these
+    // non-canonical forms even though the correct ms value already sat in
+    // `updated_at_ms`.
+    function pinNonCanonicalUpdatedAt(id: string, rawTimestamp: string) {
+      const ms = timestampToMs(rawTimestamp);
+      if (ms === null) throw new Error(`test fixture bug: unparseable timestamp ${rawTimestamp}`);
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run(rawTimestamp, ms, id);
+    }
+
+    it("dateFilter `from` on updated_at is correct against a space-form non-canonical timestamp (vault#585)", async () => {
+      // "2024-11-02 14:30:00" (space separator, no zone) is UTC-correct
+      // 14:30 on Nov 2 per timestampToMs — 4.5 hours AFTER the 10:00 bound,
+      // so it MUST be included. Lexicographic TEXT comparison disagrees:
+      // the space (0x20) sorts BEFORE 'T' (0x54), so the space-form string
+      // compares as LESS than the canonical `T`-separated bound on the same
+      // calendar day — the old TEXT-compare code wrongly EXCLUDED it.
+      const included = await store.createNote("space-form, after bound");
+      pinNonCanonicalUpdatedAt(included.id, "2024-11-02 14:30:00");
+      const excluded = await store.createNote("canonical, before bound");
+      pinNonCanonicalUpdatedAt(excluded.id, "2024-11-01T00:00:00.000Z");
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "updated_at", from: "2024-11-02T10:00:00.000Z" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["space-form, after bound"]);
+    });
+
+    it("dateFilter `to` on updated_at is correct against an offset non-canonical timestamp (vault#585)", async () => {
+      // "2024-11-02T21:00:00+13:00" is UTC-correct 08:00 on Nov 2 per
+      // timestampToMs (21:00 minus the 13-hour offset) — BEFORE the 10:00
+      // bound, so it MUST be included (`to` is the exclusive-upper `<`).
+      // Lexicographic TEXT comparison disagrees: the wall-clock hour "21"
+      // sorts AFTER the bound's "10" as a plain string, so the old
+      // TEXT-compare code wrongly EXCLUDED it.
+      const included = await store.createNote("offset, actually before bound");
+      pinNonCanonicalUpdatedAt(included.id, "2024-11-02T21:00:00+13:00");
+      const excluded = await store.createNote("canonical, after bound");
+      pinNonCanonicalUpdatedAt(excluded.id, "2024-11-02T15:00:00.000Z");
+
+      const results = await store.queryNotes({
+        dateFilter: { field: "updated_at", to: "2024-11-02T10:00:00.000Z" },
+      });
+      expect(results.map((n) => n.content)).toEqual(["offset, actually before bound"]);
+    });
   });
 
   it("sorts ascending and descending", async () => {
@@ -2114,6 +2171,52 @@ describe("queryNotes", async () => {
       expect(store.queryNotes({ orderBy: "foo" })).rejects.toThrow(/not indexed/);
     });
 
+    // ---- vault#585: order_by "updated_at" is a pseudo-field like link_count ----
+    //
+    // Before vault#585, `order_by: "updated_at"` always threw
+    // FIELD_NOT_INDEXED — `updated_at` is a native `notes` column, not a
+    // declared-indexed metadata field, and the generic order_by branch
+    // gated every field (including this one) through `requireIndexedField`
+    // (see the 2026-06 MCP-tool-description-audit CHANGELOG entry — this
+    // was documented, intentional behavior, not a silent mis-sort). This
+    // test proves the NEW capability lands correct from day one: ordering
+    // on the integer `updated_at_ms` mirror (vault#586), immune to the
+    // TEXT-lexicographic trap a plain `ORDER BY updated_at` would fall
+    // into — a space-form timestamp's ' ' (0x20) always sorts BEFORE any
+    // canonical `T`-separated timestamp's 'T' (0x54) on the same calendar
+    // day, regardless of the actual wall-clock instant either encodes.
+    it("order_by: \"updated_at\" sorts correctly across canonical + non-canonical timestamps (vault#585)", async () => {
+      const p = await store.createNote("P earliest (canonical)");
+      const q = await store.createNote("Q middle (space-form, non-canonical)");
+      const r = await store.createNote("R latest (canonical)");
+      const pin = (id: string, raw: string) => {
+        const ms = timestampToMs(raw);
+        if (ms === null) throw new Error(`test fixture bug: unparseable timestamp ${raw}`);
+        db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?").run(raw, ms, id);
+      };
+      // True chronological order: P (08:00) < Q (12:00) < R (16:00). Q's
+      // space-form TEXT ("2024-11-02 12:00:00") sorts BEFORE P's canonical
+      // TEXT ("2024-11-02T08:00:00.000Z") under a plain string compare
+      // (' ' < 'T'), which is exactly backwards.
+      pin(p.id, "2024-11-02T08:00:00.000Z");
+      pin(q.id, "2024-11-02 12:00:00");
+      pin(r.id, "2024-11-02T16:00:00.000Z");
+
+      const asc = await store.queryNotes({ orderBy: "updated_at", sort: "asc" });
+      expect(asc.map((n) => n.content)).toEqual([
+        "P earliest (canonical)",
+        "Q middle (space-form, non-canonical)",
+        "R latest (canonical)",
+      ]);
+
+      const desc = await store.queryNotes({ orderBy: "updated_at", sort: "desc" });
+      expect(desc.map((n) => n.content)).toEqual([
+        "R latest (canonical)",
+        "Q middle (space-form, non-canonical)",
+        "P earliest (canonical)",
+      ]);
+    });
+
     it("unknown operator throws UNKNOWN_OPERATOR with supported-op list", async () => {
       await seedIndexedPriorities();
       expect(

package/core/src/mcp.ts

@@ -419,7 +419,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
           last_updated_by: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write was attributed to this principal. Exact match; indexed." },
           created_via: { type: "string", description: "Write-attribution filter (vault#298): only notes FIRST written through this interface/channel — e.g. `mcp`, `surface:<name>`, `agent:<id>`, `operator`, `api`. Exact match; indexed." },
           last_updated_via: { type: "string", description: "Write-attribution filter (vault#298): only notes whose MOST RECENT write came through this interface/channel. Exact match; indexed." },
-          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. The special value `link_count` sorts by link DEGREE (both-directions raw row count) — no declaration needed — matching the `include_link_count` field for every note. Direction is taken from `sort` (default 'asc'); `created_at` is appended as a stable tiebreaker." },
+          order_by: { type: "string", description: "Sort by an indexed metadata field instead of `created_at`. Field must be declared `indexed: true`; errors otherwise. Two special values need no declaration: `link_count` sorts by link DEGREE (both-directions raw row count), matching the `include_link_count` field for every note; `updated_at` (vault#585) sorts on the integer `updated_at_ms` mirror column — correct on non-canonical/imported timestamps — with `id` as the tiebreaker. Direction is taken from `sort` (default 'asc'); for other fields `created_at` is appended as a stable tiebreaker." },
           date_from: { type: "string", description: "Start date (ISO, inclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', from }`." },
           date_to: { type: "string", description: "End date (ISO, exclusive). Filters on `created_at` (vault ingestion time). Shorthand for `date_filter: { field: 'created_at', to }`." },
           date_filter: {

package/core/src/notes.ts

@@ -905,6 +905,50 @@ function validateIsoDateValue(field: string, value: string): void {
   }
 }
 
+/**
+ * Resolve a `date_filter` bound on the `updated_at` field to a millisecond
+ * epoch, for comparison against the integer `n.updated_at_ms` mirror column
+ * instead of the TEXT `n.updated_at` (vault#585 — the same TEXT-vs-ms class
+ * of bug vault#586 closed for the cursor keyset: a non-canonical stored
+ * timestamp — space-form, offset, no-`Z` — sorts/compares WRONG
+ * lexicographically).
+ *
+ * Runs `validateIsoDateValue` first — same loud `INVALID_QUERY` contract a
+ * caller already gets for a malformed bound — then converts with
+ * `timestampToMs` (the UTC-correct parse `updated_at_ms` itself was
+ * backfilled with). `timestampToMs` returning `null` here would mean the
+ * bound matched `Date.parse`'s more permissive grammar (e.g. a non-ISO
+ * locale string) but not `timestampToMs`'s stricter one — a defensive
+ * fallback, not an expected path for any bound `validateIsoDateValue`'s own
+ * error message advertises as valid ("2026-07-09" / full ISO timestamps).
+ * Surfaces the SAME `INVALID_QUERY` shape rather than binding `NaN`.
+ *
+ * One deliberate tightening for `updated_at` only: an ISO *shorthand* bound
+ * like `"2024"` or `"2024-06"` passes `Date.parse` (so `validateIsoDateValue`
+ * accepted it, and on a canonical vault it compared correctly via lexicographic
+ * prefix) but fails `timestampToMs`'s stricter `TIMESTAMP_RE`, so it now
+ * returns `INVALID_QUERY` here — loud, not silent. `date_filter` on
+ * `created_at` (no ms mirror) still accepts the shorthand; the asymmetry is
+ * intentional (ambiguous precision on a range bound).
+ */
+function resolveUpdatedAtBoundMs(field: string, value: string): number {
+  validateIsoDateValue(field, value);
+  const ms = timestampToMs(value);
+  if (ms === null) {
+    throw new QueryError(
+      `invalid date value for "${field}": ${JSON.stringify(value)} — must be an ISO-8601 date/timestamp (e.g. "2026-07-09" or "2026-07-09T00:00:00.000Z").`,
+      "INVALID_QUERY",
+      {
+        error_type: "invalid_query",
+        field,
+        got: value,
+        hint: "pass an ISO-8601 date or timestamp",
+      },
+    );
+  }
+  return ms;
+}
+
 /**
  * Build the shared WHERE-clause conditions + bound params for the filter
  * surface both `queryNotes` and `aggregateNotes` apply: tag membership
@@ -1169,15 +1213,17 @@ function buildFilterConditions(db: Database, opts: QueryOpts): { conditions: str
     const filter = opts.dateFilter!;
     const field = filter.field ?? "created_at";
     let column: string;
+    // vault#585: `updated_at` compares against the integer `updated_at_ms`
+    // mirror (vault#586), not the TEXT `n.updated_at` — a TEXT compare
+    // mis-filters non-canonical rows (space-form / offset / no-`Z`) the same
+    // way the pre-v26 cursor keyset did. `created_at` has no ms mirror and
+    // stays a TEXT compare (out of scope — tracked separately, see vault#585
+    // follow-up note in the fix PR).
+    const isUpdatedAt = field === "updated_at";
     if (field === "created_at") {
       column = "n.created_at";
-    } else if (field === "updated_at") {
-      // NOTE (vault#586 follow-up): this range filter compares the TEXT
-      // `updated_at`, which is inconsistent on non-canonical rows the same way
-      // the cursor keyset was pre-v26. Cursor pagination moved to the integer
-      // `updated_at_ms` column; `date_filter`/`order_by`/export `--since` still
-      // read the string and are tracked separately. Behavior unchanged here.
-      column = "n.updated_at";
+    } else if (isUpdatedAt) {
+      column = "n.updated_at_ms";
     } else {
       // Re-uses the same indexed-field gate as `metadata` operator queries
       // and `orderBy` so the error message and contract are consistent.
@@ -1185,14 +1231,24 @@ function buildFilterConditions(db: Database, opts: QueryOpts): { conditions: str
       column = `"meta_${field}"`;
     }
     if (filter.from !== undefined) {
-      validateIsoDateValue(field === "created_at" ? "date_filter.from" : `date_filter.from (${field})`, filter.from);
+      const label = field === "created_at" ? "date_filter.from" : `date_filter.from (${field})`;
       conditions.push(`${column} >= ?`);
-      params.push(filter.from);
+      if (isUpdatedAt) {
+        params.push(resolveUpdatedAtBoundMs(label, filter.from));
+      } else {
+        validateIsoDateValue(label, filter.from);
+        params.push(filter.from);
+      }
     }
     if (filter.to !== undefined) {
-      validateIsoDateValue(field === "created_at" ? "date_filter.to" : `date_filter.to (${field})`, filter.to);
+      const label = field === "created_at" ? "date_filter.to" : `date_filter.to (${field})`;
       conditions.push(`${column} < ?`);
-      params.push(filter.to);
+      if (isUpdatedAt) {
+        params.push(resolveUpdatedAtBoundMs(label, filter.to));
+      } else {
+        validateIsoDateValue(label, filter.to);
+        params.push(filter.to);
+      }
     }
   } else if (hasLegacyDate) {
     if (opts.dateFrom) {
@@ -1316,6 +1372,18 @@ export function queryNotes(db: Database, opts: QueryOpts, _outUpdatedAtMs?: Map<
     // without it, two notes sharing an `updated_at_ms` would be at the mercy
     // of SQLite's row order and the next page could miss or duplicate one.
     orderBy = "n.updated_at_ms ASC, n.id ASC";
+  } else if (opts.orderBy === "updated_at") {
+    // `updated_at` is a pseudo-field like `link_count` below — it's a native
+    // notes column, not a declared-indexed metadata field, so it bypasses
+    // `requireIndexedField` (vault#585). Prior to this, `order_by:
+    // "updated_at"` always 400'd FIELD_NOT_INDEXED (a documented, intentional
+    // reject — see the 2026-06 MCP-tool-description-audit CHANGELOG entry);
+    // it never silently sorted on the TEXT column. Ordering on the integer
+    // `updated_at_ms` mirror (vault#586) from the start means this new
+    // capability is UTC-correct on day one — no TEXT-lexicographic pass ever
+    // shipped for it. `id` is the explicit tiebreak for stable ordering when
+    // two notes share a millisecond, matching the cursor keyset's tiebreak.
+    orderBy = `n.updated_at_ms ${direction}, n.id ${direction}`;
   } else if (opts.orderBy === "link_count") {
     // `link_count` is a pseudo-field — like `created_at`/`updated_at` in the
     // dateFilter block above, it bypasses `requireIndexedField` (it's not a

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

@@ -24,6 +24,7 @@ import { join } from "path";
 import { tmpdir } from "os";
 
 import { SqliteStore } from "./store.js";
+import { timestampToMs } from "./cursor.js";
 import { getIndexedField } from "./indexed-fields.js";
 import { buildVaultProjection } from "./vault-projection.js";
 import {
@@ -593,6 +594,48 @@ describe("exportVaultToDir", async () => {
     }
   });
 
+  it("respects --since correctly on non-canonical `updated_at` (vault#585)", async () => {
+    // Independent db/store pair (not the describe's shared `store`) so the
+    // test can reach the raw `updated_at` / `updated_at_ms` columns
+    // directly — same pattern used elsewhere in this file (pruneOrphans,
+    // case-collision describes).
+    const db = new Database(":memory:");
+    const localStore = new SqliteStore(db);
+
+    const included = await localStore.createNote("space-form, after since", { id: "inc", path: "inc" });
+    const excluded = await localStore.createNote("canonical, before since", { id: "exc", path: "exc" });
+
+    // "2024-11-02 14:30:00" (space-form, no zone) is UTC-correct 14:30 on
+    // Nov 2 per timestampToMs — AFTER the 10:00 `since` bound below, so it
+    // MUST be exported. A TEXT `>=` comparison (the pre-vault#585 behavior)
+    // disagrees: the space (0x20) sorts BEFORE 'T' (0x54), so this string
+    // compares as LESS than the canonical `since` bound on the same
+    // calendar day — the old code wrongly EXCLUDED it from the incremental
+    // export.
+    const includedRaw = "2024-11-02 14:30:00";
+    const excludedRaw = "2024-11-01T00:00:00.000Z";
+    const includedMs = timestampToMs(includedRaw);
+    const excludedMs = timestampToMs(excludedRaw);
+    if (includedMs === null || excludedMs === null) {
+      throw new Error("test fixture bug: unparseable timestamp");
+    }
+    db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+      .run(includedRaw, includedMs, included.id);
+    db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+      .run(excludedRaw, excludedMs, excluded.id);
+
+    const outDir = join(tmpBase, "since-non-canonical");
+    const stats = await exportVaultToDir(localStore, {
+      outDir,
+      since: "2024-11-02T10:00:00.000Z",
+      exportedAt: "2026-05-12T00:00:00.000Z",
+    });
+
+    expect(stats.filtered_by_since).toBe(true);
+    expect(existsSync(join(outDir, "inc.md"))).toBe(true);
+    expect(existsSync(join(outDir, "exc.md"))).toBe(false);
+  });
+
   it("re-export with same exportedAt produces byte-identical output (idempotency)", async () => {
     await store.createNote("body", { id: "n1", path: "Inbox/x", tags: ["b", "a"] });
     await store.upsertTagSchema("a", { description: "tag-a" });

package/core/src/portable-md.ts

@@ -78,6 +78,7 @@ 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";
+import { timestampToMs } from "./cursor.js";
 
 // ---------------------------------------------------------------------------
 // Format constants
@@ -1627,9 +1628,40 @@ function disambiguateFilename(path: string, extension: string, noteId: string):
   return `${path}__${idShort}.${extension}`;
 }
 
+/**
+ * Incremental-export inclusion test (vault#585). Compares millisecond
+ * epochs via {@link timestampToMs} — the SAME UTC-correct parse the
+ * `notes.updated_at_ms` column mirror was backfilled with (vault#586
+ * `migrateToV26`) — instead of a TEXT `>=` comparison on the stored ISO
+ * string. Import stores frontmatter timestamps VERBATIM, so an
+ * aged/imported vault routinely carries non-canonical `updated_at`
+ * (space-separated `2024-11-02 14:30:00`, a `+02:00` offset, no trailing
+ * `Z`); those sort WRONG against a canonical `.toISOString()` bound under
+ * plain string comparison, silently including or excluding notes from an
+ * incremental export.
+ *
+ * The fallback chain mirrors `migrateToV26`'s exactly — `updatedAt` →
+ * `createdAt` → the `0` (epoch) sentinel — so this function's answer for
+ * any given note is identical to what filtering on the real
+ * `updated_at_ms` column would produce; a note whose stored timestamp is
+ * genuinely unparseable sorts as "ancient" and drops out of an
+ * incremental export rather than being (wrongly) always-included or
+ * always-excluded by an arbitrary string comparison.
+ *
+ * `since` is caller input (CLI `--since`), already validated upstream
+ * (`Date.parse`-checked in `src/cli.ts` before this is ever reached from
+ * the CLI) — `timestampToMs` is tried first for UTC-correctness on the
+ * same non-canonical shapes, falling back to `Date.parse` for any exotic
+ * shape `timestampToMs`'s stricter grammar doesn't cover. A genuinely
+ * unparseable `since` (only reachable by calling the engine directly,
+ * bypassing the CLI guard) yields `NaN`, against which `>=` is always
+ * `false` — every note is excluded rather than the prior TEXT compare's
+ * arbitrary (and possibly all-inclusive) result.
+ */
 function shouldIncludeForSince(note: Note, since: string): boolean {
-  const stamp = note.updatedAt ?? note.createdAt;
-  return stamp >= since;
+  const stampMs = timestampToMs(note.updatedAt) ?? timestampToMs(note.createdAt) ?? 0;
+  const sinceMs = timestampToMs(since) ?? Date.parse(since);
+  return stampMs >= sinceMs;
 }
 
 // ---------------------------------------------------------------------------

package/core/src/types.ts

@@ -237,6 +237,14 @@ export interface QueryOpts {
   // raw row count — using the same directional-sum definition as the
   // `linkCount` response field, so the sort key equals the field value for
   // every note (self-loops included). See `queryNotes`/`getLinkCounts`.
+  //
+  // The pseudo-field `updated_at` is also special-cased (vault#585): it
+  // orders on the integer `notes.updated_at_ms` mirror column (vault#586),
+  // NOT the TEXT `updated_at`, with `id` appended as the tiebreaker instead
+  // of `created_at` — a TEXT sort mis-orders non-canonical stored timestamps
+  // (space-form / offset / no-`Z`) the same way the pre-v26 cursor keyset
+  // did. `created_at` itself has no ms mirror and is not special-cased here
+  // (its default/no-`orderBy` sort still reads the TEXT column).
   orderBy?: string;
   limit?: number;
   offset?: number;

package/package.json

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

package/src/routes.ts

@@ -4255,7 +4255,30 @@ async function handleRetryLegacyInBody(
 // existing importers are unaffected.
 // ---------------------------------------------------------------------------
 
-const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
+export const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100MB
+
+/**
+ * Transport-level `Bun.serve` `maxRequestBodySize` ceiling (vault#588 FIX 2).
+ *
+ * The app-level caps above (`MAX_JSON_BODY_BYTES` 10MB, `MAX_UPLOAD_BYTES`
+ * 100MB) only run AFTER the transport has already buffered the body: the
+ * `Content-Length` pre-check in `parseJsonBody` short-circuits early, but a
+ * chunked request with no `Content-Length` header falls through to the
+ * post-parse backstop — which still means Bun buffered the whole thing into
+ * memory first. Bun's *default* `maxRequestBodySize` (128MB) happened to sit
+ * above `MAX_UPLOAD_BYTES` and so never bit in practice, but it was never
+ * actually configured — an accident of the default, not a deliberate
+ * ceiling wired to this codebase's own limits.
+ *
+ * Set explicitly here so the ceiling is legible and reconciled: it MUST be
+ * >= `MAX_UPLOAD_BYTES` (a legitimate max-size attachment upload must not be
+ * rejected at the transport layer before `/upload`'s own 100MB check ever
+ * runs) with headroom for multipart overhead (boundary delimiters, per-part
+ * headers — a few hundred bytes in practice, but the 20MB margin is
+ * generous rather than exact). `MAX_JSON_BODY_BYTES` (10MB) is well under
+ * `MAX_UPLOAD_BYTES`, so it never drives this number.
+ */
+export const MAX_REQUEST_BODY_BYTES = MAX_UPLOAD_BYTES + 20 * 1024 * 1024; // 120MB
 
 // Storage upload policy: DENY-LIST (vault#517). A knowledge vault stores
 // arbitrary files — ebooks, office docs, datasets, archives, binaries — so we
@@ -4359,7 +4382,31 @@ export async function handleStorage(
   const assets = assetsDir(vault);
 
   if (req.method === "POST" && path === "/upload") {
-    const form = await req.formData();
+    // vault#588 FIX 1 — `req.formData()` throws on a malformed/non-multipart
+    // body (bad boundary, truncated body, wrong Content-Type entirely). Left
+    // uncaught, that throw escapes to server.ts's generic top-level catch: a
+    // 500 with no `error_type` — the multipart-transport analog of the
+    // `req.json()` gap LB7 fixed for the JSON routes (`parseJsonBody` above).
+    // Catch it here and return the same `invalid_request` taxonomy entry
+    // LB7b uses for "syntactically-parseable-transport but wrong/unusable
+    // shape" (see docs/HTTP_API.md's error-taxonomy table) rather than
+    // minting a new `invalid_form` type for what's ultimately the same bucket.
+    // Typed off `req.formData()`'s own return, not the DOM lib `FormData`
+    // global — `req: Request` resolves through undici's ambient types here,
+    // whose `FormData` isn't structurally assignable to lib.dom's.
+    let form: Awaited<ReturnType<typeof req.formData>>;
+    try {
+      form = await req.formData();
+    } catch {
+      return json(
+        {
+          error: "Request body must be valid multipart/form-data",
+          error_type: "invalid_request",
+          hint: "expected a multipart/form-data body with a `file` field",
+        },
+        400,
+      );
+    }
     const file = form.get("file");
     if (!(file instanceof File)) {
       return json({ error: "file is required", error_type: "missing_required_field", field: "file" }, 400);

package/src/server.ts

@@ -27,7 +27,7 @@ import { loadVaultTriggers } from "./triggers-api.ts";
 import { route } from "./routing.ts";
 import { startTranscriptionWorker, registerTranscriptionHook, type TranscriptionWorker } from "./transcription-worker.ts";
 import { setTranscriptionWorker } from "./transcription-registry.ts";
-import { assetsDir } from "./routes.ts";
+import { assetsDir, MAX_REQUEST_BODY_BYTES } from "./routes.ts";
 import { resolveScribeAuthToken, ensureScribeBearer } from "./scribe-env.ts";
 import { getCachedScribeUrl } from "./scribe-discovery.ts";
 import { TranscribeCppProvider } from "./transcription/providers/transcribe-cpp.ts";
@@ -502,6 +502,14 @@ const server = Bun.serve({
   port,
   hostname,
   idleTimeout: 120, // seconds — webhook triggers can take a while
+  // vault#588 FIX 2 — explicit transport-level body-size ceiling. Without
+  // this, Bun's *default* maxRequestBodySize (128MB) is the only backstop
+  // for a chunked request with no Content-Length header (the app-level JSON
+  // cap in parseJsonBody's post-parse branch still buffers the full body
+  // first). MAX_REQUEST_BODY_BYTES is MAX_UPLOAD_BYTES (100MB) + headroom —
+  // see its doc comment in routes.ts for the reconciliation with the
+  // /upload and JSON-body app-level caps.
+  maxRequestBodySize: MAX_REQUEST_BODY_BYTES,
   websocket: subscribeWs.handlers,
   async fetch(req, server) {
     const url = new URL(req.url);

package/src/storage.test.ts

@@ -14,7 +14,7 @@
  */
 
 import { describe, test, expect, beforeAll, afterAll } from "bun:test";
-import { rmSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { rmSync, existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
 import { Database } from "bun:sqlite";
@@ -30,7 +30,7 @@ const testDir = join(
 process.env.PARACHUTE_HOME = testDir;
 process.env.ASSETS_DIR = join(testDir, "assets");
 
-const { handleStorage } = await import("./routes.ts");
+const { handleStorage, MAX_UPLOAD_BYTES, MAX_REQUEST_BODY_BYTES } = await import("./routes.ts");
 const { expandTokenTagScope } = await import("./tag-scope.ts");
 
 // The upload-allowlist tests never touch the store (POST /upload writes to
@@ -176,6 +176,126 @@ describe("storage upload allowlist", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// vault#588 FIX 1 — a malformed/non-multipart POST /upload body used to
+// throw uncaught out of `req.formData()`, escaping to server.ts's generic
+// top-level catch: a 500 with no `error_type`. Same class LB7 (vault.test.ts)
+// fixed for `req.json()` on the JSON-bodied mutating routes, applied to the
+// multipart transport. Every assertion here MUST fail without the fix.
+// ---------------------------------------------------------------------------
+describe("storage upload — malformed multipart body (vault#588 FIX 1)", () => {
+  test("garbage body + a multipart Content-Type header -> 400 invalid_request, not 500", async () => {
+    const req = new Request("http://localhost:1940/storage/upload", {
+      method: "POST",
+      body: "not a valid multipart body at all",
+      headers: { "Content-Type": "multipart/form-data; boundary=----doesNotMatchBody" },
+    });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("invalid_request");
+  });
+
+  test("plain-text body with no multipart Content-Type at all -> 400 invalid_request, not 500", async () => {
+    const req = new Request("http://localhost:1940/storage/upload", {
+      method: "POST",
+      body: "just some text, not multipart",
+      headers: { "Content-Type": "text/plain" },
+    });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("invalid_request");
+  });
+
+  test("empty body -> 400 invalid_request, not 500", async () => {
+    const req = new Request("http://localhost:1940/storage/upload", {
+      method: "POST",
+      body: "",
+      headers: { "Content-Type": "multipart/form-data; boundary=----empty" },
+    });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("invalid_request");
+  });
+
+  test("well-formed multipart form MISSING the `file` field -> 400 missing_required_field (unchanged, not a TypeError)", async () => {
+    const form = new FormData();
+    form.set("not_file", "some value");
+    const req = new Request("http://localhost:1940/storage/upload", { method: "POST", body: form });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string; field: string };
+    expect(body.error_type).toBe("missing_required_field");
+    expect(body.field).toBe("file");
+  });
+
+  test("a well-formed upload still succeeds (regression — the catch doesn't swallow the happy path)", async () => {
+    const res = await handleStorage(uploadRequest("still-works.pdf", "application/pdf"), "/upload", "default", uploadStore);
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { mimeType: string };
+    expect(body.mimeType).toBe("application/pdf");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// vault#588 FIX 2 — explicit Bun.serve `maxRequestBodySize` transport ceiling.
+// The JSON-body cap (MAX_JSON_BODY_BYTES) only gates AFTER the transport
+// already buffered the body when Content-Length is absent (chunked
+// requests); before this fix, the only backstop was Bun's unconfigured
+// default (128MB). MAX_REQUEST_BODY_BYTES must sit >= MAX_UPLOAD_BYTES (the
+// /upload app-level cap) with headroom, or a legitimate max-size attachment
+// upload would be rejected at the transport layer before /upload's own
+// 100MB check ever runs. These pin the reconciliation and the wiring;
+// see routes.ts's MAX_REQUEST_BODY_BYTES doc comment for the full rationale.
+// ---------------------------------------------------------------------------
+describe("transport-level request-body ceiling (vault#588 FIX 2)", () => {
+  test("MAX_REQUEST_BODY_BYTES is comfortably >= MAX_UPLOAD_BYTES (never caps a legitimate attachment below its own app-level limit)", () => {
+    expect(MAX_UPLOAD_BYTES).toBe(100 * 1024 * 1024);
+    expect(MAX_REQUEST_BODY_BYTES).toBeGreaterThanOrEqual(MAX_UPLOAD_BYTES);
+    // Pin the chosen ceiling (100MB upload cap + 20MB multipart-overhead
+    // headroom = 120MB) so a future edit that silently narrows it fails loudly.
+    expect(MAX_REQUEST_BODY_BYTES).toBe(120 * 1024 * 1024);
+  });
+
+  test("server.ts wires maxRequestBodySize to MAX_REQUEST_BODY_BYTES on the Bun.serve config", () => {
+    // A config-level assertion (per vault#588's own guidance — a real
+    // >MAX_REQUEST_BODY_BYTES streaming test isn't worth the fixture cost).
+    // server.ts's `Bun.serve({...})` is a module-level side effect (it boots
+    // the real listener on import), so we can't import it in-test; read the
+    // source instead to confirm the constant is actually wired in, not just
+    // defined and forgotten.
+    const serverSrc = readFileSync(join(import.meta.dir, "server.ts"), "utf8");
+    expect(serverSrc).toMatch(/import\s*\{[^}]*MAX_REQUEST_BODY_BYTES[^}]*\}\s*from\s*"\.\/routes\.ts"/);
+    expect(serverSrc).toMatch(/maxRequestBodySize:\s*MAX_REQUEST_BODY_BYTES/);
+  });
+
+  test("a legitimate upload at exactly MAX_UPLOAD_BYTES still succeeds (not capped below its own limit)", async () => {
+    const bytes = new Uint8Array(MAX_UPLOAD_BYTES);
+    const file = new File([bytes], "max-size.bin", { type: "application/octet-stream" });
+    const form = new FormData();
+    form.set("file", file);
+    const req = new Request("http://localhost:1940/storage/upload", { method: "POST", body: form });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { size: number };
+    expect(body.size).toBe(MAX_UPLOAD_BYTES);
+  });
+
+  test("one byte over MAX_UPLOAD_BYTES still rejects at the app-level gate (413 file_too_large, unaffected by the transport ceiling)", async () => {
+    const bytes = new Uint8Array(MAX_UPLOAD_BYTES + 1);
+    const file = new File([bytes], "over-size.bin", { type: "application/octet-stream" });
+    const form = new FormData();
+    form.set("file", file);
+    const req = new Request("http://localhost:1940/storage/upload", { method: "POST", body: form });
+    const res = await handleStorage(req, "/upload", "default", uploadStore);
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as { error_type: string };
+    expect(body.error_type).toBe("file_too_large");
+  });
+});
+
 // ---------------------------------------------------------------------------
 // GET byte-serve tag-scope enforcement (C0 adversarial-audit finding).
 //

package/src/vault.test.ts

@@ -2226,10 +2226,13 @@ describe("HTTP /notes", async () => {
     const a = await store.createNote("untouched", { id: "ua", path: "ua" });
     const b = await store.createNote("modified", { id: "ub", path: "ub" });
     // Bump b's updated_at into the test window, leave a's at its createdAt.
-    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-      .run("2026-01-15T00:00:00.000Z", a.id);
-    db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-      .run("2026-04-25T00:00:00.000Z", b.id);
+    // Pin BOTH `updated_at` and `updated_at_ms` — mirrors production
+    // (vault#586: every real write keeps them in lockstep) — the vault#585
+    // fix compares the ms mirror, not the TEXT column.
+    db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+      .run("2026-01-15T00:00:00.000Z", Date.parse("2026-01-15T00:00:00.000Z"), a.id);
+    db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+      .run("2026-04-25T00:00:00.000Z", Date.parse("2026-04-25T00:00:00.000Z"), b.id);
 
     const res = await handleNotes(
       mkReq("GET", "/notes?meta[updated_at][gte]=2026-04-01&include_content=true"),
@@ -3370,10 +3373,11 @@ describe("HTTP /notes", async () => {
     test("`meta[updated_at][gte]=…` routes to dateFilter on n.updated_at", async () => {
       const a = await store.createNote("untouched");
       const b = await store.createNote("modified");
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-01-15T00:00:00.000Z", a.id);
-      db.prepare("UPDATE notes SET updated_at = ? WHERE id = ?")
-        .run("2026-04-25T00:00:00.000Z", b.id);
+      // Pin BOTH columns (vault#585/#586 — see the identical note above).
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-01-15T00:00:00.000Z", Date.parse("2026-01-15T00:00:00.000Z"), a.id);
+      db.prepare("UPDATE notes SET updated_at = ?, updated_at_ms = ? WHERE id = ?")
+        .run("2026-04-25T00:00:00.000Z", Date.parse("2026-04-25T00:00:00.000Z"), b.id);
       const res = await handleNotes(
         mkReq("GET", "/notes?meta[updated_at][gte]=2026-04-01&include_content=true"),
         store,