pi-obsidian-memory 0.0.1 → 0.1.0

package/src/usecases/settings/change.ts

@@ -0,0 +1,142 @@
+import {
+  canonicalizeRegistration,
+  changeSetting,
+  ensureVaultAssets,
+  inspectVaultFolder,
+  type MemoryConfig,
+  readConfigSnapshot,
+  resolveRegistrationVault,
+  type SettingChange,
+  targetVault,
+  writeConfig,
+} from "#src/services"
+import type { Succeeded } from "#src/shared"
+import { captureRegistrationContext, type RegistrationContext } from "#src/usecases/registration"
+import type { SettingsChangeFailure, SettingsChangeRequest, SettingsChangeResult } from "./types.ts"
+
+function refused(problems: string[]): SettingsChangeFailure {
+  return { succeeded: false, reason: "refused", problems }
+}
+
+function interruption(context: RegistrationContext): SettingsChangeFailure | null {
+  if (context.signal.aborted || !context.session.isCurrent(context.stamp)) {
+    return { succeeded: false, reason: "cancelled", problems: ["settings cancelled or session authority changed"] }
+  }
+  return null
+}
+
+export async function changeMemorySettings(
+  request: SettingsChangeRequest,
+  callerContext: RegistrationContext,
+): Promise<SettingsChangeResult> {
+  const context = captureRegistrationContext(callerContext)
+  const captured: SettingsChangeRequest = {
+    change: structuredClone(request.change),
+    expectedHash: request.expectedHash,
+  }
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) {
+    const stopped = interruption(context)
+    if (stopped) return stopped
+    return refused(["settings session admission refused"])
+  }
+  try {
+    const stopped = interruption(context)
+    if (stopped) return stopped
+    return await applyChange(captured, context)
+  } finally {
+    lease.release()
+  }
+}
+
+async function currentConfig(
+  expectedHash: string,
+  context: RegistrationContext,
+): Promise<Succeeded<MemoryConfig> | SettingsChangeFailure> {
+  const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+  if (!snapshot.succeeded) return refused(snapshot.problems)
+  if (snapshot.output.state === "missing") return refused(["memory is not configured"])
+  if (snapshot.output.hash !== expectedHash) {
+    return { succeeded: false, reason: "conflict", problems: ["the config changed on disk since it was read"] }
+  }
+  const { lexicalParse } = snapshot.output
+  if (!lexicalParse.succeeded) return refused(lexicalParse.problems)
+  return lexicalParse
+}
+
+async function resolvedVault(
+  change: SettingChange,
+  context: RegistrationContext,
+): Promise<SettingChange | SettingsChangeFailure> {
+  if (change.kind !== "projectVault") return change
+  const vault = resolveRegistrationVault({ vault: change.vault, workingFolder: context.workingFolder })
+  if (!vault.succeeded) return refused(vault.problems)
+  const folder = await inspectVaultFolder(vault.output)
+  if (!folder.succeeded) return refused(folder.problems)
+  if (folder.output === "not-directory") return refused([`${vault.output} is a file, not a folder`])
+  return { ...change, vault: vault.output }
+}
+
+async function prepareProjectVault(
+  change: SettingChange,
+  config: MemoryConfig,
+  context: RegistrationContext,
+): Promise<Succeeded<string[]> | SettingsChangeFailure> {
+  if (change.kind !== "projectVault") return { succeeded: true, output: [] }
+  const project = config.projects.find((entry) => entry.name === change.name)
+  if (!project) return refused([`No project named "${change.name}"`])
+  const canonical = await canonicalizeRegistration({
+    config,
+    configPath: context.configPath,
+    indexPath: context.indexPath,
+    platform: context.platform,
+  })
+  if (!canonical.succeeded) return refused(canonical.problems)
+  const target = targetVault(config, "project", project.folder, context.platform)
+  if (!target.succeeded) return refused(target.problems)
+  const assets = await ensureVaultAssets({ ...target.output, limits: config.limits })
+  if (!assets.succeeded) return refused(assets.problems)
+  return { succeeded: true, output: assets.output.maintenanceProblems }
+}
+
+function isFailure(value: SettingChange | SettingsChangeFailure): value is SettingsChangeFailure {
+  return "succeeded" in value
+}
+
+async function applyChange(
+  request: SettingsChangeRequest,
+  context: RegistrationContext,
+): Promise<SettingsChangeResult> {
+  const current = await currentConfig(request.expectedHash, context)
+  if (!("output" in current)) return current
+  const change = await resolvedVault(request.change, context)
+  if (isFailure(change)) return change
+  const next = changeSetting(current.output, change, context.platform)
+  if (!next.succeeded) return refused(next.problems)
+  const stopped = interruption(context)
+  if (stopped) return stopped
+  const assets = await prepareProjectVault(change, next.output, context)
+  if (!assets.succeeded) return assets
+  const written = await writeConfig({
+    path: context.configPath,
+    platform: context.platform,
+    indexPath: context.indexPath,
+    config: next.output,
+    expectedHash: request.expectedHash,
+  })
+  if (!written.succeeded) {
+    if (written.reason === "conflict") return { succeeded: false, reason: "conflict", problems: written.problems }
+    return refused(written.problems)
+  }
+  if (context.session.isCurrent(context.stamp)) context.session.invalidate(context.stamp)
+  return {
+    succeeded: true,
+    output: {
+      configHash: written.output.hash,
+      config: next.output,
+      warnings: [...assets.output, ...written.warnings],
+    },
+  }
+}
+
+export { parseSettingNumber } from "#src/services"

