pi-obsidian-memory 0.0.1 → 0.1.0

package/src/services/vault/bootstrap/write.ts

@@ -0,0 +1,47 @@
+import { join } from "node:path"
+
+import type { VaultCatalogFailure } from "#src/domain"
+import { catalogFailure, catalogIoFailure, resolveCatalogEntry } from "#src/services/vault/catalog"
+import { publishExclusively } from "#src/services/vault/filesystem"
+import type { Done } from "#src/shared"
+import { existingAsset } from "./paths.ts"
+import type { AssetWriteRequest } from "./types.ts"
+
+export async function createAssetExclusively(request: AssetWriteRequest): Promise<Done | VaultCatalogFailure> {
+  const existing = await existingAsset(request)
+  if (!existing.succeeded) return existing
+  if (existing.output !== "") return preserveAsset(request, existing.output)
+  const parent = await resolveCatalogEntry({ root: request.root, path: request.folder })
+  if (!parent.succeeded) return parent
+  return publishAsset(request, parent.output.absolutePath)
+}
+
+async function publishAsset(request: AssetWriteRequest, parent: string): Promise<Done | VaultCatalogFailure> {
+  const path = [request.folder, request.name].filter((part) => part !== "").join("/")
+  try {
+    const written = await publishExclusively(join(parent, request.name), request.content)
+    if (!written.succeeded) {
+      if (written.reason !== "exists") {
+        return { succeeded: false, path, scope: "file", reason: "not-writable", problems: written.problems }
+      }
+      request.progress.maintenanceProblems.push(...written.problems)
+      return preserveAsset(request, path)
+    }
+    if (written.maintenanceProblems) request.progress.maintenanceProblems.push(...written.maintenanceProblems)
+    request.progress.created.push(path)
+    return { succeeded: true }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path, scope: "file" })
+    throw error
+  }
+}
+
+async function preserveAsset(request: AssetWriteRequest, path: string): Promise<Done | VaultCatalogFailure> {
+  const resolved = await resolveCatalogEntry({ root: request.root, path })
+  if (!resolved.succeeded) return resolved
+  if (resolved.output.kind !== "file") {
+    return catalogFailure({ path, scope: "file", reason: "not-file", problem: "The asset path is not a regular file" })
+  }
+  request.progress.preserved.push(path)
+  return { succeeded: true }
+}

package/src/services/vault/catalog/bytes.ts

@@ -0,0 +1,51 @@
+import { open, stat } from "node:fs/promises"
+
+import type { VaultCatalogFailure } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { hashOf } from "#src/services/vault/filesystem"
+import { catalogFailure, catalogIoFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+import { catalogStat, sameCatalogStat } from "./stat.ts"
+import type { CatalogBytesResult, CatalogReadRequest, ResolvedCatalogEntry } from "./types.ts"
+
+export async function readCatalogBytes(vault: VaultContext, request: CatalogReadRequest): Promise<CatalogBytesResult> {
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const resolved = await resolveCatalogEntry({ root: root.output, path: request.path })
+  if (!resolved.succeeded) return resolved
+  if (resolved.output.kind !== "file") {
+    return catalogFailure({ path: request.path, scope: "file", reason: "not-file", problem: "Expected a regular file" })
+  }
+  try {
+    return await readStableBytes(resolved.output, request)
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: request.path, scope: "file" })
+    throw error
+  }
+}
+
+async function readStableBytes(entry: ResolvedCatalogEntry, request: CatalogReadRequest): Promise<CatalogBytesResult> {
+  const before = entry.stat
+  if (request.expectedStat && !sameCatalogStat(before, request.expectedStat)) return changed(request.path)
+  const file = await open(entry.absolutePath, "r")
+  try {
+    const opened = catalogStat(await file.stat())
+    if (!sameCatalogStat(before, opened)) return changed(request.path)
+    const bytes = await file.readFile()
+    const after = catalogStat(await file.stat())
+    if (!sameCatalogStat(before, after)) return changed(request.path)
+    if (!sameCatalogStat(after, catalogStat(await stat(entry.absolutePath)))) return changed(request.path)
+    return { succeeded: true, output: { path: request.path, bytes, rawHash: hashOf(bytes), stat: after } }
+  } finally {
+    await file.close()
+  }
+}
+
+function changed(path: string): VaultCatalogFailure {
+  return catalogFailure({
+    path,
+    scope: "file",
+    reason: "changed",
+    problem: "The file changed while collecting its snapshot",
+  })
+}

