@openparachute/vault 0.5.1-rc.2 → 0.5.2-rc.1

package/core/src/obsidian-alignment.test.ts

@@ -0,0 +1,375 @@
+/**
+ * Obsidian-importer alignment fixtures (vault#423).
+ *
+ * These assert the vault/CLI parser + write adapter against the SHARED
+ * canonical fixture set in the alignment contract. The parachute-surface
+ * web parser asserts the SAME fixtures (its own test runner) so both
+ * importers produce identical parsed results. Do NOT change expected
+ * values here without changing the contract + the web side in lockstep.
+ *
+ * Fixture inputs are inline strings (`srcPath` + content). Parse-tier
+ * fixtures write the file to a temp dir and parse via `parseObsidianFile`
+ * — the same code the CLI runs. Write-tier fixtures (FX-ID-COLLISION,
+ * FX-SAME-STEM-COLLISION, FX-CREATED-AT write assertion) exercise the
+ * real `importObsidianNotes` adapter against an in-memory SqliteStore.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import {
+  parseObsidianFile,
+  importObsidianNotes,
+  isMarkdownExtension,
+  isExcludedPath,
+  type ObsidianNote,
+} from "./obsidian.js";
+import { mkdirSync, writeFileSync, rmSync } from "fs";
+import { join, dirname } from "path";
+import { tmpdir } from "os";
+
+// ---------------------------------------------------------------------------
+// Parse-tier helper: write `content` at `srcPath` under a fresh temp root,
+// parse it via the real `parseObsidianFile`, and return the ObsidianNote.
+// ---------------------------------------------------------------------------
+
+const PARSE_ROOT = join(tmpdir(), "parachute-align-parse");
+
+function parseFixture(srcPath: string, content: string): ObsidianNote {
+  rmSync(PARSE_ROOT, { recursive: true, force: true });
+  const full = join(PARSE_ROOT, srcPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content);
+  return parseObsidianFile(full, PARSE_ROOT);
+}
+
+/** Sorted tag array, for stable comparison against the contract's
+ *  "(sorted)" expected tag lists. */
+function tags(note: ObsidianNote): string[] {
+  return [...note.tags].sort();
+}
+
+describe("alignment: parse tier", () => {
+  it("FX-FENCE-BOM — strips BOM then parses frontmatter", () => {
+    const n = parseFixture("Note.md", "---\nid: bom1\ntags: [a]\n---\nhello");
+    expect(n.path).toBe("Note");
+    expect(tags(n)).toEqual(["a"]);
+    expect(n.id).toBe("bom1");
+    expect(n.createdAt).toBeUndefined();
+    expect(n.content).toBe("hello");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-FOURDASH — ---- body line is not a close fence", () => {
+    const n = parseFixture("Doc.md", "---\nid: x9\n---\nbefore\n----\nafter");
+    expect(n.path).toBe("Doc");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBe("x9");
+    expect(n.content).toBe("before\n----\nafter");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-FOURDASH-OPEN — ---- after open, no real close → whole file is body", () => {
+    const n = parseFixture("D2.md", "---\nid: y\n----\nbody text");
+    expect(n.path).toBe("D2");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("---\nid: y\n----\nbody text");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FENCE-UNCLOSED — open never closed → whole file is body", () => {
+    const n = parseFixture("U.md", "---\nid: z\nbody no close");
+    expect(n.path).toBe("U");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("---\nid: z\nbody no close");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CODE-TAG — #tag inside fenced + inline code is dropped", () => {
+    const content = "#realtag at top\n\n`#inlinenope`\n\n```\n#fencednope\n```\n";
+    const n = parseFixture("C.md", content);
+    expect(n.path).toBe("C");
+    expect(tags(n)).toEqual(["realtag"]);
+    expect(n.content).toBe(content);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NUMERIC-TAG — #2024 is not a tag, #q3/#v2 are", () => {
+    const n = parseFixture("N.md", "plan #2024 and #q3 and #v2 done");
+    expect(n.path).toBe("N");
+    expect(tags(n)).toEqual(["q3", "v2"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-HIER-TAG — hierarchical inline tag keeps the slash", () => {
+    const n = parseFixture("H.md", "see #area/subarea here");
+    expect(n.path).toBe("H");
+    expect(tags(n)).toEqual(["area/subarea"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-FM-TAGS-VALIDATE — slug-validate + normalize frontmatter tags", () => {
+    const n = parseFixture(
+      "T.md",
+      '---\ntags: [Foo, "bad tag!", 42, true, ok-1, "#hash"]\n---\nbody',
+    );
+    expect(n.path).toBe("T");
+    expect(tags(n)).toEqual(["42", "foo", "hash", "ok-1", "true"]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-INLINE-ARRAY — quote-aware inline-array split (2 items, not 3)", () => {
+    const n = parseFixture("IA.md", '---\nkeywords: ["a, b", c]\n---\nx');
+    expect(n.path).toBe("IA");
+    expect(tags(n)).toEqual([]);
+    expect(n.content).toBe("x");
+    expect(n.frontmatter).toEqual({ keywords: ["a, b", "c"] });
+  });
+
+  it("FX-MARKDOWN-EXT — .markdown ingest + classifier", () => {
+    const n = parseFixture("Folder/Note.markdown", "---\nid: m1\n---\nbody");
+    expect(n.path).toBe("Folder/Note");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBe("m1");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+
+    expect(isMarkdownExtension("x.markdown")).toBe(true);
+    expect(isMarkdownExtension("x.md")).toBe(true);
+    expect(isMarkdownExtension("x.mdx")).toBe(false);
+  });
+
+  it("FX-PATH-OVERRIDE — frontmatter path: wins, not in metadata", () => {
+    const n = parseFixture("deep/orig.md", "---\npath: Custom/Place\n---\nbody");
+    expect(n.path).toBe("Custom/Place");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-PATH-OVERRIDE-EXT — frontmatter path: override is extension-stripped", () => {
+    // Pins contract §1.8: a `path:` override ending in .md/.markdown has
+    // its extension stripped (matches the web side). A real web-side
+    // divergence here stayed green because nothing pinned the invariant.
+    const n = parseFixture("deep/orig.md", "---\npath: My/Note.md\n---\nbody");
+    expect(n.path).toBe("My/Note");
+    expect(tags(n)).toEqual([]);
+    expect(n.id).toBeUndefined();
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-PATH-NORMALIZE — backslash + collapse + case-preserve", () => {
+    // Frontmatter path value: \Win\Path\\x\  (double-quoted in YAML).
+    const n = parseFixture("X.md", '---\npath: "\\\\Win\\\\Path\\\\\\\\x\\\\"\n---\nb');
+    expect(n.path).toBe("Win/Path/x");
+    expect(n.content).toBe("b");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CREATED-AT — created_at + updated_at hoisted verbatim, not in metadata", () => {
+    const n = parseFixture(
+      "CA.md",
+      "---\nid: t1\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    expect(n.path).toBe("CA");
+    expect(n.id).toBe("t1");
+    expect(n.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(n.updatedAt).toBe("2024-06-01T12:00:00Z");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CREATED-AT-CAMEL — camelCase createdAt fallback", () => {
+    const n = parseFixture("CC.md", "---\ncreatedAt: 2024-05-01T10:00:00Z\n---\nx");
+    expect(n.path).toBe("CC");
+    expect(n.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NO-ID — id absent → field omitted", () => {
+    const n = parseFixture("NI.md", "---\ntitle: Hello\n---\nbody");
+    expect(n.path).toBe("NI");
+    expect(n.id).toBeUndefined();
+    expect(tags(n)).toEqual([]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({ title: "Hello" });
+  });
+
+  it("FX-DOTDIR-EXCLUDE — intake exclusion classifier", () => {
+    expect(isExcludedPath(".obsidian/app.json")).toBe(true);
+    expect(isExcludedPath(".trash/x.md")).toBe(true);
+    expect(isExcludedPath(".git/config")).toBe(true);
+    expect(isExcludedPath(".parachute/vault.yaml")).toBe(true);
+    expect(isExcludedPath("__MACOSX/x")).toBe(true);
+    expect(isExcludedPath("node_modules/y/z.md")).toBe(true);
+    expect(isExcludedPath(".DS_Store")).toBe(true);
+    expect(isExcludedPath("sub/.hidden.md")).toBe(true);
+    expect(isExcludedPath("Notes/a.md")).toBe(false);
+    expect(isExcludedPath("Notes/Sub/b.markdown")).toBe(false);
+  });
+
+  it("FX-WIKILINK-PASSTHROUGH — wikilinks untouched, inline #tag still extracted", () => {
+    const content = "See [[Other]] and ![[Embed]] and #tag";
+    const n = parseFixture("WL.md", content);
+    expect(n.content).toContain("[[Other]]");
+    expect(n.content).toContain("![[Embed]]");
+    expect(tags(n)).toEqual(["tag"]);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-CRLF — CRLF frontmatter", () => {
+    const n = parseFixture("CR.md", "---\r\nid: cr1\r\ntags: [a]\r\n---\r\nbody");
+    expect(n.path).toBe("CR");
+    expect(n.id).toBe("cr1");
+    expect(tags(n)).toEqual(["a"]);
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-DOTTED-KEY — dotted frontmatter key accepted, not confused with created_at", () => {
+    const n = parseFixture("DK.md", "---\ncreated.at: 2024\nid: dk1\n---\nx");
+    expect(n.path).toBe("DK");
+    expect(n.id).toBe("dk1");
+    expect(n.createdAt).toBeUndefined();
+    expect(n.frontmatter).toEqual({ "created.at": 2024 });
+    expect(n.content).toBe("x");
+  });
+
+  it("FX-COMMENT-LINE — comment inside frontmatter is skipped", () => {
+    const n = parseFixture("CM.md", "---\n# a yaml comment\nid: cm1\n---\nbody");
+    expect(n.path).toBe("CM");
+    expect(n.id).toBe("cm1");
+    expect(n.content).toBe("body");
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-NO-FRONTMATTER — plain markdown, inline tag only", () => {
+    const content = "# Title\n\nbody with #tag";
+    const n = parseFixture("P.md", content);
+    expect(n.path).toBe("P");
+    expect(n.id).toBeUndefined();
+    expect(tags(n)).toEqual(["tag"]);
+    expect(n.content).toBe(content);
+    expect(n.frontmatter).toEqual({});
+  });
+
+  it("FX-METADATA-EXCLUSIONS — all seven hoisted keys excluded from metadata", () => {
+    const n = parseFixture(
+      "M.md",
+      "---\nid: i\npath: P/Q\ntags: [t]\ncreated_at: 2024\ncreatedAt: 2024\nupdated_at: 2024\nupdatedAt: 2024\nextra: keep\n---\nb",
+    );
+    expect(n.path).toBe("P/Q");
+    expect(n.id).toBe("i");
+    expect(tags(n)).toEqual(["t"]);
+    expect(n.createdAt).toBe("2024");
+    expect(n.updatedAt).toBe("2024");
+    expect(n.content).toBe("b");
+    expect(n.frontmatter).toEqual({ extra: "keep" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Write tier — real `importObsidianNotes` adapter against an in-memory Store.
+// ---------------------------------------------------------------------------
+
+describe("alignment: write tier (importObsidianNotes adapter)", () => {
+  let store: SqliteStore;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+  });
+
+  it("FX-CREATED-AT — timestamps pegged on the id path (not new Date())", async () => {
+    const note = parseFixture(
+      "CA.md",
+      "---\nid: t1\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(0);
+    const stored = (await store.getNote("t1"))!;
+    expect(stored).toBeTruthy();
+    expect(stored.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(stored.updatedAt).toBe("2024-06-01T12:00:00Z");
+  });
+
+  it("FX-CREATED-AT (no-id variant) — minted note still gets the frontmatter created_at", async () => {
+    const note = parseFixture(
+      "CA.md",
+      "---\ncreated_at: 2024-05-01T10:00:00Z\nupdated_at: 2024-06-01T12:00:00Z\n---\nbody",
+    );
+    expect(note.id).toBeUndefined();
+    const { imported } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    const stored = (await store.getNoteByPath("CA"))!;
+    expect(stored).toBeTruthy();
+    expect(stored.createdAt).toBe("2024-05-01T10:00:00Z");
+    expect(stored.updatedAt).toBe("2024-06-01T12:00:00Z");
+  });
+
+  it("FX-ID-COLLISION — id-upsert path guard skips, does not overwrite", async () => {
+    // Pre-seed a note id=dup1 at path Existing/Place.
+    await store.createNoteRaw("original body", { id: "dup1", path: "Existing/Place" });
+    const before = (await store.getNote("dup1"))!;
+
+    const note = parseFixture("anything.md", "---\nid: dup1\npath: Different/Place\n---\nnew body");
+    expect(note.id).toBe("dup1");
+    expect(note.path).toBe("Different/Place");
+
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(0);
+    expect(skipped).toBe(1);
+
+    // The pre-existing note is untouched.
+    const after = (await store.getNote("dup1"))!;
+    expect(after.content).toBe("original body");
+    expect(after.path).toBe("Existing/Place");
+    expect(before.content).toBe(after.content);
+    // No new note created at Different/Place.
+    expect(await store.getNoteByPath("Different/Place")).toBeNull();
+  });
+
+  it("FX-SAME-STEM-COLLISION — Foo.md + Foo.markdown → 1 created, 1 skipped, no throw", async () => {
+    const fooMd = parseFixture("Foo.md", "AAA");
+    const fooMarkdown = parseFixture("Foo.markdown", "BBB");
+    expect(fooMd.path).toBe("Foo");
+    expect(fooMarkdown.path).toBe("Foo");
+
+    // Sorted walk order: Foo.markdown sorts before Foo.md.
+    const { imported, skipped } = await importObsidianNotes(store, [fooMarkdown, fooMd]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(1);
+
+    const stored = (await store.getNoteByPath("Foo"))!;
+    expect(stored).toBeTruthy();
+    expect(["AAA", "BBB"]).toContain(stored.content);
+  });
+
+  it("intra-batch collision survives even when dedup is bypassed (try/catch isolation)", async () => {
+    // Two no-id notes at the same path but built so the second slips past
+    // the seenPaths guard would still be caught by the UNIQUE insert. Here
+    // we exercise the belt-and-suspenders try/catch by forcing a duplicate
+    // through with distinct objects (same normalized path).
+    const a: ObsidianNote = { path: "Dup", content: "one", frontmatter: {}, tags: [] };
+    const b: ObsidianNote = { path: "Dup", content: "two", frontmatter: {}, tags: [] };
+    const { imported, skipped } = await importObsidianNotes(store, [a, b]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(1);
+    expect((await store.getNoteByPath("Dup"))!.content).toBe("one");
+  });
+
+  it("id-upsert same-path updates content + replaces tags", async () => {
+    await store.createNoteRaw("v1", { id: "up1", path: "Same/Place", tags: ["old"] });
+    const note = parseFixture("x.md", "---\nid: up1\npath: Same/Place\ntags: [new]\n---\nv2");
+    const { imported, skipped } = await importObsidianNotes(store, [note]);
+    expect(imported).toBe(1);
+    expect(skipped).toBe(0);
+    const stored = (await store.getNote("up1"))!;
+    expect(stored.content).toBe("v2");
+    expect(stored.tags).toEqual(["new"]);
+  });
+});

package/core/src/obsidian.ts

@@ -33,23 +33,41 @@ export {
   parseFrontmatter,
   extractInlineTags,
   walkMarkdownFiles,
+  normalizeTagValue,
+  isMarkdownExtension,
+  isExcludedPath,
 } from "./portable-md.js";
 
-import { parseFrontmatter, walkMarkdownFiles, extractInlineTags } from "./portable-md.js";
+import {
+  parseFrontmatter,
+  walkMarkdownFiles,
+  extractInlineTags,
+  normalizeTagValue,
+} from "./portable-md.js";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
 export interface ObsidianNote {
-  /** Relative path without .md extension (e.g., "Projects/Parachute/README") */
+  /** Relative path without .md/.markdown extension (e.g.,
+   *  "Projects/Parachute/README"). A frontmatter `path:` override wins. */
   path: string;
   /** Raw markdown content (frontmatter stripped) */
   content: string;
-  /** Parsed YAML frontmatter */
+  /** Parsed YAML frontmatter with hoisted keys (id/path/tags/timestamps)
+   *  removed — i.e. the metadata bag the importer persists. */
   frontmatter: Record<string, unknown>;
   /** Tags from both frontmatter and inline #tags */
   tags: string[];
+  /** Frontmatter `id` (string, trimmed, non-empty), if present. The write
+   *  adapter upserts-by-id when set. Absent → field omitted. */
+  id?: string;
+  /** Frontmatter `created_at` / `createdAt` (verbatim string, no Date
+   *  coercion), if present. Preserved on write. */
+  createdAt?: string;
+  /** Frontmatter `updated_at` / `updatedAt` (verbatim string), if present. */
+  updatedAt?: string;
 }
 
 export interface ImportStats {
@@ -60,13 +78,43 @@ export interface ImportStats {
   errors: { path: string; error: string }[];
 }
 
-/** Tags from frontmatter (handles both array and string formats). */
+/**
+ * Tags from frontmatter (handles both array and string formats), routed
+ * through the canonical `normalizeTagValue` (contract C6 / §1.4) so they
+ * are slug-validated, lowercased, and `#`-stripped identically to the web
+ * parser. A string value is split on `/[,\s]+/` (comma OR whitespace).
+ * Invalid values (`My Tag!`, non-scalars) are dropped.
+ */
 function extractFrontmatterTags(frontmatter: Record<string, unknown>): string[] {
   const raw = frontmatter.tags;
-  if (!raw) return [];
-  if (Array.isArray(raw)) return raw.map((t) => String(t).toLowerCase().trim()).filter(Boolean);
-  if (typeof raw === "string") return raw.split(",").map((t) => t.toLowerCase().trim()).filter(Boolean);
-  return [];
+  if (raw === undefined || raw === null) return [];
+  const candidates: unknown[] = Array.isArray(raw)
+    ? raw
+    : typeof raw === "string"
+      ? raw.split(/[,\s]+/)
+      : [];
+  const out: string[] = [];
+  for (const c of candidates) {
+    const tag = normalizeTagValue(c);
+    if (tag) out.push(tag);
+  }
+  return out;
+}
+
+/**
+ * Normalize an import path (contract §1.8). Case-PRESERVING: backslash →
+ * forward slash, strip trailing `.md`/`.markdown`, collapse repeated
+ * slashes, trim leading/trailing slashes. Empty result → "". Does not
+ * lowercase or slugify (friend-friendly paths). Agrees with the Store's
+ * `paths.ts::normalizePath` on the slug rules; additionally strips
+ * `.markdown` and returns "" (not null) for empty.
+ */
+function normalizeImportPath(p: string): string {
+  return p
+    .replace(/\\/g, "/")
+    .replace(/\.(md|markdown)$/i, "")
+    .replace(/\/+/g, "/")
+    .replace(/^\/+|\/+$/g, "");
 }
 
 // ---------------------------------------------------------------------------
@@ -77,20 +125,59 @@ export function parseObsidianFile(filePath: string, vaultRoot: string): Obsidian
   const raw = readFileSync(filePath, "utf-8");
   const { frontmatter, content } = parseFrontmatter(raw);
 
-  // Path: relative to vault root, without .md extension
-  const rel = relative(vaultRoot, filePath);
-  const path = rel.replace(/\.md$/i, "");
+  // Path: a frontmatter `path:` override wins (contract §1.8); otherwise
+  // derive from the source filename. Both routed through the
+  // case-preserving `normalizeImportPath` (strips .md/.markdown,
+  // backslash→/, collapse + trim slashes).
+  const fmPath = frontmatter.path;
+  const path =
+    typeof fmPath === "string" && fmPath.trim() !== ""
+      ? normalizeImportPath(fmPath.trim())
+      : normalizeImportPath(relative(vaultRoot, filePath));
+
+  // Hoist id (contract §1.5) — string, trimmed, non-empty.
+  const rawId = frontmatter.id;
+  const id =
+    typeof rawId === "string" && rawId.trim() !== "" ? rawId.trim() : undefined;
+
+  // Hoist created_at/updated_at (contract §1.6) — verbatim string, with
+  // camelCase fallback, NO Date coercion.
+  const createdAt = hoistTimestamp(frontmatter.created_at ?? frontmatter.createdAt);
+  const updatedAt = hoistTimestamp(frontmatter.updated_at ?? frontmatter.updatedAt);
 
-  // Merge tags from frontmatter and inline
+  // Merge tags from frontmatter and inline.
   const fmTags = extractFrontmatterTags(frontmatter);
   const inlineTags = extractInlineTags(content);
   const allTags = [...new Set([...fmTags, ...inlineTags])];
 
-  // Remove tags from metadata (they go to the tags table)
+  // Strip all hoisted keys from the metadata bag (contract C7) — they
+  // become first-class note fields / the tags table, not metadata.
   const metadata = { ...frontmatter };
+  delete metadata.id;
+  delete metadata.path;
   delete metadata.tags;
+  delete metadata.created_at;
+  delete metadata.createdAt;
+  delete metadata.updated_at;
+  delete metadata.updatedAt;
+
+  const note: ObsidianNote = { path, content, frontmatter: metadata, tags: allTags };
+  if (id !== undefined) note.id = id;
+  if (createdAt !== undefined) note.createdAt = createdAt;
+  if (updatedAt !== undefined) note.updatedAt = updatedAt;
+  return note;
+}
 
-  return { path, content, frontmatter: metadata, tags: allTags };
+/** Coerce a hoisted timestamp frontmatter value to a verbatim trimmed
+ *  string (contract §1.6) — no Date coercion. Numbers (e.g. a bare year
+ *  `2024`) stringify; non-scalars are dropped. */
+function hoistTimestamp(v: unknown): string | undefined {
+  if (typeof v === "string") {
+    const t = v.trim();
+    return t === "" ? undefined : t;
+  }
+  if (typeof v === "number") return String(v);
+  return undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -131,6 +218,139 @@ export function parseObsidianVault(vaultPath: string): {
   return { notes, errors };
 }
 
+// ---------------------------------------------------------------------------
+// Legacy import write adapter (contract C10)
+// ---------------------------------------------------------------------------
+
+import type { Note } from "./types.js";
+
+/**
+ * The Store surface `importObsidianNotes` needs. `SqliteStore` satisfies
+ * this structurally; defined locally (rather than importing the full
+ * `Store` interface) because `createNoteRaw` is a Store-implementation
+ * method, not on the public `Store` interface.
+ */
+export interface ImportWriteStore {
+  getNote(id: string): Promise<Note | null>;
+  getNoteByPath(path: string, extension?: string): Promise<Note | null>;
+  createNoteRaw(
+    content: string,
+    opts?: {
+      id?: string;
+      path?: string;
+      tags?: string[];
+      metadata?: Record<string, unknown>;
+      created_at?: string;
+      extension?: string;
+    },
+  ): Promise<Note>;
+  updateNote(
+    id: string,
+    updates: { content?: string; path?: string; metadata?: Record<string, unknown> },
+  ): Promise<Note>;
+  tagNote(noteId: string, tags: string[]): Promise<void>;
+  untagNote(noteId: string, tags: string[]): Promise<void>;
+  restoreNoteTimestamps(id: string, createdAt: string, updatedAt: string): Promise<void>;
+}
+
+/**
+ * Write parsed Obsidian notes into the Store (legacy import path —
+ * contract C10). Behavior:
+ *
+ *  - **id-aware upsert** (correction #4): a frontmatter `id` upserts by id.
+ *    If that id already exists at a DIFFERENT path, the import does NOT
+ *    overwrite the unrelated note — it skips with a warning. Same id +
+ *    same/absent path updates in place.
+ *  - **timestamp preservation** (correction #3): frontmatter
+ *    `created_at`/`updated_at` are pegged via `restoreNoteTimestamps` on
+ *    BOTH the id and no-id branches (the no-id path mints an id first).
+ *  - **intra-batch path-dedup + write isolation** (correction #5):
+ *    `Foo.md` + `Foo.markdown` both normalize to path `Foo`; the second is
+ *    counted skipped (dedup OR a caught `PathConflictError`). Each note's
+ *    write is wrapped in try/catch so one failure never aborts the batch.
+ *
+ * Does NOT run wikilink sync — the caller does a single post-batch pass
+ * (much faster for large vaults). Returns `{ imported, skipped }`.
+ */
+export async function importObsidianNotes(
+  store: ImportWriteStore,
+  notes: ObsidianNote[],
+): Promise<{ imported: number; skipped: number }> {
+  let imported = 0;
+  let skipped = 0;
+
+  // `getNoteByPath` matches COLLATE NOCASE, so the dedup key is lowercased.
+  const seenPaths = new Set<string>();
+
+  for (const note of notes) {
+    const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
+
+    try {
+      if (note.id) {
+        const existing = await store.getNote(note.id);
+        if (existing && existing.path != null && note.path && existing.path !== note.path) {
+          console.warn(
+            `skip: id ${note.id} exists at "${existing.path}", incoming path "${note.path}" differs`,
+          );
+          skipped++;
+          continue;
+        }
+        if (existing) {
+          await store.updateNote(note.id, {
+            content: note.content,
+            ...(note.path ? { path: note.path } : {}),
+            ...(metadata ? { metadata: metadata as Record<string, unknown> } : {}),
+          });
+          if (existing.tags && existing.tags.length > 0) await store.untagNote(note.id, existing.tags);
+          if (note.tags.length > 0) await store.tagNote(note.id, note.tags);
+        } else {
+          await store.createNoteRaw(note.content, {
+            id: note.id,
+            path: note.path || undefined,
+            tags: note.tags.length > 0 ? note.tags : undefined,
+            metadata: metadata as Record<string, unknown>,
+          });
+        }
+        if (note.createdAt) {
+          await store.restoreNoteTimestamps(note.id, note.createdAt, note.updatedAt ?? note.createdAt);
+        }
+        if (note.path) seenPaths.add(note.path.toLowerCase());
+        imported++;
+      } else {
+        const key = (note.path || "").toLowerCase();
+        if (note.path && seenPaths.has(key)) {
+          skipped++;
+          continue;
+        }
+        const existing = note.path ? await store.getNoteByPath(note.path) : null;
+        if (existing) {
+          skipped++;
+          if (note.path) seenPaths.add(key);
+          continue;
+        }
+        const created = await store.createNoteRaw(note.content, {
+          path: note.path || undefined,
+          tags: note.tags.length > 0 ? note.tags : undefined,
+          metadata: metadata as Record<string, unknown>,
+        });
+        if (note.path) seenPaths.add(key);
+        if (note.createdAt) {
+          await store.restoreNoteTimestamps(created.id, note.createdAt, note.updatedAt ?? note.createdAt);
+        }
+        imported++;
+      }
+    } catch (err) {
+      // A collision that slips past the dedup (or a path-conflict on the
+      // id-upsert branch) throws from the UNIQUE insert. Collect + continue
+      // rather than aborting the whole import (correction #5).
+      console.warn(`skip: ${note.path}: ${err instanceof Error ? err.message : String(err)}`);
+      skipped++;
+    }
+  }
+
+  return { imported, skipped };
+}
+
 // ---------------------------------------------------------------------------
 // Legacy export — kept for back-compat. New code: use `toPortableMarkdown`.
 // ---------------------------------------------------------------------------