package/src/usecases/settings/index.ts

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

package/src/usecases/settings/prepare.ts

@@ -0,0 +1,24 @@
+import { readConfigSnapshot } from "#src/services"
+import type { RegistrationContext } from "#src/usecases/registration"
+import { captureRegistrationContext } from "#src/usecases/registration"
+import type { SettingsPreparationResult } from "./types.ts"
+
+export async function prepareMemorySettings(callerContext: RegistrationContext): Promise<SettingsPreparationResult> {
+  const context = captureRegistrationContext(callerContext)
+  const lease = await context.session.acquire(context.stamp, context.signal)
+  if (!lease) return { succeeded: false, reason: "unreadable", problems: ["settings session admission refused"] }
+  try {
+    const snapshot = await readConfigSnapshot({ path: context.configPath, platform: context.platform })
+    if (!snapshot.succeeded) return { succeeded: false, reason: "unreadable", problems: snapshot.problems }
+    if (snapshot.output.state === "missing") {
+      return { succeeded: false, reason: "not-configured", problems: ["memory is not configured"] }
+    }
+    const { lexicalParse, hash } = snapshot.output
+    if (!lexicalParse.succeeded) {
+      return { succeeded: false, reason: "invalid-config", problems: lexicalParse.problems }
+    }
+    return { succeeded: true, output: { config: lexicalParse.output, hash } }
+  } finally {
+    lease.release()
+  }
+}

package/src/usecases/settings/types.ts

@@ -0,0 +1,32 @@
+import type { MemoryConfig, SettingChange } from "#src/services"
+import type { Failed, Succeeded } from "#src/shared"
+
+export type { MemoryConfig, ProjectEntry, SettingChange } from "#src/services"
+
+export interface SettingsPreparation {
+  config: MemoryConfig
+  hash: string
+}
+
+export interface SettingsRefusal extends Failed {
+  reason: "not-configured" | "invalid-config" | "unreadable"
+}
+
+export type SettingsPreparationResult = Succeeded<SettingsPreparation> | SettingsRefusal
+
+export interface SettingsChangeRequest {
+  change: SettingChange
+  expectedHash: string
+}
+
+export interface SettingsChanged {
+  configHash: string
+  config: MemoryConfig
+  warnings: string[]
+}
+
+export interface SettingsChangeFailure extends Failed {
+  reason: "conflict" | "refused" | "cancelled"
+}
+
+export type SettingsChangeResult = Succeeded<SettingsChanged> | SettingsChangeFailure