package/src/services/vault/catalog/dont-forget.ts

@@ -0,0 +1 @@
+export { isLoadedDontForget } from "#src/domain"

package/src/services/vault/catalog/enumerate.ts

@@ -0,0 +1,69 @@
+import type { Dirent } from "node:fs"
+import { readdir } from "node:fs/promises"
+
+import { catalogFileKind, isCatalogHidden, isCatalogNotePath, type VaultEnumerationResult } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogIoFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot, resolveListedEntry } from "./resolve.ts"
+import type { CatalogResolveResult, CatalogWalk, CatalogWalkRequest } from "./types.ts"
+import { visitCatalogEntry } from "./visit.ts"
+
+export async function enumerateVault(vault: VaultContext): Promise<VaultEnumerationResult> {
+  return walkVault({ vault, mode: "memory" })
+}
+
+export async function walkVault(request: CatalogWalkRequest): Promise<VaultEnumerationResult> {
+  const root = await resolveCatalogRoot(request.vault)
+  if (!root.succeeded) return root
+  const walk: CatalogWalk = {
+    ...request,
+    root: root.output,
+    pending: [""],
+    inventory: { entries: [], observedPaths: [], completeDirectories: [], failures: [], aliases: [] },
+  }
+  while (walk.pending.length > 0) {
+    const folder = walk.pending.pop()
+    if (typeof folder === "string") await enumerateDirectory(walk, folder)
+  }
+  walk.inventory.entries.sort((a, b) => a.path.localeCompare(b.path))
+  return { succeeded: true, output: walk.inventory }
+}
+
+async function enumerateDirectory(walk: CatalogWalk, folder: string): Promise<void> {
+  const resolved = await resolveCatalogEntry({ root: walk.root, path: folder })
+  if (!resolved.succeeded) {
+    walk.inventory.failures.push({ ...resolved, scope: "directory" })
+    return
+  }
+  try {
+    const canonicalFolder = resolved.output.canonicalPath === folder
+    const entries = await readdir(resolved.output.absolutePath, { withFileTypes: true })
+    walk.inventory.completeDirectories.push(folder)
+    for (const entry of entries) {
+      const path = [folder, entry.name].filter((part) => part !== "").join("/")
+      if (skipEntry(walk, path, entry.isDirectory())) continue
+      walk.inventory.observedPaths.push(path)
+      visitCatalogEntry(walk, path, await resolveListing(walk, path, entry, canonicalFolder))
+    }
+  } catch (error) {
+    if (!(error instanceof Error)) throw error
+    walk.inventory.failures.push(catalogIoFailure(error, { path: folder, scope: "directory" }))
+  }
+}
+
+async function resolveListing(
+  walk: CatalogWalk,
+  path: string,
+  entry: Dirent,
+  canonicalFolder: boolean,
+): Promise<CatalogResolveResult> {
+  const location = { root: walk.root, path }
+  if (canonicalFolder) return resolveListedEntry(location, entry)
+  return resolveCatalogEntry(location)
+}
+
+function skipEntry(walk: CatalogWalk, path: string, directory: boolean): boolean {
+  if (walk.mode === "export") return isCatalogHidden(path) || catalogFileKind(path) === "temporary"
+  if (directory) return isCatalogHidden(path)
+  return isCatalogHidden(path) && !isCatalogNotePath(path) && catalogFileKind(path) !== "temporary"
+}

