@openparachute/vault 0.7.2-rc.6 → 0.7.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.2-rc.6",
+  "version": "0.7.2",
   "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).
 //