package/src/usecases/succeed-memory/index.ts

@@ -0,0 +1,3 @@
+export * from "./schemas.ts"
+export * from "./succeed-memory.ts"
+export * from "./types.ts"

package/src/usecases/succeed-memory/schemas.ts

@@ -0,0 +1,13 @@
+import Type from "typebox"
+
+import { MemoryDraftSchema, MemoryScopeSchema } from "#src/services"
+
+export const SucceedMemoryRequestSchema = Type.Object(
+  {
+    vault: MemoryScopeSchema,
+    path: Type.String(),
+    folder: Type.String(),
+    draft: MemoryDraftSchema,
+  },
+  { additionalProperties: false },
+)

package/src/usecases/succeed-memory/succeed-memory.ts

@@ -0,0 +1,34 @@
+import { displayNotePath, newNote, newNoteId, succeedStoredFile, today } from "#src/services"
+import { changeLeasedMemory, reportPartial, warningsOf } from "#src/usecases/memory-change"
+import type { MemoryOperationContext } from "#src/usecases/operation-context"
+import type { SucceedMemoryRequest, SucceedMemoryResult } from "./types.ts"
+
+export async function succeedMemory(
+  request: SucceedMemoryRequest,
+  context: MemoryOperationContext,
+): Promise<SucceedMemoryResult> {
+  const address = { vault: request.vault, path: request.path }
+  return changeLeasedMemory(address, context, async ({ target, receipted }) => {
+    const { note, folder, read } = receipted
+    const day = today()
+    const succeeded = await succeedStoredFile(target.vault, {
+      path: read.path,
+      previous: { folder, note },
+      hashWhenRead: read.rawHash,
+      successor: { folder: request.folder, note: newNote(request.draft, newNoteId(), day) },
+      today: day,
+    })
+    if (!succeeded.succeeded) return reportPartial(succeeded)
+    const { archived, successor } = succeeded.output
+    return {
+      succeeded: true,
+      output: {
+        vault: request.vault,
+        path: request.path,
+        archivedPath: displayNotePath(archived.folder, archived.note.statement),
+        successorPath: displayNotePath(successor.folder, successor.note.statement),
+        maintenanceProblems: warningsOf(succeeded),
+      },
+    }
+  })
+}

package/src/usecases/succeed-memory/types.ts

@@ -0,0 +1,18 @@
+import type { Static } from "typebox"
+
+import type { LifecycleRefusal, MemoryScope } from "#src/services"
+import type { Succeeded } from "#src/shared"
+import type { ChangeRefusal, PartialMemoryChange } from "#src/usecases/memory-change"
+import type { SucceedMemoryRequestSchema } from "./schemas.ts"
+
+export type SucceedMemoryRequest = Static<typeof SucceedMemoryRequestSchema>
+
+export interface SucceededMemory {
+  vault: MemoryScope
+  path: string
+  archivedPath: string
+  successorPath: string
+  maintenanceProblems: string[]
+}
+
+export type SucceedMemoryResult = Succeeded<SucceededMemory> | LifecycleRefusal | PartialMemoryChange | ChangeRefusal

package/src/usecases/synchronize-memory/index.ts

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

package/src/usecases/synchronize-memory/leased/aliases.ts