package/src/services/vault/catalog/export.ts

@@ -0,0 +1,21 @@
+import type { VaultCatalogFailure, VaultExportFile, VaultExportResult } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { readCatalogBytes } from "./bytes.ts"
+import { walkVault } from "./enumerate.ts"
+
+export async function collectExportFiles(vault: VaultContext): Promise<VaultExportResult> {
+  const scan = await walkVault({ vault, mode: "export" })
+  if (!scan.succeeded) return { succeeded: false, failures: [scan], problems: scan.problems }
+  const failures: VaultCatalogFailure[] = [...scan.output.failures]
+  const files: VaultExportFile[] = []
+  for (const entry of scan.output.entries) {
+    if (entry.kind === "folder" || entry.kind === "temporary") continue
+    const read = await readCatalogBytes(vault, { path: entry.path, expectedStat: entry.stat })
+    if (read.succeeded) files.push(read.output)
+    else failures.push(read)
+  }
+  if (failures.length > 0) {
+    return { succeeded: false, failures, problems: failures.flatMap((failure) => failure.problems) }
+  }
+  return { succeeded: true, output: files }
+}

package/src/services/vault/catalog/failures.ts

@@ -0,0 +1,16 @@
+import type { VaultCatalogFailure } from "#src/domain"
+import type { CatalogFailureDetail, CatalogOperation } from "./types.ts"
+
+export function catalogFailure(detail: CatalogFailureDetail): VaultCatalogFailure {
+  return { succeeded: false, path: detail.path, scope: detail.scope, reason: detail.reason, problems: [detail.problem] }
+}
+
+export function catalogIoFailure(error: Error, operation: CatalogOperation): VaultCatalogFailure {
+  let reason: VaultCatalogFailure["reason"] = "io-error"
+  if ("code" in error) {
+    if (error.code === "ENOENT") reason = "not-found"
+    if (error.code === "ENOTDIR") reason = "not-directory"
+    if (error.code === "EACCES" || error.code === "EPERM" || error.code === "EBUSY") reason = "unreadable"
+  }
+  return catalogFailure({ ...operation, reason, problem: error.message })
+}

package/src/services/vault/catalog/index.ts

@@ -0,0 +1,10 @@
+export * from "./bytes.ts"
+export * from "./dont-forget.ts"
+export * from "./enumerate.ts"
+export * from "./export.ts"
+export * from "./failures.ts"
+export * from "./inspect.ts"
+export * from "./observe.ts"
+export * from "./resolve.ts"
+export * from "./stat.ts"
+export * from "./types.ts"

package/src/services/vault/catalog/inspect.ts

