@openparachute/vault 0.4.4-rc.12 → 0.4.5

package/core/src/portable-md.ts

@@ -72,7 +72,7 @@
  * See vault#308.
  */
 
-import { readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync } from "fs";
+import { readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, copyFileSync, existsSync, rmSync } from "fs";
 import { basename, join, relative, extname, dirname, resolve as resolvePath, sep as pathSep } from "path";
 import type { Store, Note, Link, Attachment } from "./types.js";
 import type { TagRecord } from "./tag-schemas.js";
@@ -90,11 +90,42 @@ export const EXPORT_FORMAT_VERSION = 1;
  *  as notes; consumers like Logseq/Foam/Quartz don't see the sidecar. */
 export const SIDECAR_DIR = ".parachute";
 
+/**
+ * Subdirectory under the sidecar where per-note metadata sidecars live
+ * for non-frontmatter-compatible extensions (vault#328). One YAML file
+ * per note, keyed by note id: `.parachute/notes-meta/<note-id>.yaml`.
+ * Mirrors the inline-frontmatter shape so the parser can chew either.
+ */
+export const NOTES_META_DIR = "notes-meta";
+
+/**
+ * Extensions whose serialized form carries metadata as inline YAML
+ * frontmatter at the top of the content file. `.md` is the canonical
+ * case; `.mdx` joins it because MDX's parser accepts the same `---`
+ * delimited preamble (and Aaron's planning to use MDX in notes).
+ * Anything else is sidecar-required — see `core/src/portable-md.ts`
+ * write/read paths.
+ *
+ * Easy to extend later — e.g. `.org` if/when a real workflow demands
+ * it. Today's set is conservative: only formats whose parser semantics
+ * we've explicitly validated.
+ */
+const FRONTMATTER_COMPAT_EXTENSIONS = new Set(["md", "mdx"]);
+
+export function supportsInlineFrontmatter(extension: string): boolean {
+  return FRONTMATTER_COMPAT_EXTENSIONS.has(extension.toLowerCase());
+}
+
 /** Order in which top-level frontmatter keys are emitted. Fixed — required
- *  for byte-identical re-exports of unchanged vault state. */
+ *  for byte-identical re-exports of unchanged vault state. `extension` is
+ *  emitted right after `path` so the suffix story sits with the
+ *  filesystem-location story; emitted only when non-default ("md"
+ *  doesn't get a frontmatter line so the existing `.md`-only corpus
+ *  diffs cleanly against pre-vault#328 exports). */
 const FRONTMATTER_KEY_ORDER = [
   "id",
   "path",
+  "extension",
   "tags",
   "metadata",
   "links",
@@ -107,11 +138,20 @@ const FRONTMATTER_KEY_ORDER = [
 // Types
 // ---------------------------------------------------------------------------
 
-/** Per-note shape written into one .md file (frontmatter + content). */
+/** Per-note shape written into one file (frontmatter + content for
+ *  `.md`/`.mdx`; raw content + sidecar metadata for everything else). */
 export interface PortableNote {
   id: string;
   path?: string;
   content: string;
+  /**
+   * File extension (vault#328). Defaults to "md" when omitted —
+   * back-compat with PR1/PR2 exports that predate the extension axis.
+   * Controls both the file suffix on disk AND whether metadata goes
+   * inline as frontmatter (`md`, `mdx`) or in a sidecar
+   * (`csv`/`yaml`/`json`/etc).
+   */
+  extension?: string;
   metadata?: Record<string, unknown>;
   tags?: string[];
   links?: PortableLink[];
@@ -152,6 +192,31 @@ export interface ExportStats {
   notes: number;
   schemas: number;
   attachments: number;
+  /**
+   * Per-note metadata sidecars written for non-frontmatter-compatible
+   * extensions (vault#328). For `.md`/`.mdx` notes this stays 0 —
+   * metadata is inline. For `.csv`/`.yaml`/`.json` notes, one sidecar
+   * per note.
+   */
+  sidecars: number;
+  /**
+   * True when the export ran on a case-insensitive filesystem (macOS
+   * APFS default, Windows NTFS, FAT/exFAT) — whether or not any
+   * collision actually occurred. The probe runs once per export
+   * regardless of the note set; this field reflects the probe's
+   * outcome. To detect actual collisions, check
+   * `disambiguated_paths.length > 0`. See vault#327.
+   */
+  case_insensitive_fs: boolean;
+  /**
+   * Per-note disambiguation detail when the export's case-insensitive
+   * filesystem would otherwise silently collapse notes whose paths
+   * differ only by case (vault#327). Each entry records the original
+   * path + the suffixed on-disk filename so the operator can audit.
+   * Empty on case-sensitive filesystems and on case-insensitive
+   * filesystems with no collisions.
+   */
+  disambiguated_paths: Array<{ note_id: string; original_path: string; disambiguated_filename: string }>;
   /** Set when caller passed `since`; counts notes whose `updated_at >= since`. */
   filtered_by_since: boolean;
   /**
@@ -356,6 +421,9 @@ function buildFrontmatter(note: PortableNote): Record<string, unknown> {
   const fm: Record<string, unknown> = {};
   fm.id = note.id;
   if (note.path) fm.path = note.path;
+  // Emit only when non-default ("md") so legacy markdown-only exports
+  // produce byte-identical bytes pre- and post-vault#328.
+  if (note.extension && note.extension !== "md") fm.extension = note.extension;
   if (note.tags && note.tags.length > 0) fm.tags = [...note.tags].sort();
   if (note.metadata && Object.keys(note.metadata).length > 0) fm.metadata = note.metadata;
   if (note.links && note.links.length > 0) fm.links = note.links;
@@ -366,13 +434,18 @@ function buildFrontmatter(note: PortableNote): Record<string, unknown> {
 }
 
 /**
- * Render a note as portable markdown: `--- <frontmatter> --- <content>`.
- * Frontmatter keys in `FRONTMATTER_KEY_ORDER`; nested objects alpha-sorted.
- * Trailing newline preserved from `content` (or one is added if absent).
+ * Emit a frontmatter-shape object using `FRONTMATTER_KEY_ORDER`: each
+ * present key gets one or more lines (inline form for scalars + empty
+ * collections, block form otherwise). Every line ends in `\n`. The
+ * output does NOT include the `---` wrapper — that's the caller's
+ * concern (only `toPortableMarkdown` wraps; `toSidecarYaml` doesn't).
+ *
+ * Single source of truth for the per-key emit loop shared by
+ * `toPortableMarkdown` and `toSidecarYaml` (vault#330 F3 — pure
+ * refactor, behavior unchanged).
  */
-export function toPortableMarkdown(note: PortableNote): string {
-  const fm = buildFrontmatter(note);
-  let out = "---\n";
+function emitFrontmatterKeys(fm: Record<string, unknown>): string {
+  let out = "";
   for (const key of FRONTMATTER_KEY_ORDER) {
     if (!(key in fm)) continue;
     const value = fm[key];
@@ -385,6 +458,36 @@ export function toPortableMarkdown(note: PortableNote): string {
       if (block !== null) out += `${block}\n`;
     }
   }
+  return out;
+}
+
+/**
+ * Render a note's content-file bytes. Behavior depends on the note's
+ * `extension`:
+ *
+ *   - Frontmatter-compatible (`.md`, `.mdx`): emits `--- <frontmatter>
+ *     --- <content>`. Today's behavior, generalized to also handle MDX.
+ *   - Sidecar-required (`.csv`, `.yaml`, `.json`, etc.): emits the
+ *     raw content as-is (no frontmatter prepend). The metadata lives in
+ *     `.parachute/notes-meta/<id>.yaml`; see `toSidecarYaml`.
+ *
+ * Trailing-newline: frontmatter form always ends with `\n`. Raw content
+ * form is returned verbatim — if the note's content has no trailing
+ * newline, the file ends without one. Callers wanting strict
+ * trailing-newline normalization (re-emit invariant) should add it
+ * outside this function.
+ */
+export function toPortableMarkdown(note: PortableNote): string {
+  const ext = note.extension ?? "md";
+  if (!supportsInlineFrontmatter(ext)) {
+    // Sidecar-required: content goes out as-is. No frontmatter, no
+    // synthetic trailing newline — the file is whatever the caller
+    // stored as `content`.
+    return note.content;
+  }
+  const fm = buildFrontmatter(note);
+  let out = "---\n";
+  out += emitFrontmatterKeys(fm);
   out += "---\n";
   // Preserve content as-is; ensure exactly one trailing newline if missing.
   out += note.content;
@@ -392,14 +495,47 @@ export function toPortableMarkdown(note: PortableNote): string {
   return out;
 }
 
+/**
+ * Render a note's sidecar metadata bytes (vault#328). Same key set as
+ * the inline frontmatter — just lifted out of the content file. Used
+ * for sidecar-required extensions (`.csv`/`.yaml`/`.json`/etc.) where
+ * the content file can't host YAML. Order of keys is fixed
+ * (`FRONTMATTER_KEY_ORDER`) so the sidecar bytes are byte-identical
+ * across re-exports of unchanged vault state.
+ *
+ * Always includes the `extension` field (unlike `buildFrontmatter`,
+ * which omits it for `md` to keep legacy diffs clean) — the sidecar is
+ * a new artifact, the omit-default optimization buys nothing.
+ */
+export function toSidecarYaml(note: PortableNote): string {
+  // Build a "full" frontmatter — same as buildFrontmatter, but always
+  // emit the extension. The sidecar's purpose is exactly to record
+  // the extension that's not in the filename.
+  const fm: Record<string, unknown> = {};
+  fm.id = note.id;
+  if (note.path) fm.path = note.path;
+  fm.extension = note.extension ?? "md";
+  if (note.tags && note.tags.length > 0) fm.tags = [...note.tags].sort();
+  if (note.metadata && Object.keys(note.metadata).length > 0) fm.metadata = note.metadata;
+  if (note.links && note.links.length > 0) fm.links = note.links;
+  if (note.attachments && note.attachments.length > 0) fm.attachments = note.attachments;
+  fm.created_at = note.created_at;
+  if (note.updated_at) fm.updated_at = note.updated_at;
+
+  return emitFrontmatterKeys(fm);
+}
+
 /**
  * Determine the file path for an exported portable-md note. Notes with a
- * `path` use it; pathless notes use `_unpathed/<id>.md` (no date-prefix
- * coincidence with user content).
+ * `path` use it + their `extension`; pathless notes use
+ * `_unpathed/<id>.<extension>` (no date-prefix coincidence with user
+ * content). Default extension is "md" so pre-vault#328 exports produce
+ * the same filenames.
  */
 export function portableExportFilePath(note: PortableNote): string {
-  if (note.path) return note.path + ".md";
-  return `_unpathed/${note.id}.md`;
+  const ext = note.extension ?? "md";
+  if (note.path) return `${note.path}.${ext}`;
+  return `_unpathed/${note.id}.${ext}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -440,10 +576,16 @@ export async function noteToPortable(
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
 
+  // Default to "md" so old PR1/PR2 callers (or callers that didn't get
+  // the v18 column from a fresh-DB read) keep producing identical
+  // frontmatter shape.
+  const extension = note.extension ?? "md";
+
   const result: PortableNote = {
     id: note.id,
     ...(note.path ? { path: note.path } : {}),
     content: note.content,
+    ...(extension ? { extension } : {}),
     ...(note.metadata && Object.keys(note.metadata).length > 0 ? { metadata: note.metadata } : {}),
     ...(note.tags && note.tags.length > 0 ? { tags: [...note.tags].sort() } : {}),
     ...(typedLinks.length > 0 ? { links: typedLinks } : {}),
@@ -480,6 +622,15 @@ export interface ExportOptions {
    * stays pure (no dep on server-side path resolution).
    */
   assetsDir?: string;
+  /**
+   * Override the filesystem case-sensitivity probe (vault#327). Pass
+   * `false` to force the case-insensitive code path (with auto-
+   * disambiguation) regardless of the real filesystem; pass `true` to
+   * force the case-sensitive code path. Test seam — lets the round-trip
+   * suite exercise both branches on whatever FS the test happens to
+   * run on. When unset (the production default), the probe runs.
+   */
+  caseSensitiveOverride?: boolean;
 }
 
 /**
@@ -556,14 +707,63 @@ export async function exportVaultToDir(
   const assetsDirResolved = opts.assetsDir ? resolvePath(opts.assetsDir) : undefined;
   const attachmentsRoot = join(sidecar, "attachments");
   const attachmentsRootResolved = resolvePath(attachmentsRoot);
+  const notesMetaRoot = join(sidecar, NOTES_META_DIR);
+  const notesMetaRootResolved = resolvePath(notesMetaRoot);
   let notesWritten = 0;
   let attachmentsWritten = 0;
+  let sidecarsWritten = 0;
   const skipped: { path: string | undefined; reason: string }[] = [];
   const skippedAttachments: { note_id: string; attachment_id: string; path: string; reason: string }[] = [];
+  const disambiguatedPaths: ExportStats["disambiguated_paths"] = [];
+
+  // Case-collision detection (vault#327). On case-insensitive
+  // filesystems (macOS APFS-default, Windows NTFS-default, FAT/exFAT),
+  // two notes whose paths differ only by case collapse into one file
+  // on write — silent data loss. We probe the export dir's filesystem
+  // once, then either ship as-is (case-sensitive) or build a lowercase
+  // `(path, extension)` index during the walk and disambiguate
+  // colliding notes with an `__<id-short>` filename suffix.
+  //
+  // The note's stored `path` (in frontmatter + sidecar) stays canonical;
+  // only the on-disk filename is suffixed. Import recovers the
+  // canonical path from frontmatter/sidecar, not from the filename.
+  const caseSensitive = opts.caseSensitiveOverride ?? probeCaseSensitive(outDir);
+  // Lowercased `<path>|<ext>` → first-write note-id. Subsequent matches
+  // on the same key trigger disambiguation. Only populated on
+  // case-insensitive filesystems.
+  const seenLowerKeys = new Map<string, string>();
+
   for (const note of allNotes) {
     if (since && !shouldIncludeForSince(note, since)) continue;
     const portable = await noteToPortable(note, store);
-    const relPath = portableExportFilePath(portable);
+    let relPath = portableExportFilePath(portable);
+
+    // Decide whether this note's filename needs disambiguation
+    // (vault#327). Only meaningful when the FS is case-insensitive AND
+    // a prior note's (path, ext) tuple already claimed the same
+    // lowercased filename slot. Pathless notes (`_unpathed/<id>.<ext>`)
+    // are immune by construction — their filename embeds the id, which
+    // is case-stable already.
+    if (!caseSensitive && portable.path) {
+      const ext = portable.extension ?? "md";
+      const key = `${portable.path.toLowerCase()}|${ext.toLowerCase()}`;
+      const prior = seenLowerKeys.get(key);
+      if (prior !== undefined && prior !== portable.id) {
+        // Collision: emit the disambiguated form. The frontmatter /
+        // sidecar `path:` still holds the canonical (original) path so
+        // import recovers the truth.
+        const disambig = disambiguateFilename(portable.path, ext, portable.id);
+        relPath = disambig;
+        disambiguatedPaths.push({
+          note_id: portable.id,
+          original_path: portable.path,
+          disambiguated_filename: disambig,
+        });
+      } else if (prior === undefined) {
+        seenLowerKeys.set(key, portable.id);
+      }
+    }
+
     const fullPath = join(outDir, relPath);
     // vault#317 F3 — path-traversal guard. A note with
     // `path: "../../.ssh/authorized_keys"` would otherwise write outside
@@ -583,6 +783,28 @@ export async function exportVaultToDir(
     writeFileSync(fullPath, toPortableMarkdown(portable));
     notesWritten++;
 
+    // Sidecar metadata write for non-frontmatter-compat extensions
+    // (vault#328). The content file holds raw bytes (no YAML); the
+    // sidecar at .parachute/notes-meta/<id>.yaml carries id/path/tags/
+    // metadata/links/attachments/timestamps.
+    const portableExt = portable.extension ?? "md";
+    if (!supportsInlineFrontmatter(portableExt)) {
+      const sidecarFile = join(notesMetaRoot, `${portable.id}.yaml`);
+      const sidecarResolved = resolvePath(sidecarFile);
+      // Path-traversal guard symmetric with the attachments path: the
+      // sidecar lives under the .parachute/notes-meta/ subtree, period.
+      if (!isWithinDir(sidecarResolved, notesMetaRootResolved)) {
+        skipped.push({
+          path: portable.path,
+          reason: `path-traversal: sidecar write target "${sidecarResolved}" escapes notes-meta root "${notesMetaRootResolved}"`,
+        });
+      } else {
+        mkdirSync(notesMetaRoot, { recursive: true });
+        writeFileSync(sidecarResolved, toSidecarYaml(portable));
+        sidecarsWritten++;
+      }
+    }
+
     // Copy attachment binaries when assetsDir is wired. Each attachment
     // is path-traversal-guarded on both ends: source under assetsDir,
     // dest under outDir's sidecar attachments root. Missing source files
@@ -652,6 +874,9 @@ export async function exportVaultToDir(
     notes: notesWritten,
     schemas: schemasWritten,
     attachments: attachmentsWritten,
+    sidecars: sidecarsWritten,
+    case_insensitive_fs: !caseSensitive,
+    disambiguated_paths: disambiguatedPaths,
     filtered_by_since: since !== undefined,
     skipped_traversal: skipped.length,
     skipped_notes: skipped,
@@ -689,6 +914,85 @@ function isWithinDir(candidate: string, root: string): boolean {
   return candidate.startsWith(root + pathSep);
 }
 
+/**
+ * Probe whether `dir` lives on a case-sensitive filesystem (vault#327).
+ *
+ * The check writes a hidden tempfile, then tests whether the same file
+ * is reachable via its uppercased name. macOS APFS-default and Windows
+ * NTFS-default are case-insensitive (the file IS reachable); Linux
+ * ext4 and macOS APFS-CS are case-sensitive (the file is NOT). Other
+ * platforms (FAT32, exFAT, network shares to either) collapse to the
+ * same probe result.
+ *
+ * Returns true when the filesystem distinguishes case, false otherwise.
+ * Defaults to true (case-sensitive — current export behavior) if the
+ * probe fails for any reason — we'd rather ship without disambiguation
+ * than fail-closed on an unexpected I/O error mid-export.
+ *
+ * The probe cleans up after itself: tempfile is removed before return.
+ * Tempfile name uses a UUID-ish suffix so concurrent probes don't
+ * collide in shared directories.
+ */
+export function probeCaseSensitive(dir: string): boolean {
+  const suffix = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+  const lowerName = `._parachute_cs_probe_${suffix}`;
+  const upperName = `._PARACHUTE_CS_PROBE_${suffix.toUpperCase()}`;
+  const lowerPath = join(dir, lowerName);
+  const upperPath = join(dir, upperName);
+  try {
+    writeFileSync(lowerPath, "");
+    // On a case-insensitive FS, `existsSync(upperPath)` returns true
+    // because upperPath references the same inode. On a case-sensitive
+    // FS, the file at upperPath doesn't exist.
+    const caseInsensitive = existsSync(upperPath);
+    return !caseInsensitive;
+  } catch {
+    // Probe failed — assume case-sensitive (the conservative default
+    // that matches today's export behavior).
+    return true;
+  } finally {
+    try { rmSync(lowerPath, { force: true }); } catch {}
+    // Defensive: if some FS variant created a distinct file at
+    // upperPath, clean that too. No-op when it was the same inode.
+    try { rmSync(upperPath, { force: true }); } catch {}
+  }
+}
+
+/**
+ * Compute the disambiguated filename for a colliding note (vault#327).
+ * Appends `__<id-short>` to the path's basename, before the extension.
+ * The id-short is the first 8 chars of the note ID — short enough to
+ * stay readable, unique enough to avoid secondary collisions in
+ * practice (vault IDs are timestamp-prefixed YYYY-MM-DD-HH-MM-SS-ffffff,
+ * so the first 8 chars include the year + month + day).
+ *
+ * Example: `Journal/2025-05-26 Technology in Balance` (path) with
+ * extension `md` + id `2025-05-26-09-15-42-123456` becomes
+ * `Journal/2025-05-26 Technology in Balance__2025-05-.md`.
+ *
+ * The original path is preserved in the note's frontmatter/sidecar
+ * `path:` field — import recovers the canonical path from there, not
+ * from the disambiguated filename.
+ *
+ * **Assumption** (vault#331 N4): two notes created in the same month
+ * share the first 8 chars of the id-prefix (`YYYY-MM-`). For import,
+ * this is harmless because the resolver runs three tiers in order
+ * (exact-case canonical path → leftover-bucket pick → id-prefix
+ * scan), and sidecars are removed from the leftover map as they're
+ * consumed. By the time the id-prefix scan runs for a disambiguated
+ * filename, the only sidecars that could match are still-orphaned,
+ * so there's at most one candidate per scan. If two notes in the
+ * same month BOTH had disambiguated filenames AND the resolver had
+ * to fall through to the prefix scan for both, the first match wins
+ * deterministically (sorted dir walk). Bumping the slice to 12 or 14
+ * chars would tighten this further but adds noise to filenames —
+ * skip it until a real workload demands the change.
+ */
+function disambiguateFilename(path: string, extension: string, noteId: string): string {
+  const idShort = noteId.slice(0, 8);
+  return `${path}__${idShort}.${extension}`;
+}
+
 function shouldIncludeForSince(note: Note, since: string): boolean {
   const stamp = note.updatedAt ?? note.createdAt;
   return stamp >= since;
@@ -736,6 +1040,14 @@ export interface ImportStats {
   skipped_links: Array<{ source_id: string; target_id: string; relationship: string; reason: string }>;
   /** Per-skipped-attachment detail. */
   skipped_attachments: Array<{ note_id: string; attachment_id: string; reason: string }>;
+  /**
+   * Sidecars under `.parachute/notes-meta/` with no matching content
+   * file on disk (vault#330 S2). Each entry records the sidecar's id +
+   * the expected `(path, extension)` it claimed so the operator can
+   * see what's orphaned. Empty when every sidecar paired with a
+   * content file during the walk.
+   */
+  skipped_sidecars: Array<{ sidecar_id: string; expected_path: string | null; expected_extension: string | null; reason: string }>;
   /** Set when the caller passed `blowAway: true`; counts notes removed. */
   notes_wiped: number;
 }
@@ -783,6 +1095,7 @@ export async function importPortableVault(
     attachments_restored: 0,
     skipped_links: [],
     skipped_attachments: [],
+    skipped_sidecars: [],
     notes_wiped: 0,
   };
 
@@ -837,19 +1150,142 @@ export async function importPortableVault(
     }
   }
 
-  // 3. Notes. Walk every .md file under inDir (dot-dirs already
-  // excluded), parse, upsert.
+  // 3. Notes. Walk every content file under inDir (dot-dirs already
+  // excluded). For frontmatter-compatible extensions (md, mdx) parse
+  // inline metadata. For sidecar-required extensions (csv, yaml, json,
+  // etc.) look up metadata in `.parachute/notes-meta/<id>.yaml`.
+  //
+  // The sidecar's `path` + `extension` are the source of truth for the
+  // user-visible filename — but we walk filenames first and INDEX
+  // sidecars by `(path, extension)` for O(1) lookup per content file.
+  // Sidecars with no matching content file are warned about (and
+  // skipped) rather than triggering a write — preserves the
+  // export-bytes-are-truth invariant.
+  // Sidecar index: keyed by lowercased `<path>|<ext>` so the walker's
+  // filename-derived key (also lowered) matches. The bucket holds the
+  // full sidecar(s) — multiple entries occur when two notes share a
+  // case-insensitive path (vault#327 collisions). The lookup logic
+  // picks the right sidecar from the bucket using the walker's
+  // case-preserved filename + the disambiguated-id-suffix heuristic.
+  const notesMetaDir = join(sidecar, NOTES_META_DIR);
+  const sidecarByKey = new Map<string, Record<string, unknown>[]>();
+  const sidecarByIdLeftover = new Map<string, Record<string, unknown>>();
+  if (existsSync(notesMetaDir)) {
+    const notesMetaRootResolved = resolvePath(notesMetaDir);
+    for (const entry of readdirSync(notesMetaDir)) {
+      if (!entry.endsWith(".yaml")) continue;
+      if (entry.startsWith(".")) continue;
+      const fullPath = join(notesMetaDir, entry);
+      const resolved = resolvePath(fullPath);
+      if (!isWithinDir(resolved, notesMetaRootResolved)) continue;
+      const text = readFileSync(fullPath, "utf-8");
+      // The sidecar is a bare YAML doc (no `---`); wrap to reuse the
+      // shared frontmatter parser.
+      const wrapped = `---\n${text}${text.endsWith("\n") ? "" : "\n"}---\n`;
+      const { frontmatter } = parseFrontmatter(wrapped);
+      const sidecarId = typeof frontmatter.id === "string" ? frontmatter.id : null;
+      const sidecarPath = typeof frontmatter.path === "string" ? frontmatter.path : null;
+      const sidecarExt = typeof frontmatter.extension === "string" ? frontmatter.extension : null;
+      if (!sidecarId) continue;
+      // Index by (path, ext) tuple lowered so case-insensitive walks
+      // match. Multi-value bucket lets two case-collided sidecars coexist
+      // until the per-file lookup picks the right one.
+      if (sidecarPath && sidecarExt) {
+        const key = `${sidecarPath.toLowerCase()}|${sidecarExt.toLowerCase()}`;
+        const bucket = sidecarByKey.get(key);
+        if (bucket) bucket.push(frontmatter);
+        else sidecarByKey.set(key, [frontmatter]);
+      }
+      sidecarByIdLeftover.set(sidecarId, frontmatter);
+    }
+  }
+
   // Track per-import (id → portable) so we can replay typed links
   // after all notes exist.
   const seenNotes = new Map<string, PortableNote>();
-  for (const filePath of walkMarkdownFiles(inDir)) {
+  for (const filePath of walkContentFiles(inDir)) {
     // Containment check — readdirSync should already be safe, but
     // verify the resolved path is inside inDir (symlinks).
     const resolved = resolvePath(filePath);
     if (!isWithinDir(resolved, inDirResolved)) continue;
 
-    const raw = readFileSync(filePath, "utf-8");
-    const { frontmatter, content } = parseFrontmatter(raw);
+    // Derive the file's extension (lowercased, no leading dot) and the
+    // user-visible note path (everything between inDir and the
+    // extension).
+    const extWithDot = extname(filePath); // e.g. ".csv"
+    const fileExt = extWithDot.slice(1).toLowerCase();
+    if (fileExt.length === 0) continue;
+    const relWithExt = relative(inDir, filePath);
+    const relNoExt = relWithExt.slice(0, relWithExt.length - extWithDot.length);
+    // Normalize path separators for cross-platform exports.
+    const userPath = relNoExt.split(pathSep).join("/");
+
+    let frontmatter: Record<string, unknown>;
+    let content: string;
+    if (supportsInlineFrontmatter(fileExt)) {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = parseFrontmatter(raw);
+      frontmatter = parsed.frontmatter;
+      content = parsed.content;
+    } else {
+      // Resolve which sidecar this content file belongs to. Two
+      // sources of ambiguity to handle:
+      //   1. vault#327 case-collisions on a case-insensitive FS —
+      //      multiple sidecars share the same lowered (path, ext) key.
+      //   2. Disambiguated filenames — `<base>__<id-prefix>.<ext>` —
+      //      where the walker's path doesn't match any sidecar's
+      //      canonical path.
+      // Resolution order: exact-case match within the bucket → id-prefix
+      // match against the disambiguation suffix → first remaining
+      // sidecar in the bucket → fall through to id-prefix scan of all
+      // leftovers.
+      let found: Record<string, unknown> | undefined;
+      const key = `${userPath.toLowerCase()}|${fileExt}`;
+      const bucket = sidecarByKey.get(key);
+      if (bucket && bucket.length > 0) {
+        // Try exact-case match on canonical path first — distinguishes
+        // case-collided notes when the FS preserves filename case but
+        // not equality.
+        found = bucket.find((s) => typeof s.path === "string" && s.path === userPath);
+        if (!found) {
+          // No exact-case match. Pick a sidecar from the bucket whose
+          // id is still in `leftover` (i.e. not yet consumed by a prior
+          // file in the walk). This keeps two case-collided notes on a
+          // case-sensitive replay from claiming the same sidecar twice.
+          found = bucket.find((s) => typeof s.id === "string" && sidecarByIdLeftover.has(s.id));
+        }
+      }
+      if (!found) {
+        // Disambiguated filename fallback: `<base>__<id-prefix>.<ext>`.
+        // Strip the suffix, then find a leftover sidecar whose id
+        // starts with that prefix.
+        const disambigMatch = userPath.match(/^(.*)__([A-Za-z0-9-]{6,})$/);
+        if (disambigMatch) {
+          const idPrefix = disambigMatch[2]!;
+          for (const [sidecarId, sidecar] of sidecarByIdLeftover) {
+            if (sidecarId.startsWith(idPrefix)) {
+              found = sidecar;
+              break;
+            }
+          }
+        }
+      }
+      if (!found) {
+        // No sidecar — log and skip. Importing the raw bytes with no
+        // metadata would orphan the row (no id, no path, no
+        // timestamps). Better to surface the gap than silently lose
+        // shape.
+        // eslint-disable-next-line no-console
+        console.warn(`[import] skipped "${filePath}": no matching sidecar at ${NOTES_META_DIR}/<id>.yaml (path="${userPath}", extension="${fileExt}")`);
+        continue;
+      }
+      frontmatter = found;
+      content = readFileSync(filePath, "utf-8");
+      // Mark this sidecar as consumed so subsequent files (and the
+      // stale-sidecar pass) don't double-count.
+      const sidecarId = typeof found.id === "string" ? found.id : null;
+      if (sidecarId) sidecarByIdLeftover.delete(sidecarId);
+    }
 
     const id = typeof frontmatter.id === "string" ? frontmatter.id : null;
     if (!id) {
@@ -863,6 +1299,12 @@ export async function importPortableVault(
     const created_at = typeof frontmatter.created_at === "string" ? frontmatter.created_at : new Date().toISOString();
     const updated_at = typeof frontmatter.updated_at === "string" ? frontmatter.updated_at : created_at;
     const path = typeof frontmatter.path === "string" ? frontmatter.path : undefined;
+    // Trust the frontmatter/sidecar extension first; fall back to the
+    // filename extension. Notes without an explicit extension default
+    // to "md" (back-compat with pre-vault#328 exports).
+    const extension = typeof frontmatter.extension === "string"
+      ? frontmatter.extension
+      : fileExt || "md";
     const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags.filter((t): t is string => typeof t === "string") : undefined;
     const metadata = (frontmatter.metadata && typeof frontmatter.metadata === "object" && !Array.isArray(frontmatter.metadata))
       ? frontmatter.metadata as Record<string, unknown>
@@ -875,6 +1317,7 @@ export async function importPortableVault(
       content,
       created_at,
       updated_at,
+      extension,
       ...(path ? { path } : {}),
       ...(tags && tags.length > 0 ? { tags } : {}),
       ...(metadata ? { metadata } : {}),
@@ -925,6 +1368,7 @@ export async function importPortableVault(
         content,
         ...(path !== undefined ? { path } : {}),
         ...(metadata ? { metadata } : {}),
+        extension,
       });
       // Tags: delete existing, re-tag with imported set.
       if (existing.tags && existing.tags.length > 0) {
@@ -941,6 +1385,7 @@ export async function importPortableVault(
         ...(tags && tags.length > 0 ? { tags } : {}),
         ...(metadata ? { metadata } : {}),
         created_at,
+        extension,
       });
       stats.notes_created++;
     }
@@ -952,6 +1397,27 @@ export async function importPortableVault(
     await store.restoreNoteTimestamps(id, created_at, updated_at);
   }
 
+  // 3b. Drain remaining sidecars (vault#330 S2). Any entry still in
+  // `sidecarByIdLeftover` after the content-file walk is orphaned —
+  // its expected content file wasn't on disk. Record the gap in
+  // `skipped_sidecars` so programmatic callers can surface or repair.
+  // Common cause: an operator removed a content file by hand without
+  // deleting the matching sidecar.
+  for (const [sidecarId, sidecar] of sidecarByIdLeftover) {
+    const expectedPath = typeof sidecar.path === "string" ? sidecar.path : null;
+    const expectedExt = typeof sidecar.extension === "string" ? sidecar.extension : null;
+    stats.skipped_sidecars.push({
+      sidecar_id: sidecarId,
+      expected_path: expectedPath,
+      expected_extension: expectedExt,
+      reason: expectedPath
+        ? `no content file at "${expectedPath}.${expectedExt ?? "md"}"`
+        : "sidecar has no `path:` field; orphaned by construction",
+    });
+    // eslint-disable-next-line no-console
+    console.warn(`[import] orphaned sidecar "${sidecarId}.yaml": ${stats.skipped_sidecars[stats.skipped_sidecars.length - 1]!.reason}`);
+  }
+
   // 4. Typed links — replay only now that all notes exist. Wikilinks
   // (which the exporter excludes from `links:`) rebuild from
   // content brackets via syncAllWikilinks (a callable Store method).
@@ -1395,6 +1861,29 @@ export function walkMarkdownFiles(dir: string): string[] {
   return results.sort();
 }
 
+/**
+ * Recursively list all content files in a portable-md export (vault#328).
+ * Same dot-dir exclusion as `walkMarkdownFiles` — sidecar metadata under
+ * `.parachute/` is reached separately by the importer. Files with no
+ * extension are skipped (no way to tell what they are; vault doesn't
+ * write extensionless notes by design).
+ */
+export function walkContentFiles(dir: string): string[] {
+  const results: string[] = [];
+  function walk(current: string) {
+    for (const entry of readdirSync(current)) {
+      if (entry.startsWith(".")) continue;
+      if (entry === "node_modules") continue;
+      const full = join(current, entry);
+      const stat = statSync(full);
+      if (stat.isDirectory()) walk(full);
+      else if (stat.isFile() && extname(entry).length > 0) results.push(full);
+    }
+  }
+  walk(dir);
+  return results.sort();
+}
+
 /** Extract inline #tags from markdown content. Excludes tags in code blocks. */
 export function extractInlineTags(content: string): string[] {
   let stripped = content.replace(/```[\s\S]*?```/g, "");