@openparachute/vault 0.7.2-rc.7 → 0.7.3-rc.1

package/core/src/core.test.ts

@@ -3910,6 +3910,78 @@ describe("MCP tools", async () => {
     expect(result.updatedAt).toBe(note.updatedAt);
   });
 
+  describe("metadata is always present on the wire (V1.1)", () => {
+    it("a note created with no metadata reads back with an empty-object `metadata` key, not an absent one", async () => {
+      const note = await store.createNote("No metadata here");
+      expect("metadata" in note).toBe(true);
+      expect(note.metadata).toEqual({});
+      // The real acid test: does the key survive a JSON round-trip, or does
+      // `JSON.stringify` drop it because it's `undefined`?
+      expect(JSON.parse(JSON.stringify(note))).toHaveProperty("metadata", {});
+
+      const fetched = await store.getNote(note.id);
+      expect(fetched).toHaveProperty("metadata", {});
+      expect(JSON.parse(JSON.stringify(fetched))).toHaveProperty("metadata", {});
+
+      // `tags` has always been unconditionally present ([]) — confirm that
+      // invariant still holds alongside the metadata fix.
+      expect(note.tags).toEqual([]);
+    });
+
+    it("a note whose metadata was explicitly written as {} also reads back with metadata: {}", async () => {
+      const note = await store.createNote("Explicit empty metadata", { metadata: {} });
+      expect(note.metadata).toEqual({});
+      const fetched = await store.getNote(note.id);
+      expect(fetched!.metadata).toEqual({});
+    });
+
+    it("a note WITH real metadata is unchanged by the fix", async () => {
+      const note = await store.createNote("Has metadata", { metadata: { source: "import", version: 2 } });
+      expect(note.metadata).toEqual({ source: "import", version: 2 });
+      const fetched = await store.getNote(note.id);
+      expect(fetched!.metadata).toEqual({ source: "import", version: 2 });
+    });
+
+    it("queryNotes list results carry metadata: {} on metadata-less notes", async () => {
+      await store.createNote("List entry, no metadata");
+      const results = await store.queryNotes({});
+      expect(results.length).toBeGreaterThan(0);
+      for (const r of results) {
+        expect(r).toHaveProperty("metadata", {});
+      }
+    });
+
+    it("searchNotes results carry metadata: {} on metadata-less notes", async () => {
+      await store.createNote("Findable via search, no metadata");
+      const results = await store.searchNotes("Findable");
+      expect(results.length).toBeGreaterThan(0);
+      for (const r of results) {
+        expect(r).toHaveProperty("metadata", {});
+      }
+    });
+
+    it("MCP query-notes (single by id) carries metadata: {} on a metadata-less note", async () => {
+      const note = await store.createNote("MCP single, no metadata");
+      const tools = generateMcpTools(store);
+      const query = tools.find((t) => t.name === "query-notes")!;
+      const result = await query.execute({ id: note.id }) as any;
+      expect(result).toHaveProperty("metadata", {});
+      expect(JSON.parse(JSON.stringify(result))).toHaveProperty("metadata", {});
+    });
+
+    it("MCP query-notes (list) carries metadata: {} on metadata-less notes", async () => {
+      await store.createNote("MCP list, no metadata");
+      const tools = generateMcpTools(store);
+      const query = tools.find((t) => t.name === "query-notes")!;
+      const result = await query.execute({}) as any;
+      const list = Array.isArray(result) ? result : result.notes;
+      expect(list.length).toBeGreaterThan(0);
+      for (const r of list) {
+        expect(r).toHaveProperty("metadata", {});
+      }
+    });
+  });
+
   it("query-notes single note by path", async () => {
     await store.createNote("By Path", { path: "Projects/README" });
     const tools = generateMcpTools(store);
@@ -4173,14 +4245,21 @@ describe("MCP tools", async () => {
     expect(projects).toHaveLength(3);
     expect(projects.every((n) => n.path!.startsWith("Projects"))).toBe(true);
 
-    // limit + offset
-    const page = await query.execute({
+    // limit + offset. Returning exactly `limit` rows with no cursor also
+    // trips the V1.3 truncation-honesty warning (results.length === limit,
+    // an inherent heuristic — it can't distinguish "exactly this many rows
+    // exist" from "capped, more may follow" without a lookahead), which
+    // wraps the response in { notes, warnings } instead of a bare array —
+    // same envelope shape the tool already uses for other warnings.
+    const pageResult = await query.execute({
       path_prefix: "Projects",
       sort: "asc",
       limit: 2,
       offset: 1,
-    }) as any[];
+    }) as any;
+    const page = Array.isArray(pageResult) ? pageResult : pageResult.notes;
     expect(page).toHaveLength(2);
+    expect(pageResult.warnings?.some((w: any) => w.code === "truncated" && w.limit === 2)).toBe(true);
   });
 
   it("query-notes full-text search works", async () => {
@@ -6614,10 +6693,10 @@ describe("create-note if_exists (vault#555)", async () => {
       if_exists: "replace",
     }) as any;
     expect(second.content).toBe("");
-    // An empty `{}` metadata collapses to `undefined` on read — the same
-    // convention every note with no metadata follows (rowToNote), not
-    // something special about `replace`.
-    expect(second.metadata).toBeUndefined();
+    // An empty `{}` metadata reads back as `{}`, not an absent key — the
+    // same convention every note with no metadata follows (rowToNote,
+    // vault V1.1), not something special about `replace`.
+    expect(second.metadata).toEqual({});
   });
 
   it("if_exists is a no-op without a path — a pathless create can never conflict", async () => {

package/core/src/mcp.ts

@@ -10,6 +10,7 @@ import {
   collectUnknownTagWarnings,
   emptySearchWarning,
   ignoredParamWarning,
+  truncatedResultsWarning,
   computeSearchDidYouMean,
   searchDidYouMeanWarning,
   type QueryWarning,
@@ -771,6 +772,22 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // never leaks via `did_you_mean`.
         let queryWarnings: QueryWarning[] = [];
         if (params.search) {
+          // `offset` under full-text search (vault contracts-brief V1.2):
+          // `searchNotes` has no offset parameter at all — FTS5 ranks by
+          // relevance, not a stable row order, so paging by offset over it
+          // is unsound. Rather than silently return page 1 with no signal,
+          // flag it. Presence check (`!== undefined`) so `offset: 0` — a
+          // caller being explicit about "start" — still warns. The
+          // structured-query branch (below) has real offset support and is
+          // unaffected.
+          if (params.offset !== undefined) {
+            queryWarnings.push(
+              ignoredParamWarning(
+                "offset",
+                "full-text search has no stable row order to offset into — results are always page 1, ranked by relevance",
+              ),
+            );
+          }
           // Normalize tag param
           const tags = normalizeTags(params.tag);
           const mode: SearchMode = searchMode ?? "literal";
@@ -887,6 +904,13 @@ Response shape (vault#550 — three variants, pick by what you passed):
             nextCursor = page.next_cursor;
           } else {
             results = await store.queryNotes(queryOpts);
+            // Truncation-honesty (vault contracts-brief V1.3): no cursor was
+            // requested, so `next_cursor` never surfaces as an honest
+            // "more may follow" signal — this is that signal. Mirrors the
+            // REST structured-query path in src/routes.ts.
+            if (results.length === queryOpts.limit) {
+              queryWarnings.push(truncatedResultsWarning(queryOpts.limit));
+            }
           }
         }
 

package/core/src/notes.ts

@@ -2980,7 +2980,12 @@ interface NoteRow {
 }
 
 function rowToNote(row: NoteRow): Note {
-  let metadata: Record<string, unknown> | undefined;
+  // `metadata` is always present on the wire — NULL/"{}"/unparseable all
+  // collapse to `{}` rather than an absent key. `tags` is already always
+  // `[]` (see getNote/queryNotes/searchNotes hydration below); this keeps
+  // the note shape internally consistent and fixes a real third-party
+  // crash on clients that assumed `note.metadata` always exists.
+  let metadata: Record<string, unknown> = {};
   if (row.metadata && row.metadata !== "{}") {
     try { metadata = JSON.parse(row.metadata); } catch {}
   }

package/core/src/query-warnings.ts

@@ -219,6 +219,26 @@ export function ignoredParamWarning(param: string, reason: string): QueryWarning
   };
 }
 
+/**
+ * `truncated` warning (vault contracts-brief V1.3) — a structured, non-
+ * cursor list query returned exactly `limit` rows with no watermark to page
+ * from. That's ambiguous on its own: it might be the whole result set
+ * (coincidence), or there might be more rows silently cut off. Combined
+ * with the engine's default order (`created_at ASC` — oldest first,
+ * core/src/notes.ts) this is the concrete failure mode: a bare `GET
+ * /api/notes` on a >limit-note vault returns the OLDEST rows with zero
+ * signal that the NEWEST ones didn't make it. `?cursor=` (bootstrap or
+ * watermark) sidesteps this entirely — the warning only fires in its
+ * absence.
+ */
+export function truncatedResultsWarning(limit: number): QueryWarning {
+  return {
+    code: "truncated",
+    message: `${limit} = limit rows returned; there may be more. Pass ?cursor= to page, or sort=desc for newest-first.`,
+    limit,
+  };
+}
+
 /**
  * Cheap zero-result search suggestion (vault#551 WS2B — mirrors the tag
  * `did_you_mean` above via the SAME `suggestSimilarTag` scorer, just over a

package/core/src/seed-packs.ts

@@ -382,6 +382,16 @@ file one document, or bring in one small batch — then stop and show them what
 happened. Structure grows from real notes (that's Part 2's design vocabulary).
 Setup is a relationship over many sessions, not an install step.
 
+**Capture first, ask second.** If the person's very first message already names
+something real — a live project, a decision they're weighing, a deadline —
+**capture THAT as the first note from what they've told you, before asking for
+more detail.** Don't interview them into an empty vault: the note you can
+already write is worth more than the three you're still asking about, and your
+questions land better as the follow-up to a captured thing ("got the commission
+down — when's it due, and who's the client?") than as the opener. A good first
+conversation that leaves the vault empty is a miss, not a success — something
+they said should have stuck.
+
 Five short guides ship in this vault for the person to read (tagged \`#guide\`):
 [[Welcome to your vault 🪂]], [[Capture anything]], [[Tags and the graph]],
 [[Connect your AI]], and [[Yours to keep]]. Point them there for anything you'd
@@ -484,7 +494,12 @@ These three axes are the heart of vault design. Use the right one for the job:
   marked \`indexed: true\` to make it **queryable with operators** (\`query-notes
   { tag: "meeting", metadata: { held_on: { gte: "2026-01-01" } } }\`); indexing
   is opt-in per field, not automatic. Add a schema (and index a field) when you
-  find yourself wanting to filter or sort on a value, not before.
+  find yourself wanting to filter or sort on a value, not before. **Field names
+  are global across the vault, not scoped per tag** — two tags that declare the
+  same field name must agree on its type. So prefer a tag-specific name
+  (\`price_tier\` on \`#restaurant\`, \`book_rating\` on \`#book\`) over a generic
+  shared one (a \`rating\` that means 1–10 on one tag and \`$\`–\`$$$$\` on another
+  collides); when in doubt, name the field for the tag it belongs to.
 
 Rule of thumb: **type with tags, file with paths, make-it-queryable with
 schemas.** Start minimal — invent tags as real notes need them, declare a
@@ -502,7 +517,7 @@ update-tag {
   fields: {
     held_on: { type: "string", indexed: true },                                         // queryable with operators
     status:  { type: "string", enum: ["scheduled", "done"], default: "scheduled" },      // explicit default — declare one to auto-fill
-    rating:  { type: "integer" }                                                        // no default — stays unset until written
+    meeting_rating: { type: "integer" }                                                 // no default — stays unset until written; tag-specific name, not a bare rating
   }
 }
 \`\`\`
@@ -556,8 +571,8 @@ A few behaviors worth knowing before you write at scale:
 - **A schema field only back-fills when you declare an explicit \`default\`.**
   When a note gets a tag whose schema declares a field with a \`default\`, an
   unset field is filled with THAT value. A field with no \`default\` stays
-  genuinely absent — \`query-notes { metadata: { rating: { exists: false } } }\`
-  reliably finds notes that never set \`rating\`. Declare \`default\` on a field
+  genuinely absent — \`query-notes { metadata: { meeting_rating: { exists: false } } }\`
+  reliably finds notes that never set \`meeting_rating\`. Declare \`default\` on a field
   only when "unset" and "explicitly set to X" should read the same; leave it
   off when you need to tell them apart.
 - **Validation is advisory, never blocking — EXCEPT an \`indexed: true\`

package/core/src/types.ts

@@ -31,6 +31,13 @@ export interface Note {
    * `core/src/portable-md.ts:supportsInlineFrontmatter`.
    */
   extension?: string;
+  /**
+   * Always present on notes read back from the store — NULL/`"{}"`/
+   * unparseable metadata all collapse to `{}` rather than an absent key
+   * (mirrors `tags`, which is likewise always `[]`). Optional here only so
+   * write-input shapes (`createNote`/`updateNote` options) can share this
+   * type without forcing every caller to pass an empty object.
+   */
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
@@ -352,6 +359,7 @@ export interface NoteIndex {
   lastUpdatedBy?: string | null;
   lastUpdatedVia?: string | null;
   tags?: string[];
+  /** Always present (`{}` when empty) — see `Note.metadata`. */
   metadata?: Record<string, unknown>;
   byteSize: number;
   preview: string;

package/package.json

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

package/src/auth.ts

@@ -280,14 +280,20 @@ export function isMethodAllowed(method: string, permission: TokenPermission): bo
   return READ_METHODS.has(method);
 }
 
+// RFC 7235: the auth-scheme token is case-insensitive (`Bearer`/`bearer`/
+// `BEARER` are all the same scheme) — only the token68/credentials that
+// follow are case-sensitive. `\s+` (not a single literal space) tolerates
+// the rare client that sends more than one space after the scheme.
+const BEARER_PREFIX = /^Bearer\s+/i;
+
 /**
  * Extract API key/token from request.
  * Priority: Authorization header → X-API-Key header → ?key= query param.
  */
 export function extractApiKey(req: Request): string | null {
   const authHeader = req.headers.get("authorization");
-  if (authHeader?.startsWith("Bearer ")) {
-    return authHeader.slice(7);
+  if (authHeader && BEARER_PREFIX.test(authHeader)) {
+    return authHeader.replace(BEARER_PREFIX, "");
   }
   const xApiKey = req.headers.get("x-api-key");
   if (xApiKey) return xApiKey;

package/src/contract-honest-queries.test.ts

@@ -248,6 +248,48 @@ describe("contract: honest queries — warnings channel (#550)", () => {
   });
 });
 
+describe("contract: truncation-honesty warning (V1.3)", () => {
+  it("a structured non-cursor list that hits its limit carries a `truncated` warning", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`note ${i}`);
+    const res = await getNotes("limit=2");
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect(body.length).toBe(2); // the limit itself is unaffected — warning only
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const truncated = warnings!.find((w) => w.code === "truncated");
+    expect(truncated).toBeDefined();
+    expect(truncated.limit).toBe(2);
+  });
+
+  it("an under-limit list carries no `truncated` warning", async () => {
+    await store.createNote("only one");
+    const res = await getNotes("limit=50");
+    expect(res.status).toBe(200);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w) => w.code === "truncated") ?? false).toBe(false);
+  });
+
+  it("cursor mode never carries a `truncated` warning — `next_cursor` is already the honest signal", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`note ${i}`);
+    const res = await getNotes("limit=2&cursor=");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.notes.length).toBe(2);
+    expect(typeof body.next_cursor).toBe("string");
+    expect((body.warnings ?? []).some((w: any) => w.code === "truncated")).toBe(false);
+  });
+
+  it("MCP query-notes mirrors the same truncated warning on a limit-hit non-cursor list", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`mcp note ${i}`);
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ limit: 2 })) as any;
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings.some((w: any) => w.code === "truncated" && w.limit === 2)).toBe(true);
+  });
+});
+
 describe("contract: honest queries — cursor bootstrap (#550, the P1)", () => {
   it("an empty cursor (`?cursor=`) engages the {notes, next_cursor} envelope on the VERY FIRST call, and the returned next_cursor sees only notes written after it", async () => {
     const n1 = await store.createNote("existing note");
@@ -410,3 +452,49 @@ describe("contract: honest queries — find-path hydration (#550, additive)", ()
     ]);
   });
 });