@@ -0,0 +1,55 @@
+import {
+  classifyAliasFailure,
+  inspectedCatalogEntry,
+  inspectVaultFile,
+  observeVaultPath,
+  type VaultCatalogFailure,
+} from "#src/services"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import type { CatalogSynchronization, SynchronizationScan, SynchronizationScanResult } from "./types.ts"
+
+export async function inspectScanAliases(
+  work: CatalogSynchronization,
+  scan: SynchronizationScan,
+): Promise<SynchronizationScanResult> {
+  for (const alias of scan.enumeration.aliases) {
+    const interrupted = memoryOperationInterruption(work.context)
+    if (interrupted) return interrupted
+    const observed = await observeVaultPath(work.target.vault, { path: alias.path })
+    const stale = memoryOperationInterruption(work.context)
+    if (stale) return stale
+    if (!observed.succeeded) {
+      recordAliasFailure(scan, observed)
+    } else if (observed.output.kind === "directory") {
+      scan.catalog.untraversedAliasDirectories.push(alias.path)
+    } else {
+      await inspectAliasFile(work, scan, alias.path)
+      const cancelled = memoryOperationInterruption(work.context)
+      if (cancelled) return cancelled
+    }
+  }
+  return { succeeded: true, output: scan }
+}
+
+async function inspectAliasFile(work: CatalogSynchronization, scan: SynchronizationScan, path: string): Promise<void> {
+  const inspected = await inspectVaultFile(work.target.vault, { path })
+  if (memoryOperationInterruption(work.context)) return
+  if (inspected.succeeded) {
+    scan.catalog.entries.push(inspectedCatalogEntry(inspected.output, scan.catalog.validationFingerprint))
+  } else {
+    recordAliasFailure(scan, inspected)
+  }
+}
+
+export function recordAliasFailure(scan: SynchronizationScan, failure: VaultCatalogFailure): void {
+  const classified = classifyAliasFailure(failure)
+  if (classified.kind === "untraversed-directory") {
+    scan.catalog.untraversedAliasDirectories.push(classified.path)
+  } else if (classified.kind === "excluded-file") {
+    scan.catalog.excludedAliasFiles.push(classified.path)
+  } else {
+    scan.catalog.failedPaths.push(classified.path)
+    scan.catalog.complete = false
+    scan.warnings.push(...classified.problems)
+  }
+}

package/src/usecases/synchronize-memory/leased/folder-states.ts

@@ -0,0 +1,58 @@
+import type {
+  FolderIndexState,
+  FolderListingFingerprint,
+  RefreshedFolder,
+  VaultEnumeration,
+  VaultFileStat,
+} from "#src/services"
+
+export function dirtyFolders(
+  enumeration: VaultEnumeration,
+  fingerprints: FolderListingFingerprint[],
+  stored: FolderIndexState[],
+): string[] {
+  const states = new Map(stored.map((state) => [state.folder, state]))
+  const indexStats = new Map<string, VaultFileStat>()
+  for (const entry of enumeration.entries) {
+    if (entry.kind === "index") indexStats.set(parentFolder(entry.path), entry.stat)
+  }
+  return fingerprints
+    .filter(({ folder, fingerprint }) => {
+      const state = states.get(folder)
+      const stat = indexStats.get(folder)
+      if (typeof fingerprint !== "string" || !state || !stat) return true
+      return (
+        state.fingerprint !== fingerprint ||
+        state.indexSize !== stat.size ||
+        state.indexMtimeMs !== stat.mtimeMs ||
+        state.indexCtimeMs !== stat.ctimeMs ||
+        state.indexIno !== String(stat.inode)
+      )
+    })
+    .map(({ folder }) => folder)
+}
+
+export function settledStates(
+  fingerprints: FolderListingFingerprint[],
+  refreshed: RefreshedFolder[],
+): FolderIndexState[] {
+  const known = new Map(fingerprints.map(({ folder, fingerprint }) => [folder, fingerprint]))
+  const states: FolderIndexState[] = []
+  for (const { folder, index, settled } of refreshed) {
+    const fingerprint = known.get(folder)
+    if (!settled || typeof fingerprint !== "string") continue
+    states.push({
+      folder,
+      fingerprint,
+      indexSize: index.size,
+      indexMtimeMs: index.mtimeMs,
+      indexCtimeMs: index.ctimeMs,
+      indexIno: String(index.inode),
+    })
+  }
+  return states
+}
+
+function parentFolder(path: string): string {
+  return path.slice(0, Math.max(path.lastIndexOf("/"), 0))
+}

package/src/usecases/synchronize-memory/leased/index.ts

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

package/src/usecases/synchronize-memory/leased/inspection.ts