@@ -0,0 +1,41 @@
+import {
+  analyzeVaultNote,
+  type InspectedVaultFile,
+  isCatalogNotePath,
+  isRootArchive,
+  type VaultExportFile,
+  type VaultFileRequest,
+  type VaultInspectionResult,
+} from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { readCatalogBytes } from "./bytes.ts"
+import { catalogFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+
+export async function inspectVaultFile(vault: VaultContext, request: VaultFileRequest): Promise<VaultInspectionResult> {
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const resolved = await resolveCatalogEntry({ root: root.output, path: request.path })
+  if (!resolved.succeeded) return resolved
+  const canonicalPath = resolved.output.canonicalPath
+  if (resolved.output.kind !== "file" || ![request.path, canonicalPath].every(isCatalogNotePath)) {
+    return catalogFailure({
+      path: request.path,
+      scope: "file",
+      reason: "excluded",
+      problem: "This path is not a memory note",
+    })
+  }
+
+  const raw = await readCatalogBytes(vault, { ...request, expectedStat: resolved.output.stat })
+  if (!raw.succeeded) return raw
+  return { succeeded: true, output: inspectContent(vault, raw.output, canonicalPath) }
+}
+
+function inspectContent(vault: VaultContext, raw: VaultExportFile, canonicalPath: string): InspectedVaultFile {
+  const text = Buffer.from(raw.bytes).toString("utf8")
+  const archived = isRootArchive(raw.path) || isRootArchive(canonicalPath)
+  const statement = canonicalPath.slice(canonicalPath.lastIndexOf("/") + 1, -3)
+  const analysis = analyzeVaultNote({ statement, text, archived, limits: vault.limits })
+  return { path: raw.path, canonicalPath, text, rawHash: raw.rawHash, stat: raw.stat, archived, analysis }
+}

package/src/services/vault/catalog/observe.ts

@@ -0,0 +1,35 @@
+import { isCatalogHidden, isRootTemplate, type VaultFileRequest } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogFailure } from "./failures.ts"
+import { resolveCatalogEntry, resolveCatalogRoot } from "./resolve.ts"
+import type { CatalogResolveResult } from "./types.ts"
+
+export async function observeVaultPath(vault: VaultContext, request: VaultFileRequest): Promise<CatalogResolveResult> {
+  let path = request.path
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1)
+  const root = await resolveCatalogRoot(vault)
+  if (!root.succeeded) return root
+  const entry = await resolveCatalogEntry({ root: root.output, path })
+  if (!entry.succeeded) return entry
+  if (request.path.endsWith("/") && entry.output.kind !== "directory") {
+    return catalogFailure({
+      path: request.path,
+      scope: "directory",
+      reason: "not-directory",
+      problem: "Expected a folder",
+    })
+  }
+  if (entry.output.kind === "directory" && ![path, entry.output.canonicalPath].every(isReadableFolder)) {
+    return catalogFailure({
+      path: request.path,
+      scope: "directory",
+      reason: "excluded",
+      problem: "This folder is not readable memory",
+    })
+  }
+  return entry
+}
+
+function isReadableFolder(path: string): boolean {
+  return !isCatalogHidden(path) && !isRootTemplate(path)
+}

package/src/services/vault/catalog/resolve.ts