+
+describe("contract: metadata always present on the wire (V1.1)", () => {
+  it("GET /api/notes?id= on a metadata-less note carries `metadata: {}`, not an absent key", async () => {
+    const note = await store.createNote("No metadata here");
+    const res = await getNotes(`id=${note.id}`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body).toHaveProperty("metadata");
+    expect(body.metadata).toEqual({});
+    // `tags` has always been unconditionally present — confirm it still is.
+    expect(body.tags).toEqual([]);
+  });
+
+  it("GET /api/notes (list) carries `metadata: {}` on metadata-less entries", async () => {
+    await store.createNote("List entry, no metadata");
+    const res = await getNotes("");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body.length).toBeGreaterThan(0);
+    for (const entry of body) {
+      expect(entry).toHaveProperty("metadata");
+      expect(entry.metadata).toEqual({});
+    }
+  });
+
+  it("GET /api/notes?search= carries `metadata: {}` on metadata-less results", async () => {
+    await store.createNote("Findable via search, no metadata");
+    const res = await getNotes("search=Findable");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body.length).toBeGreaterThan(0);
+    for (const entry of body) {
+      expect(entry).toHaveProperty("metadata");
+      expect(entry.metadata).toEqual({});
+    }
+  });
+
+  it("a note WITH real metadata is unaffected — the fix only changes the empty case", async () => {
+    const note = await store.createNote("Has metadata", { metadata: { source: "import" } });
+    const res = await getNotes(`id=${note.id}`);
+    const body: any = await res.json();
+    expect(body.metadata).toEqual({ source: "import" });
+  });
+});