@@ -0,0 +1,32 @@
+import { type CatalogSnapshot, inspectedCatalogEntry, inspectVaultFile, reusableCatalogEntry } from "#src/services"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import type { CatalogSynchronization, SynchronizationScan, SynchronizationScanResult } from "./types.ts"
+
+export async function inspectScanEntries(
+  work: CatalogSynchronization,
+  snapshot: CatalogSnapshot,
+  scan: SynchronizationScan,
+): Promise<SynchronizationScanResult> {
+  const previous = new Map(snapshot.entries.map((entry) => [entry.path, entry]))
+  for (const file of scan.enumeration.entries) {
+    if (file.kind !== "note") continue
+    const interrupted = memoryOperationInterruption(work.context)
+    if (interrupted) return interrupted
+    const cached = previous.get(file.path)
+    if (cached && reusableCatalogEntry(file, cached, scan.catalog.validationFingerprint)) {
+      scan.catalog.entries.push(cached)
+      continue
+    }
+    const inspected = await inspectVaultFile(work.target.vault, { path: file.path })
+    const stale = memoryOperationInterruption(work.context)
+    if (stale) return stale
+    if (inspected.succeeded) {
+      scan.catalog.entries.push(inspectedCatalogEntry(inspected.output, scan.catalog.validationFingerprint))
+    } else {
+      scan.catalog.failedPaths.push(file.path)
+      scan.catalog.complete = false
+      scan.warnings.push(...inspected.problems)
+    }
+  }
+  return { succeeded: true, output: scan }
+}

package/src/usecases/synchronize-memory/leased/maintenance.ts

@@ -0,0 +1,41 @@
+import {
+  FOLDER_INDEX_FORMAT,
+  type FolderIndexState,
+  folderListingFingerprints,
+  readFolderIndexStates,
+  recordFolderIndexStates,
+  refreshFolders,
+} from "#src/services"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import { dirtyFolders, settledStates } from "./folder-states.ts"
+import type { CatalogSynchronization, SynchronizationScan } from "./types.ts"
+
+export async function maintainMemoryFolders(work: CatalogSynchronization, scan: SynchronizationScan): Promise<void> {
+  const folders = [...scan.enumeration.completeDirectories].sort()
+  if (folders.length === 0 || memoryOperationInterruption(work.context)) return
+  const renderKey = JSON.stringify([FOLDER_INDEX_FORMAT, work.target.vault.name, scan.catalog.validationFingerprint])
+  const fingerprints = folderListingFingerprints(scan.enumeration, renderKey)
+  const stored = readFolderIndexStates(work.index)
+  let known: FolderIndexState[] = []
+  if (stored.succeeded) known = stored.output
+  else {
+    work.progress.warnings.push(...stored.problems)
+    const cleared = recordFolderIndexStates(work.index, [], [])
+    if (!cleared.succeeded) work.progress.warnings.push(...cleared.problems)
+  }
+  const dirty = dirtyFolders(scan.enumeration, fingerprints, known).sort()
+  let settled: FolderIndexState[] = []
+  if (dirty.length > 0) {
+    const refreshed = await refreshFolders(
+      work.target.vault,
+      dirty,
+      () => !memoryOperationInterruption(work.context),
+      "exact",
+    )
+    if (!refreshed.succeeded) work.progress.warnings.push(...refreshed.problems)
+    else if (refreshed.maintenanceProblems) work.progress.warnings.push(...refreshed.maintenanceProblems)
+    settled = settledStates(fingerprints, refreshed.refreshed)
+  }
+  const recorded = recordFolderIndexStates(work.index, settled, folders)
+  if (!recorded.succeeded) work.progress.warnings.push(...recorded.problems)
+}

package/src/usecases/synchronize-memory/leased/publication.ts

