@openparachute/vault 0.4.4-rc.12 → 0.4.5

package/core/src/notes.ts

@@ -29,22 +29,22 @@ export function generateId(): string {
 export function createNote(
   db: Database,
   content: string,
-  opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string },
+  opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string },
 ): Note {
   const id = opts?.id ?? generateId();
   const createdAt = opts?.created_at ?? new Date().toISOString();
   const metadata = opts?.metadata ? JSON.stringify(opts.metadata) : "{}";
   const path = normalizePath(opts?.path);
+  // `extension` defaults to "md" so existing callers see no change.
+  // Validation happens at the API surface (MCP/REST) — the Store accepts
+  // whatever the caller passed; importer paths trust the export's shape.
+  const extension = opts?.extension ?? "md";
 
-  // Empty-note invariant (#213): reject `content+path both absent`. Three
-  // legit shapes — content-only, path-only, both — only the empty+empty
-  // combo is the runaway-client signature that flooded a deployment with
-  // 7,453 pathless empty notes in one MCP burst. `content` only is a
-  // legitimate un-pathed jot; `path` only is a wikilink placeholder or
-  // `_schemas/*` config note.
-  if (!content.trim() && path === null) {
-    throw new EmptyNoteError();
-  }
+  // Empty content is a valid state (vault#323): skeleton notes, drafts
+  // saved before content, organizing-only notes, capture-then-fill flows.
+  // The earlier #213 guard rejected `content + path both absent`; we no
+  // longer enforce it because real vaults legitimately carry such rows
+  // and the round-trip import has to accept them.
 
   // `updated_at` is set to `created_at` on insert so a client whose optimistic
   // concurrency check falls back to `createdAt` on a never-updated note
@@ -54,8 +54,8 @@ export function createNote(
   // "user-touched since creation."
   try {
     db.prepare(
-      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)`,
-    ).run(id, content, path, metadata, createdAt, createdAt);
+      `INSERT INTO notes (id, content, path, metadata, created_at, updated_at, extension) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).run(id, content, path, metadata, createdAt, createdAt, extension);
   } catch (err) {
     if (path !== null && isPathUniqueError(err)) {
       throw new PathConflictError(path);
@@ -79,13 +79,49 @@ export function getNote(db: Database, id: string): Note | null {
   return note;
 }
 
-export function getNoteByPath(db: Database, path: string): Note | null {
-  const row = db.prepare("SELECT * FROM notes WHERE path = ?").get(path) as NoteRow | undefined;
-  if (!row) return null;
+/**
+ * Look up a note by `path`. When `extension` is provided, the lookup
+ * matches the `(path, extension)` tuple — exactly one row, since v18's
+ * composite uniqueness index makes that combo unique. When `extension`
+ * is omitted:
+ *
+ *   - 0 matches → return null (back-compat).
+ *   - 1 match → return it (back-compat).
+ *   - >1 match → throw `AmbiguousPathError` (vault#330 S1). Caller
+ *     must pass `extension` explicitly to disambiguate. Mirrors the
+ *     wikilink ambiguity policy from vault#328 edge case 3 —
+ *     path-as-key lookup is "(path, extension) tuple" everywhere.
+ *
+ * Path match is case-insensitive (`COLLATE NOCASE`) — matches the v5
+ * uniqueness contract and how wikilinks resolve.
+ */
+export function getNoteByPath(db: Database, path: string, extension?: string): Note | null {
+  if (extension !== undefined) {
+    const row = db.prepare(
+      "SELECT * FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(path, extension.toLowerCase()) as NoteRow | undefined;
+    if (!row) return null;
+    const note = rowToNote(row);
+    note.tags = getNoteTags(db, note.id);
+    return note;
+  }
 
-  const note = rowToNote(row);
-  note.tags = getNoteTags(db, note.id);
-  return note;
+  // No extension given. The composite-unique index lets two rows share
+  // a path differing only by extension, so we have to look at all matches
+  // before returning.
+  const rows = db.prepare(
+    "SELECT * FROM notes WHERE path = ? COLLATE NOCASE",
+  ).all(path) as NoteRow[];
+  if (rows.length === 0) return null;
+  if (rows.length === 1) {
+    const note = rowToNote(rows[0]!);
+    note.tags = getNoteTags(db, note.id);
+    return note;
+  }
+  throw new AmbiguousPathError(
+    path,
+    rows.map((r) => ({ id: r.id, extension: r.extension ?? "md" })),
+  );
 }
 
 export function getNotes(db: Database, ids: string[]): Note[] {
@@ -147,6 +183,31 @@ export class PathConflictError extends Error {
   }
 }
 
+/**
+ * Thrown by `getNoteByPath` when the caller looked up a path that has
+ * multiple notes (post-vault#328: same path, different extensions),
+ * without specifying which extension to disambiguate. Aligns the
+ * path-as-key lookup contract with the wikilink ambiguity policy
+ * (vault#328 edge case 3): refuse-and-require-explicit-extension.
+ *
+ * Surfaces structured fields so callers (MCP `resolveNote`, REST
+ * path-as-id handlers) can convert to a clear 409 / 4xx with the list
+ * of candidate extensions. See vault#330 S1.
+ */
+export class AmbiguousPathError extends Error {
+  code = "AMBIGUOUS_PATH" as const;
+  path: string;
+  candidates: { id: string; extension: string }[];
+
+  constructor(path: string, candidates: { id: string; extension: string }[]) {
+    const list = candidates.map((c) => c.extension).join(", ");
+    super(`ambiguous_path: "${path}" matches ${candidates.length} notes (extensions: ${list}); pass \`extension\` to disambiguate`);
+    this.name = "AmbiguousPathError";
+    this.path = path;
+    this.candidates = candidates;
+  }
+}
+
 /**
  * Per-call item cap on `createNote`/`updateNote` batch entry points
  * (MCP `create-note` / `update-note` and HTTP `POST /api/notes`).
@@ -157,43 +218,72 @@ export class PathConflictError extends Error {
 export const MAX_BATCH_SIZE = 500;
 
 /**
- * Thrown by `createNote` / `updateNote` when the proposed note state has
- * neither content nor path. The vault accepts un-pathed jots (content only)
- * and path-only placeholders (wikilink stubs, `_schemas/*`), but a note
- * with neither is the runaway-client signature flagged in #213 — one MCP
- * burst flooded a deployment with 7,453 empty pathless rows. Surfaces as
- * 400 at the HTTP layer.
+ * Validate a caller-supplied file extension (vault#328). Rules:
+ *   1. Non-empty, lowercase alphanumeric only.
+ *   2. Length 1–16 — long enough for "markdown" etc., short enough to
+ *      bound on-disk filename length.
+ *   3. No dot/slash/uppercase — those would create path-encoding
+ *      ambiguity or collide with filesystem separators.
+ *   4. Reserved: anything matching /^parachute/i is refused because the
+ *      `.parachute/` sidecar dir convention owns that namespace; a note
+ *      with extension `parachute` would write to `<path>.parachute`
+ *      which is ambiguous with a directory entry.
+ *
+ * Throws `ExtensionValidationError` on failure. Both MCP and REST
+ * surfaces import this so the contract can never drift between them.
  */
-export class EmptyNoteError extends Error {
-  code = "EMPTY_NOTE" as const;
-  note_id: string | null;
-  /**
-   * Zero-based position in a batch call when the empty entry is rejected via
-   * the transport-layer pre-validation pass (HTTP `POST /api/notes` or MCP
-   * `create-note` with `notes: [...]`). `null` for single-update rejections
-   * and for Store-level throws that don't know their batch context.
-   */
-  item_index: number | null;
-
-  constructor(noteId: string | null = null, itemIndex: number | null = null) {
-    super(
-      noteId
-        ? `empty_note: update would leave note "${noteId}" with neither content nor path`
-        : itemIndex !== null
-          ? `empty_note: a note must have either content or a path (item index ${itemIndex})`
-          : `empty_note: a note must have either content or a path`,
+export const EXTENSION_PATTERN = /^[a-z0-9]{1,16}$/;
+
+export class ExtensionValidationError extends Error {
+  code = "INVALID_EXTENSION" as const;
+  extension: string;
+  reason: string;
+
+  constructor(extension: string, reason: string) {
+    super(`invalid extension "${extension}": ${reason}`);
+    this.name = "ExtensionValidationError";
+    this.extension = extension;
+    this.reason = reason;
+  }
+}
+
+export function validateExtension(extension: unknown): string {
+  if (typeof extension !== "string") {
+    throw new ExtensionValidationError(
+      String(extension),
+      `must be a string (got ${typeof extension})`,
+    );
+  }
+  if (extension.length === 0) {
+    throw new ExtensionValidationError(
+      extension,
+      "must be non-empty; omit the field entirely to default to 'md'",
+    );
+  }
+  if (!EXTENSION_PATTERN.test(extension)) {
+    throw new ExtensionValidationError(
+      extension,
+      `must match ${EXTENSION_PATTERN.source} (lowercase alphanumeric, 1–16 chars; no '.', '/', or uppercase)`,
+    );
+  }
+  // Reserved namespace: anything that starts with "parachute" collides
+  // with the .parachute/ sidecar directory convention. The pattern check
+  // above already enforces lowercase, so a literal prefix match is exact.
+  if (extension.startsWith("parachute")) {
+    throw new ExtensionValidationError(
+      extension,
+      "the 'parachute' prefix is reserved for the .parachute/ sidecar dir",
     );
-    this.name = "EmptyNoteError";
-    this.note_id = noteId;
-    this.item_index = itemIndex;
   }
+  return extension;
 }
 
 /**
- * Match bun:sqlite's UNIQUE-constraint error on the notes.path index. The
- * error class is `SQLiteError` but matching on the message is sufficient
- * here — the index name and column are stable parts of the schema, and
- * bun:sqlite has carried this exact message text since 1.0.
+ * Match bun:sqlite's UNIQUE-constraint error on the notes path index.
+ * Post-vault#328 the unique index is composite `(path, extension)`, so
+ * the message text is "UNIQUE constraint failed: notes.path,
+ * notes.extension". Pre-v18 (legacy `(path)` index) emitted just
+ * "notes.path". Match on the common prefix to cover both.
  */
 function isPathUniqueError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -219,6 +309,7 @@ export function updateNote(
      */
     prepend?: string;
     path?: string;
+    extension?: string;
     metadata?: Record<string, unknown>;
     created_at?: string;
     skipUpdatedAt?: boolean;
@@ -236,36 +327,9 @@ export function updateNote(
     );
   }
 
-  // Empty-note invariant (#213): when this update touches content or path,
-  // reject if the post-state would be empty content + null path. We only
-  // enforce on transitions that actually touch the relevant fields, so
-  // metadata-only or tag-only updates against legacy empty rows still pass.
-  // Hook-style writes (skipUpdatedAt) are exempted — they're machine-level
-  // marker writes that legitimately may run against any shape of row.
-  const touchesContent = updates.content !== undefined
-    || updates.append !== undefined
-    || updates.prepend !== undefined;
-  const touchesPath = updates.path !== undefined;
-  if ((touchesContent || touchesPath) && !updates.skipUpdatedAt) {
-    const current = getNote(db, id);
-    if (current) {
-      let finalContent: string;
-      if (updates.content !== undefined) {
-        finalContent = updates.content;
-      } else if (touchesContent) {
-        finalContent = (updates.prepend ?? "") + current.content + (updates.append ?? "");
-      } else {
-        finalContent = current.content;
-      }
-      const finalPath = touchesPath ? normalizePath(updates.path) : (current.path ?? null);
-      if (!finalContent.trim() && !finalPath) {
-        throw new EmptyNoteError(id);
-      }
-    }
-    // If `current` is null we fall through — existing code paths handle the
-    // missing-row case downstream (the conditional UPDATE returns 0 rows;
-    // OC throws ConflictError; non-OC returns silently).
-  }
+  // Empty content is a valid state (vault#323) — see createNote. The
+  // matching guard that used to reject updates clearing both content
+  // and path has been removed.
 
   const sets: string[] = [];
   const values: (string | null)[] = [];
@@ -324,6 +388,14 @@ export function updateNote(
     sets.push("path = ?");
     values.push(normalizePath(updates.path));
   }
+  if (updates.extension !== undefined) {
+    // Allowed but documented as caller-owned (vault#328 edge case 1):
+    // the Store accepts whatever the API surface validated, including
+    // changing extension on a non-empty note. The caller is responsible
+    // for content validity post-change.
+    sets.push("extension = ?");
+    values.push(updates.extension);
+  }
   if (updates.metadata !== undefined) {
     sets.push("metadata = ?");
     values.push(JSON.stringify(updates.metadata));
@@ -369,8 +441,14 @@ export function updateNote(
       db.prepare(sql).run(...values);
     }
   } catch (err) {
-    if (updates.path !== undefined && isPathUniqueError(err)) {
-      throw new PathConflictError(normalizePath(updates.path) ?? updates.path);
+    // Post-vault#328 the unique index is composite (path, extension), so
+    // an extension-only update can also trip UNIQUE — widen the catch to
+    // surface those as structured PATH_CONFLICT instead of a raw 500.
+    if (isPathUniqueError(err)) {
+      const conflictPath = updates.path !== undefined
+        ? (normalizePath(updates.path) ?? updates.path)
+        : ((db.prepare("SELECT path FROM notes WHERE id = ?").get(id) as { path: string | null } | undefined)?.path ?? "<unknown>");
+      throw new PathConflictError(conflictPath);
     }
     throw err;
   }
@@ -488,6 +566,26 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     params.push(opts.pathPrefix + "%");
   }
 
+  // Extension filter (vault#328). Single string → exact match; array → IN
+  // clause. Compared lower-case so a caller passing "CSV" still hits rows
+  // stored as "csv". An empty array is a no-op (no filter applied) rather
+  // than a "no rows match" short-circuit — matches the spirit of the
+  // existing `tags: []` behavior.
+  if (opts.extension !== undefined) {
+    const exts = Array.isArray(opts.extension) ? opts.extension : [opts.extension];
+    const cleaned = exts
+      .filter((e): e is string => typeof e === "string" && e.length > 0)
+      .map((e) => e.toLowerCase());
+    if (cleaned.length === 1) {
+      conditions.push("LOWER(n.extension) = ?");
+      params.push(cleaned[0]!);
+    } else if (cleaned.length > 1) {
+      const placeholders = cleaned.map(() => "?").join(", ");
+      conditions.push(`LOWER(n.extension) IN (${placeholders})`);
+      params.push(...cleaned);
+    }
+  }
+
   // Metadata filters — operator objects route through the indexed generated
   // column (fast, loud errors on non-indexed fields); primitives keep the
   // existing JSON-scan exact-match behavior for backcompat.
@@ -1186,6 +1284,7 @@ export function toNoteIndex(note: Note): NoteIndex {
   return {
     id: note.id,
     path: note.path,
+    extension: note.extension,
     createdAt: note.createdAt,
     updatedAt: note.updatedAt,
     tags: note.tags,
@@ -1293,6 +1392,7 @@ export interface BulkNoteInput {
   tags?: string[];
   metadata?: Record<string, unknown>;
   created_at?: string;
+  extension?: string;
 }
 
 export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
@@ -1308,6 +1408,7 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
           tags: input.tags,
           metadata: input.metadata,
           created_at: input.created_at,
+          extension: input.extension,
         }),
       );
     }
@@ -1375,6 +1476,7 @@ interface NoteRow {
   metadata: string | null;
   created_at: string;
   updated_at: string | null;
+  extension: string | null;
 }
 
 function rowToNote(row: NoteRow): Note {
@@ -1386,6 +1488,10 @@ function rowToNote(row: NoteRow): Note {
     id: row.id,
     content: row.content,
     path: row.path ?? undefined,
+    // `extension` is NOT NULL DEFAULT 'md' in v18+, but rows under a v17
+    // migration window might briefly read as NULL. Fall back to "md" so
+    // callers never see a missing extension.
+    extension: row.extension ?? "md",
     metadata,
     createdAt: row.created_at,
     // Legacy notes (pre-#70) may have NULL updated_at. Fall back to created_at