@@ -0,0 +1,94 @@
+import type { Dirent } from "node:fs"
+import { lstat, realpath, stat } from "node:fs/promises"
+import { isAbsolute, join, relative, sep } from "node:path"
+
+import { isSafeCatalogPath } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { catalogFailure, catalogIoFailure } from "./failures.ts"
+import { catalogEntryKind, catalogStat } from "./stat.ts"
+import type { CatalogLocation, CatalogResolveResult, CatalogRootResult } from "./types.ts"
+
+export async function resolveCatalogRoot(vault: VaultContext): Promise<CatalogRootResult> {
+  try {
+    const root = await realpath(vault.path)
+    if (!(await stat(root)).isDirectory()) {
+      return catalogFailure({
+        path: "",
+        scope: "directory",
+        reason: "not-directory",
+        problem: "The vault root is not a directory",
+      })
+    }
+    return { succeeded: true, output: root }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: "", scope: "directory" })
+    throw error
+  }
+}
+
+export async function resolveCatalogEntry(location: CatalogLocation): Promise<CatalogResolveResult> {
+  if (location.path !== "" && !isSafeCatalogPath(location.path)) {
+    return catalogFailure({
+      path: location.path,
+      scope: "entry",
+      reason: "invalid-path",
+      problem: "Expected a safe vault-relative path with / separators",
+    })
+  }
+  try {
+    const resolved = await resolveComponents(location)
+    if (!resolved.succeeded) return resolved
+    const stats = await stat(resolved.output)
+    return {
+      succeeded: true,
+      output: {
+        absolutePath: resolved.output,
+        canonicalPath: relative(location.root, resolved.output).split(sep).join("/"),
+        kind: catalogEntryKind(stats),
+        stat: catalogStat(stats),
+      },
+    }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: location.path, scope: "entry" })
+    throw error
+  }
+}
+
+export async function resolveListedEntry(location: CatalogLocation, listed: Dirent): Promise<CatalogResolveResult> {
+  if (!(listed.isFile() || listed.isDirectory()) || !isSafeCatalogPath(location.path)) {
+    return resolveCatalogEntry(location)
+  }
+  const absolutePath = join(location.root, ...location.path.split("/"))
+  try {
+    const stats = await lstat(absolutePath)
+    if (stats.isSymbolicLink()) return resolveCatalogEntry(location)
+    return {
+      succeeded: true,
+      output: { absolutePath, canonicalPath: location.path, kind: catalogEntryKind(stats), stat: catalogStat(stats) },
+    }
+  } catch (error) {
+    if (error instanceof Error) return catalogIoFailure(error, { path: location.path, scope: "entry" })
+    throw error
+  }
+}
+
+async function resolveComponents(location: CatalogLocation): Promise<CatalogRootResult> {
+  let current = location.root
+  for (const part of location.path.split("/").filter((part) => part !== "")) {
+    current = await realpath(join(current, part))
+    if (!isCatalogInside(location.root, current)) {
+      return catalogFailure({
+        path: location.path,
+        scope: "entry",
+        reason: "outside-vault",
+        problem: "The path leads outside the real vault root",
+      })
+    }
+  }
+  return { succeeded: true, output: current }
+}
+
+export function isCatalogInside(root: string, path: string): boolean {
+  const rel = relative(root, path)
+  return !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`)
+}

package/src/services/vault/catalog/stat.ts

@@ -0,0 +1,23 @@
+import type { Stats } from "node:fs"
+
+import type { VaultFileStat } from "#src/domain"
+import type { ResolvedCatalogEntry } from "./types.ts"
+
+export function catalogStat(stats: Stats): VaultFileStat {
+  return { size: stats.size, mtimeMs: stats.mtimeMs, ctimeMs: stats.ctimeMs, device: stats.dev, inode: stats.ino }
+}
+
+export function catalogEntryKind(stats: Stats): ResolvedCatalogEntry["kind"] {
+  if (stats.isFile()) return "file"
+  if (stats.isDirectory()) return "directory"
+  return "other"
+}
+
+export function sameCatalogStat(left: VaultFileStat, right: VaultFileStat): boolean {
+  return (
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs &&
+    left.device === right.device &&
+    left.inode === right.inode
+  )
+}

package/src/services/vault/catalog/types.ts

@@ -0,0 +1,69 @@
+import type { VaultCatalogFailure, VaultEnumeration, VaultExportFile, VaultFileStat } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import type { Succeeded } from "#src/shared"
+
+export type {
+  InspectedVaultFile,
+  ParsedVaultNote,
+  UnclosedVaultNote,
+  VaultAlias,
+  VaultCatalogEntry,
+  VaultCatalogFailure,
+  VaultEntryKind,
+  VaultEnumeration,
+  VaultEnumerationResult,
+  VaultExportFailure,
+  VaultExportFile,
+  VaultExportResult,
+  VaultFileRequest,
+  VaultFileStat,
+  VaultInspectionResult,
+  VaultNoteAnalysis,
+  VaultNoteProblems,
+} from "#src/domain"
+
+export interface CatalogLocation {
+  root: string
+  path: string
+}
+
+export interface ResolvedCatalogEntry {
+  absolutePath: string
+  canonicalPath: string
+  kind: "file" | "directory" | "other"
+  stat: VaultFileStat
+}
+
+export interface CatalogFailureDetail {
+  path: string
+  scope: VaultCatalogFailure["scope"]
+  reason: VaultCatalogFailure["reason"]
+  problem: string
+}
+
+export interface CatalogOperation {
+  path: string
+  scope: VaultCatalogFailure["scope"]
+}
+
+export type CatalogRootResult = Succeeded<string> | VaultCatalogFailure
+export type CatalogResolveResult = Succeeded<ResolvedCatalogEntry> | VaultCatalogFailure
+export type CatalogBytesResult = Succeeded<VaultExportFile> | VaultCatalogFailure
+
+export interface CatalogReadRequest {
+  path: string
+  expectedStat?: VaultFileStat
+}
+
+export interface CatalogWalk {
+  vault: VaultContext
+  root: string
+  mode: "memory" | "export"
+  pending: string[]
+  inventory: VaultEnumeration
+}
+
+export interface CatalogWalkRequest {
+  vault: VaultContext
+  mode: CatalogWalk["mode"]
+}

package/src/services/vault/catalog/visit.ts

@@ -0,0 +1,58 @@
+import { catalogFileKind, isCatalogHidden, isCatalogNotePath, isRootArchive, isRootTemplate } from "#src/domain"
+import { catalogFailure } from "./failures.ts"
+import type { CatalogResolveResult, CatalogWalk, ResolvedCatalogEntry } from "./types.ts"
+
+export function visitCatalogEntry(walk: CatalogWalk, path: string, result: CatalogResolveResult): void {
+  if (!result.succeeded) {
+    walk.inventory.failures.push(result)
+    return
+  }
+
+  const entry = result.output
+  if (entry.kind === "directory" && isCatalogHidden(path)) return
+
+  if (entry.canonicalPath !== path) {
+    recordAlias(walk, path, entry)
+    return
+  }
+  recordPhysicalEntry(walk, entry)
+}
+
+function recordPhysicalEntry(walk: CatalogWalk, entry: ResolvedCatalogEntry): void {
+  const path = entry.canonicalPath
+  if (entry.kind === "directory") {
+    walk.inventory.entries.push({ path, kind: "folder", archived: isRootArchive(path), stat: entry.stat })
+    if (walk.mode === "export" || !isRootTemplate(path)) walk.pending.push(path)
+    return
+  }
+  if (entry.kind !== "file") {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "entry", reason: "not-file", problem: "Not a regular file or directory" }),
+    )
+    return
+  }
+  walk.inventory.entries.push({
+    path,
+    kind: catalogFileKind(path),
+    archived: isRootArchive(path),
+    stat: entry.stat,
+  })
+}
+
+function recordAlias(walk: CatalogWalk, path: string, entry: ResolvedCatalogEntry): void {
+  const target = entry.canonicalPath
+  if (entry.kind === "directory" && (target === "" || path.startsWith(`${target}/`))) {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "directory", reason: "cycle", problem: "Directory alias leads to an ancestor" }),
+    )
+    return
+  }
+  const memoryNote = walk.mode === "memory" && entry.kind === "file" && isCatalogNotePath(target)
+  if (isCatalogHidden(target) && !memoryNote) {
+    walk.inventory.failures.push(
+      catalogFailure({ path, scope: "entry", reason: "excluded", problem: "Alias leads to a hidden path" }),
+    )
+    return
+  }
+  walk.inventory.aliases.push({ path, target })
+}

package/src/services/vault/complete-blank.ts

@@ -0,0 +1,66 @@
+import { checkMemoryFolder, type Note, parseNote } from "#src/domain"
+import { inspectVaultFile } from "#src/services/vault/catalog"
+import type { VaultContext } from "#src/services/vault/context"
+import type { Succeeded } from "#src/shared"
+import type { BlankCompletionRefusal, CompleteBlankRequest, CompleteBlankResult } from "./types.ts"
+import { updateNoteFile } from "./update-file.ts"
+
+export async function completeBlankFile(
+  vault: VaultContext,
+  request: CompleteBlankRequest,
+): Promise<CompleteBlankResult> {
+  const inspected = await inspectVaultFile(vault, { path: request.path })
+  if (!inspected.succeeded) return inspected
+  const current = inspected.output
+  if (current.rawHash !== request.expectedHash) {
+    return { succeeded: false, reason: "conflict", problems: ["The blank file changed since its preview"] }
+  }
+  const note = noteToComplete(request.note, current.text)
+  if (!note.succeeded) return note
+
+  return completeInspectedBlank(vault, { ...request, note: note.output }, current.canonicalPath)
+}
+
+function noteToComplete(note: Note, text: string): Succeeded<Note> | BlankCompletionRefusal {
+  if (text.trim() === "") return { succeeded: true, output: note }
+  const parsed = parseNote(note.statement, text)
+  if (parsed.succeeded) {
+    return { succeeded: false, reason: "not-blank", problems: ["The file already has frontmatter"] }
+  }
+  if (parsed.problems.includes("frontmatter is not closed")) {
+    return { succeeded: false, reason: "not-blank", problems: parsed.problems }
+  }
+  const normalized = text.replaceAll("\r\n", "\n")
+  return { succeeded: true, output: { ...note, body: withoutFinalNewline(normalized) } }
+}
+
+function withoutFinalNewline(text: string): string {
+  if (text.endsWith("\n")) return text.slice(0, -1)
+  return text
+}
+
+async function completeInspectedBlank(
+  vault: VaultContext,
+  request: CompleteBlankRequest,
+  canonicalPath: string,
+): Promise<CompleteBlankResult> {
+  const folder = canonicalPath.slice(0, Math.max(0, canonicalPath.lastIndexOf("/")))
+  const requestedFolder = request.path.slice(0, Math.max(0, request.path.lastIndexOf("/")))
+  const problems = [...checkMemoryFolder(folder), ...checkMemoryFolder(requestedFolder)]
+  if (problems.length > 0) return { succeeded: false, reason: "invalid", problems }
+  const fileName = canonicalPath.slice(canonicalPath.lastIndexOf("/") + 1)
+  const requestedName = request.path.slice(request.path.lastIndexOf("/") + 1)
+  if (
+    fileName.slice(-3).toLowerCase() !== ".md" ||
+    fileName.slice(0, -3) !== request.note.statement ||
+    requestedName !== fileName
+  ) {
+    return {
+      succeeded: false,
+      reason: "path-mismatch",
+      problems: ["The candidate statement must match the blank file"],
+    }
+  }
+
+  return updateNoteFile(vault, { folder, fileName, note: request.note, expectedHash: request.expectedHash })
+}

package/src/services/vault/constants.ts

@@ -0,0 +1,3 @@
+export const NOTE_EXTENSION = ".md"
+
+export const FOLDER_INDEX_FILE_NAME = "index.md"

package/src/services/vault/context/index.ts

@@ -0,0 +1 @@
+export * from "./types.ts"

package/src/services/vault/context/types.ts

@@ -0,0 +1,10 @@
+import type { NoteLimits } from "#src/domain"
+
+export interface VaultContext {
+  path: string
+  limits: NoteLimits
+}
+
+export interface NamedVaultContext extends VaultContext {
+  name: string
+}

package/src/services/vault/create.ts

@@ -0,0 +1,19 @@
+import { checkMemoryFolder, checkNote, type Note } from "#src/domain"
+import type { VaultContext } from "#src/services/vault/context"
+import { resolveMemoryFolder } from "./memory-folder.ts"
+import { writeValidatedNote } from "./publish.ts"
+import type { CreateResult } from "./types.ts"
+
+export async function createMemoryNote(vault: VaultContext, folder: string, note: Note): Promise<CreateResult> {
+  const problems = [...checkMemoryFolder(folder), ...checkNote(note, vault.limits)]
+  if (problems.length > 0) {
+    return { succeeded: false, reason: "invalid", problems }
+  }
+
+  const directory = await resolveMemoryFolder(vault.path, folder)
+  if (!directory.succeeded) {
+    return directory
+  }
+
+  return writeValidatedNote(vault.path, folder, note)
+}

package/src/services/vault/display.ts

@@ -0,0 +1,6 @@
+import { joinVaultPath } from "#src/domain"
+import { noteFileName } from "./paths.ts"
+
+export function displayNotePath(folder: string, statement: string): string {
+  return joinVaultPath(folder, noteFileName(statement))
+}