@@ -0,0 +1,55 @@
+import {
+  applyIndexChanges,
+  type CatalogPlan,
+  type CatalogScan,
+  type CatalogSnapshot,
+  readIndexInventory,
+  reconcileCatalog,
+} from "#src/services"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import type { CatalogPublicationResult, CatalogSynchronization } from "./types.ts"
+
+export function publishMemoryCatalog(
+  work: CatalogSynchronization,
+  snapshot: CatalogSnapshot,
+  scan: CatalogScan,
+): CatalogPublicationResult {
+  const first = publishPlan(work, snapshot, scan)
+  if (first.succeeded || first.reason !== "conflict") return first
+  const interrupted = memoryOperationInterruption(work.context)
+  if (interrupted) return interrupted
+  const latest = readIndexInventory(work.index)
+  if (!latest.succeeded) return latest
+  return publishPlan(work, latest.output, scan)
+}
+
+function publishPlan(
+  work: CatalogSynchronization,
+  snapshot: CatalogSnapshot,
+  scan: CatalogScan,
+): CatalogPublicationResult {
+  const plan = reconcileCatalog(snapshot, scan)
+  const interrupted = memoryOperationInterruption(work.context)
+  if (interrupted) return interrupted
+  if (catalogChanged(plan, snapshot)) {
+    const applied = applyIndexChanges(work.index, plan)
+    if (!applied.succeeded) return applied
+    work.progress.committed = true
+    work.progress.revision = snapshot.revision + 1
+  } else {
+    work.progress.revision = snapshot.revision
+  }
+  work.progress.population = plan.population
+  work.progress.duplicateIds = plan.duplicateIds
+  if (scan.complete && plan.reinspectPaths.length === 0) work.progress.coverage = "complete"
+  return { succeeded: true, output: plan }
+}
+
+function catalogChanged(plan: CatalogPlan, snapshot: CatalogSnapshot): boolean {
+  return (
+    plan.upserts.length > 0 ||
+    plan.deletes.length > 0 ||
+    plan.statUpdates.length > 0 ||
+    plan.population !== snapshot.population
+  )
+}

package/src/usecases/synchronize-memory/leased/scan.ts

@@ -0,0 +1,37 @@
+import { type CatalogSnapshot, enumerateVault } from "#src/services"
+import { memoryOperationInterruption } from "#src/usecases/operation-context"
+import { inspectScanAliases, recordAliasFailure } from "./aliases.ts"
+import { inspectScanEntries } from "./inspection.ts"
+import type { CatalogSynchronization, SynchronizationScan, SynchronizationScanResult } from "./types.ts"
+
+export async function scanMemoryCatalog(
+  work: CatalogSynchronization,
+  snapshot: CatalogSnapshot,
+  validationFingerprint: string,
+): Promise<SynchronizationScanResult> {
+  const enumerated = await enumerateVault(work.target.vault)
+  const interrupted = memoryOperationInterruption(work.context)
+  if (interrupted) return interrupted
+  if (!enumerated.succeeded) return enumerated
+  const enumeration = enumerated.output
+  const scan: SynchronizationScan = {
+    enumeration,
+    catalog: {
+      entries: [],
+      observedPaths: enumeration.observedPaths,
+      completeDirectories: enumeration.completeDirectories,
+      failedPaths: [],
+      untraversedAliasDirectories: [],
+      excludedAliasFiles: [],
+      complete: true,
+      validationFingerprint,
+    },
+    warnings: [],
+  }
+  for (const failure of enumeration.failures) recordAliasFailure(scan, failure)
+  const inspected = await inspectScanEntries(work, snapshot, scan)
+  const stale = memoryOperationInterruption(work.context)
+  if (stale) return stale
+  if (!inspected.succeeded) return inspected
+  return inspectScanAliases(work, scan)
+}

package/src/usecases/synchronize-memory/leased/synchronize.ts