package/src/contract-search.test.ts

@@ -305,6 +305,32 @@ describe("contract: search — escaping edge cases, tag-scope, warnings (#551)",
     expect(warnings!.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
   });
 
+  it("offset alongside search is a no-op that surfaces an ignored_param warning, results unchanged (V1.2)", async () => {
+    await store.createNote("findable one", { tags: ["probe"] });
+    await store.createNote("findable two", { tags: ["probe"] });
+
+    const plain = await search("search=findable&tag=probe");
+    const withOffset = await search("search=findable&tag=probe&offset=1");
+    expect(withOffset.status).toBe(200);
+
+    const plainBody = await bodyOf(plain);
+    const offsetBody = await bodyOf(withOffset);
+    // Page 1 either way — offset has no effect on FTS5 relevance ordering.
+    expect(offsetBody.map((n: any) => n.id).sort()).toEqual(plainBody.map((n: any) => n.id).sort());
+
+    const warnings = decodeWarningsHeader(withOffset);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "ignored_param" && w.param === "offset")).toBe(true);
+
+    // No search → no warning (offset only means nothing UNDER search; the
+    // structured-query path honors it for real).
+    const structuredNoWarning = await search("tag=probe&offset=1");
+    const structuredWarnings = decodeWarningsHeader(structuredNoWarning);
+    expect(
+      structuredWarnings?.some((w: any) => w.code === "ignored_param" && w.param === "offset") ?? false,
+    ).toBe(false);
+  });
+
   it("an unrecognized search_mode value is a structured 400 invalid_query", async () => {
     const res = await search("search=widgets&search_mode=bogus");
     expect(res.status).toBe(400);
@@ -460,6 +486,21 @@ describe("contract: search — MCP parity (#551)", () => {
     expect(result.warnings.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
   });
 
+  it("query-notes: offset alongside search is a no-op that surfaces an ignored_param warning (V1.2)", async () => {
+    await store.createNote("mcp findable", { tags: ["probe"] });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "findable", offset: 5 })) as any;
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings.some((w: any) => w.code === "ignored_param" && w.param === "offset")).toBe(true);
+
+    // Structured query (no search) — offset is honored for real, no warning.
+    const structured = (await query.execute({ tag: "probe", offset: 0 })) as any;
+    expect(
+      (structured.warnings ?? []).some((w: any) => w.code === "ignored_param" && w.param === "offset"),
+    ).toBe(false);
+  });
+
   it("query-notes: search_mode:\"advanced\" + malformed syntax throws a structured invalid_search_syntax error", async () => {
     const tools = generateMcpTools(store);
     const query = tools.find((t) => t.name === "query-notes")!;

package/src/routes.ts

@@ -17,6 +17,7 @@ import {
   collectUnknownTagWarnings,
   emptySearchWarning,
   ignoredParamWarning,
+  truncatedResultsWarning,
   computeSearchDidYouMean,
   searchDidYouMeanWarning,
   type QueryWarning,
@@ -1254,6 +1255,23 @@ async function handleNotesInner(
         const sort = (parseQuery(url, "sort") as "asc" | "desc" | null) ?? undefined;
 
         const searchWarnings: QueryWarning[] = [];
+        // `offset` under full-text search (vault contracts-brief V1.2):
+        // `searchNotes` has no offset parameter at all — FTS5 ranks by
+        // relevance, not a stable row order, so paging by offset over it
+        // is unsound. Rather than silently return page 1 with no signal
+        // (the pre-existing behavior — `?search=x&offset=50` == `?search=x`),
+        // flag it. Presence check (not truthiness) so `offset=0` — a caller
+        // being explicit about "start" — still warns; it's equally
+        // meaningless here. The structured-query path (below) has real
+        // offset support and is unaffected.
+        if (parseQuery(url, "offset") !== null) {
+          searchWarnings.push(
+            ignoredParamWarning(
+              "offset",
+              "full-text search has no stable row order to offset into — results are always page 1, ranked by relevance",
+            ),
+          );
+        }
         let rawResults: Note[];
         // "Only whitespace/quotes" (vault#551 edge case) — short-circuit
         // BEFORE ever calling FTS5 rather than risk a syntax error (or a
@@ -1558,6 +1576,15 @@ async function handleNotesInner(
         }
         throw e;
       }
+      // Truncation-honesty (vault contracts-brief V1.3): captured BEFORE
+      // near/tag-scope filtering, which can only shrink the set further —
+      // this reflects whether the underlying store query actually hit its
+      // `limit` (i.e. there may be more rows the caller never saw). Cursor
+      // mode is exempt — it already carries `next_cursor` as the honest
+      // "more may follow" signal, so a second warning would be redundant.
+      if (!cursorMode && results.length === queryOpts.limit) {
+        queryWarnings.push(truncatedResultsWarning(queryOpts.limit));
+      }
 
       // Near-scope filter (graph neighborhood)
       const nearNoteId = parseQuery(url, "near[note_id]");

package/src/scribe-discovery.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, test, expect, beforeEach } from "bun:test";
-import { resolveScribeUrl, clearScribeUrlCache } from "./scribe-discovery.ts";
+import { resolveScribeUrl, getCachedScribeUrl, clearScribeUrlCache } from "./scribe-discovery.ts";
 
 function mkManifest(services: Array<{ name: string; port: number; origin?: string }>): typeof import("./services-manifest.ts").readManifest {
   return () => ({
@@ -75,3 +75,78 @@ describe("resolveScribeUrl", () => {
     expect(resolveScribeUrl(env, manifest)).toBe("http://127.0.0.1:1943");
   });
 });
+
+describe("getCachedScribeUrl (vault contracts-brief V1.5 — TTL, not process-lifetime)", () => {
+  // A manifest fn that counts calls, so tests can prove whether the cache
+  // actually skipped a re-read (rather than just asserting the RESULT,
+  // which would pass even if the cache silently didn't cache at all).
+  function mkCountingManifest(port: number): { impl: typeof import("./services-manifest.ts").readManifest; calls: () => number } {
+    let calls = 0;
+    const impl = (() => {
+      calls++;
+      return {
+        services: [
+          { name: "parachute-scribe", port, paths: ["/parachute-scribe"], health: "/health", version: "0.0.0-test" },
+        ],
+      };
+    }) as unknown as typeof import("./services-manifest.ts").readManifest;
+    return { impl, calls: () => calls };
+  }
+
+  test("within the TTL window, repeated calls reuse the cached value (manifest read once)", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const { impl, calls } = mkCountingManifest(1943);
+    let t = 1_000_000;
+    const now = () => t;
+
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    t += 1_000; // well inside the 30s TTL
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(calls()).toBe(1);
+  });
+
+  test("after the TTL expires, the next call re-resolves — a scribe that appeared mid-process is picked up without a restart", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    // First manifest: no scribe registered yet.
+    let manifestCalls = 0;
+    let portToReturn: number | null = null;
+    const impl = (() => {
+      manifestCalls++;
+      return {
+        services: portToReturn === null
+          ? []
+          : [{ name: "parachute-scribe", port: portToReturn, paths: ["/parachute-scribe"], health: "/health", version: "0.0.0-test" }],
+      };
+    }) as unknown as typeof import("./services-manifest.ts").readManifest;
+    let t = 1_000_000;
+    const now = () => t;
+
+    // Nothing registered yet — vault boots before scribe.
+    expect(getCachedScribeUrl(env, impl, console, now)).toBeUndefined();
+
+    // Scribe installs and registers itself mid-process — still within TTL,
+    // so the stale "undefined" is what a caller sees (this is the bound the
+    // TTL accepts, not the bug being fixed).
+    portToReturn = 1943;
+    t += 1_000;
+    expect(getCachedScribeUrl(env, impl, console, now)).toBeUndefined();
+    expect(manifestCalls).toBe(1); // still cached — didn't re-read
+
+    // TTL elapses — next probe re-reads and picks up the now-live scribe,
+    // with no vault restart in between.
+    t += 30_000;
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(manifestCalls).toBe(2);
+  });
+
+  test("clearScribeUrlCache forces a fresh resolve even within the TTL window", () => {
+    const env = {} as NodeJS.ProcessEnv;
+    const { impl, calls } = mkCountingManifest(1943);
+    const now = () => 1_000_000;
+
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    clearScribeUrlCache();
+    expect(getCachedScribeUrl(env, impl, console, now)).toBe("http://127.0.0.1:1943");
+    expect(calls()).toBe(2);
+  });
+});

package/src/scribe-discovery.ts

@@ -68,24 +68,43 @@ export function resolveScribeUrl(
 }
 
 /**
- * Process-lifetime cache. Computed at first call (typically during server
- * boot), reused for every subsequent transcription request. Operators who
- * change the scribe URL via `services.json` (re-install of scribe with a
- * different port) need to restart vault; we deliberately don't watch the
- * file because the v0.6 deploy model has a single restart-on-change story.
+ * Short-TTL cache (vault contracts-brief V1.5 — was process-lifetime).
+ * `resolveScribeUrl` is just an env read + a `services.json` stat/read, cheap
+ * enough to redo on this cadence — but the transcription capability probe
+ * (`GET /api/vault`, `src/transcription/capability.ts`) can be hit often
+ * enough that re-reading the manifest on EVERY call is wasteful. A TTL
+ * splits the difference: scribe installing/moving/starting mid-process (the
+ * real deploy sequencing — hub can bring scribe up after vault) is picked up
+ * within `SCRIBE_URL_CACHE_TTL_MS` instead of requiring a vault restart,
+ * while a steady-state deployment still avoids a filesystem read per
+ * request. Previously this was a `let ... = null` sentinel computed once at
+ * first call and reused for the rest of the process — that's the staleness
+ * this replaces.
  *
  * Tests should pass an explicit `env` + `readManifestImpl` to `resolveScribeUrl`
- * directly to bypass the cache.
+ * directly to bypass the cache, or use the `now` injection seam here to
+ * simulate TTL expiry without real sleeps.
  */
+const SCRIBE_URL_CACHE_TTL_MS = 30_000;
+
 let cachedScribeUrl: string | undefined | null = null;
+let cachedAt = 0;
 
-export function getCachedScribeUrl(): string | undefined {
-  if (cachedScribeUrl === null) {
-    cachedScribeUrl = resolveScribeUrl();
+export function getCachedScribeUrl(
+  env: NodeJS.ProcessEnv = process.env,
+  readManifestImpl: typeof readManifest = readManifest,
+  logger: { warn?: (...args: unknown[]) => void } = console,
+  now: () => number = Date.now,
+): string | undefined {
+  const t = now();
+  if (cachedScribeUrl === null || t - cachedAt >= SCRIBE_URL_CACHE_TTL_MS) {
+    cachedScribeUrl = resolveScribeUrl(env, readManifestImpl, logger);
+    cachedAt = t;
   }
   return cachedScribeUrl;
 }
 
 export function clearScribeUrlCache(): void {
   cachedScribeUrl = null;
+  cachedAt = 0;
 }

package/src/vault.test.ts

@@ -272,9 +272,9 @@ describe("metadata", async () => {
     expect(published[0].content).toBe("Published");
   });
 
-  test("notes without metadata return undefined metadata", async () => {
+  test("notes without metadata return metadata: {} (vault V1.1 — not an absent key)", async () => {
     const note = await store.createNote("Plain note");
-    expect(note.metadata).toBeUndefined();
+    expect(note.metadata).toEqual({});
   });
 
   test("creates link with metadata", async () => {
@@ -7602,6 +7602,31 @@ describe("extractApiKey", () => {
     expect(extractApiKey(req)).toBe("pvt_abc123");
   });
 
+  // RFC 7235: the auth-scheme token is case-insensitive (V1.4). A client
+  // sending `bearer`/`BEARER`/`BeArEr` must authenticate identically to
+  // one sending the canonical `Bearer` — only the credentials that follow
+  // the scheme are case-sensitive, and those come through verbatim.
+  test("extracts from a lowercase `bearer` scheme (RFC 7235 case-insensitivity)", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "bearer pvt_abc123" },
+    });
+    expect(extractApiKey(req)).toBe("pvt_abc123");
+  });
+
+  test("extracts from a mixed-case `BeArEr` scheme", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "BeArEr pvt_abc123" },
+    });
+    expect(extractApiKey(req)).toBe("pvt_abc123");
+  });
+
+  test("the token itself stays case-sensitive — only the scheme is folded", () => {
+    const req = new Request("http://localhost/api/notes", {
+      headers: { Authorization: "bearer PvT_MixedCase123" },
+    });
+    expect(extractApiKey(req)).toBe("PvT_MixedCase123");
+  });
+
   test("extracts from X-API-Key header", () => {
     const req = new Request("http://localhost/api/notes", {
       headers: { "X-API-Key": "pvk_xyz789" },