@@ -0,0 +1,102 @@
+import {
+  catalogValidationFingerprint,
+  closeIndex,
+  indexFileFor,
+  type OpenedIndex,
+  type OpenIndexResult,
+  readIndexInventory,
+  recoverIndex,
+} from "#src/services"
+import { type MemoryOperationContext, memoryOperationInterruption } from "#src/usecases/operation-context"
+import {
+  type ResolvedMemory,
+  type ResolvedVault,
+  resolveLeasedMemory,
+  selectMemoryVault,
+} from "#src/usecases/resolve-memory/leased"
+import { refreshSemantic, semanticPortOf } from "#src/usecases/semantic"
+import type { SemanticPort } from "#src/usecases/semantic-port"
+import { maintainMemoryFolders } from "./maintenance.ts"
+import { publishMemoryCatalog } from "./publication.ts"
+import { scanMemoryCatalog } from "./scan.ts"
+import type {
+  CatalogSynchronization,
+  SynchronizationProgress,
+  SynchronizeMemoryRequest,
+  SynchronizeMemoryResult,
+} from "./types.ts"
+
+export async function synchronizeLeasedMemory(
+  request: SynchronizeMemoryRequest,
+  context: MemoryOperationContext,
+): Promise<SynchronizeMemoryResult> {
+  const resolved = await resolveLeasedMemory(context)
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return { ...interrupted, progress: null }
+  if (!resolved.succeeded) return { ...resolved, progress: null }
+  const target = selectMemoryVault(resolved.output, request.vault)
+  if (!target.succeeded) return { ...target, progress: null }
+  return synchronizeSelectedMemory(resolved.output, target.output, context)
+}
+
+async function synchronizeSelectedMemory(
+  memory: ResolvedMemory,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+): Promise<SynchronizeMemoryResult> {
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return { ...interrupted, progress: null }
+  const opened = openVaultIndex(memory, target)
+  if (!opened.succeeded) return { ...opened, progress: null }
+  const warnings: string[] = []
+  const semantic = await semanticPortOf(context, memory)
+  let result: SynchronizeMemoryResult
+  try {
+    result = await synchronizeOpenedMemory(opened, memory, target, context, semantic)
+  } finally {
+    const closed = closeIndex(opened.output)
+    if (!closed.succeeded) warnings.push(...closed.problems)
+  }
+  if (result.succeeded) result.output.warnings.push(...warnings)
+  else result.problems.push(...warnings)
+  return result
+}
+
+export function openVaultIndex(memory: ResolvedMemory, target: ResolvedVault): OpenIndexResult {
+  return recoverIndex({ path: indexFileFor(memory.indexPath, target.vault.path, memory.platform) })
+}
+
+export async function synchronizeOpenedMemory(
+  opened: OpenedIndex,
+  memory: ResolvedMemory,
+  target: ResolvedVault,
+  context: MemoryOperationContext,
+  semantic: SemanticPort | null,
+): Promise<SynchronizeMemoryResult> {
+  const inventory = readIndexInventory(opened.output)
+  if (!inventory.succeeded) return { ...inventory, progress: null }
+  const progress: SynchronizationProgress = {
+    vault: target.scope,
+    revision: inventory.output.revision,
+    population: inventory.output.population,
+    rebuilt: opened.rebuilt,
+    committed: false,
+    coverage: "degraded",
+    duplicateIds: [],
+    warnings: [],
+  }
+  const work: CatalogSynchronization = { context, target, index: opened.output, progress }
+  const validationFingerprint = catalogValidationFingerprint(memory.config.limits)
+  const scanned = await scanMemoryCatalog(work, inventory.output, validationFingerprint)
+  const interrupted = memoryOperationInterruption(context)
+  if (interrupted) return { ...interrupted, progress }
+  if (!scanned.succeeded) return { ...scanned, progress }
+  progress.warnings.push(...scanned.output.warnings)
+  const published = publishMemoryCatalog(work, inventory.output, scanned.output.catalog)
+  if (!published.succeeded) return { ...published, progress }
+  await maintainMemoryFolders(work, scanned.output)
+  progress.warnings.push(...(await refreshSemantic(opened.output, memory, semantic, context)))
+  const stale = memoryOperationInterruption(context)
+  if (stale) return { ...stale, progress }
+  return { succeeded: true, output: progress }
+}