amorphous-cli 0.1.13 → 0.3.0

package/lib/agent-guides-files.mjs

@@ -0,0 +1,541 @@
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  chmodSync, closeSync, existsSync, fchmodSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync,
+  realpathSync, renameSync, rmSync, unlinkSync, writeFileSync,
+} from 'node:fs'
+import { homedir, tmpdir } from 'node:os'
+import { spawnSync } from 'node:child_process'
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path'
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const BEGIN = '# BEGIN amorphous agent guides'
+const END = '# END amorphous agent guides'
+const GUIDE_MAX_BYTES = 32 * 1024
+const FILES = ['agent.md', 'private-agent.md']
+
+/*
+ * Filesystem contract for the context command:
+ * - guidePaths(root, abstractId, userId) returns active, identity-bound paths;
+ * - ensureGuideFilesIgnored(root) installs non-destructive ignore rules;
+ * - activateGuideIdentity(root, abstractId, userId) must run only after fresh
+ *   server authorization and archives files from any prior identity;
+ * - readGuideSyncState/writeGuideSyncState store only revisions and body hashes;
+ * - materializeGuide({ projectRoot, abstractId, userId, kind, body, revision })
+ *   writes unchanged-base remote content, leaves local edits intact on conflict,
+ *   and returns { status, path, conflictPath? }. Handle conflict/identity-uncertain
+ *   without loading the active file as newly authorized remote context.
+ * The active paths are agent.md and private-agent.md. Private sync state and all
+ * conflict/recovery/temp artifacts live under ignored .amorphous-guides/.
+ */
+
+function assertId(value, label) {
+  if (typeof value !== 'string' || !UUID.test(value)) throw new Error(`Invalid ${label}.`)
+  return value.toLowerCase()
+}
+
+function projectRootOf(projectRoot) {
+  if (typeof projectRoot !== 'string' || !projectRoot) throw new Error('Project root is required.')
+  const requested = resolve(projectRoot)
+  const info = lstatSync(requested)
+  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('Project root must be a real directory, not a symlink.')
+  const actual = realpathSync(requested)
+  if (actual === parseRoot(actual) || actual === homedir()) throw new Error('Refusing to use a filesystem or home directory as the project root.')
+  return actual
+}
+
+function parseRoot(path) {
+  return parse(path).root
+}
+
+function checkedPath(root, ...parts) {
+  const path = resolve(root, ...parts)
+  const rel = relative(root, path)
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    if (rel === '') return path
+    throw new Error('Guide path escapes the project root.')
+  }
+  return path
+}
+
+function assertNoSymlink(path, { allowMissing = true } = {}) {
+  try {
+    if (lstatSync(path).isSymbolicLink()) throw new Error(`Symlinked guide path is not allowed: ${path}`)
+  } catch (error) {
+    if (error?.code === 'ENOENT' && allowMissing) return
+    throw error
+  }
+}
+
+function assertNoSymlinkChain(path) {
+  const absolute = resolve(path)
+  const root = parseRoot(absolute)
+  let current = root
+  for (const part of relative(root, absolute).split(sep).filter(Boolean)) {
+    current = join(current, part)
+    assertNoSymlink(current)
+  }
+}
+
+function ensureDirectory(root, path, mode = 0o700) {
+  const rel = relative(root, path)
+  let current = root
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = join(current, part)
+    assertNoSymlink(current)
+    try { mkdirSync(current, { mode }) } catch (error) { if (error?.code !== 'EEXIST') throw error }
+    const info = lstatSync(current)
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`Unsafe guide directory: ${current}`)
+    try { chmodSync(current, mode) } catch { /* preserve operation result; target remains private by file mode */ }
+  }
+}
+
+function ensureIgnoreParent(root, path) {
+  const parent = dirname(path)
+  const rel = relative(root, parent)
+  let current = root
+  for (const part of rel.split(sep).filter(Boolean)) {
+    current = join(current, part)
+    assertNoSymlink(current)
+    try { mkdirSync(current) } catch (error) { if (error?.code !== 'EEXIST') throw error }
+    const info = lstatSync(current)
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error(`Unsafe guide ignore directory: ${current}`)
+  }
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function git(root, args, options = {}) {
+  return spawnSync('git', args, { cwd: root, encoding: 'utf8', ...options })
+}
+
+function assertArtifactPathsSafeToWrite(root, absolutePaths) {
+  const paths = absolutePaths.map((path) => {
+    const rel = relative(root, resolve(path)).split(sep).join('/')
+    if (!rel || rel === '..' || rel.startsWith('../')) throw new Error('Guide artifact path escapes project root.')
+    return rel
+  })
+  const repo = git(root, ['rev-parse', '--show-toplevel'])
+  if (repo.error) throw new Error('Cannot verify guide artifact ignore/tracking status; refusing to write guide context.')
+  if (repo.status === 0) {
+    const gitRoot = realpathSync(repo.stdout.trim())
+    for (const path of paths) {
+      const repoPath = relative(gitRoot, resolve(root, path)).split(sep).join('/')
+      const tracked = git(gitRoot, ['ls-files', '--', repoPath])
+      const ignored = git(gitRoot, ['check-ignore', '--quiet', '--', repoPath])
+      if (tracked.status !== 0 || tracked.stdout.trim() || ignored.status !== 0) {
+        throw new Error('Guide artifact path is tracked or not effectively ignored; refusing to write guide context.')
+      }
+    }
+    return
+  }
+  if (repo.status !== 128) throw new Error('Cannot verify guide artifact ignore status; refusing to write guide context.')
+
+  // A disposable repo can model the root .gitignore but not assume that no
+  // deeper .gitignore changes the rules. Fail closed for artifacts beneath
+  // any nested ignore file rather than materializing content under uncertain
+  // effective rules.
+  for (const path of paths) {
+    let directory = dirname(resolve(root, path))
+    while (directory !== root) {
+      const nestedIgnore = join(directory, '.gitignore')
+      assertNoSymlinkChain(nestedIgnore)
+      try {
+        const info = lstatSync(nestedIgnore)
+        if (info.isSymbolicLink() || !info.isFile()) {
+          throw new Error('Nested guide ignore path is unsafe; refusing to write guide context.')
+        }
+        throw new Error('Nested guide ignore rules cannot be proven safe outside Git; refusing to write guide context.')
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error
+      }
+      directory = dirname(directory)
+    }
+  }
+
+  const temp = mkdtempSync(join(tmpdir(), 'am-guide-artifact-check-'))
+  try {
+    const init = git(temp, ['init', '--quiet'])
+    if (init.status !== 0) throw new Error('Cannot verify guide artifact ignore status; refusing to write guide context.')
+    let ignoreText = ''
+    try { ignoreText = readFileSync(join(root, '.gitignore'), 'utf8') } catch (error) { if (error?.code !== 'ENOENT') throw error }
+    writeFileSync(join(temp, '.gitignore'), ignoreText)
+    for (const path of paths) {
+      const ignored = git(temp, ['check-ignore', '--quiet', '--', path])
+      if (ignored.status !== 0) throw new Error('Guide artifact path is not effectively ignored; refusing to write guide context.')
+    }
+  } finally { rmSync(temp, { recursive: true, force: true }) }
+}
+
+function assertGuidePathsSafeToWrite(root) {
+  const repo = git(root, ['rev-parse', '--show-toplevel'])
+  if (repo.error) throw new Error('Cannot verify private guide ignore and tracking status; refusing to write private context.')
+  if (repo.status === 0) {
+    const gitRoot = realpathSync(repo.stdout.trim())
+    const trackedPaths = ['agent.md', 'private-agent.md', '.amorphous-guides']
+      .map((path) => relative(gitRoot, resolve(root, path)).split(sep).join('/'))
+    for (const path of trackedPaths) {
+      const tracked = git(gitRoot, ['ls-files', '--', path])
+      if (tracked.status !== 0 || tracked.stdout.trim()) {
+        throw new Error('Agent guide paths are tracked or tracking status is unknown; refusing to write guide context.')
+      }
+    }
+    const ignoredPaths = ['agent.md', 'private-agent.md', '.amorphous-guides/private-check']
+      .map((path) => relative(gitRoot, resolve(root, path)).split(sep).join('/'))
+    for (const path of ignoredPaths) {
+      const ignored = git(gitRoot, ['check-ignore', '--quiet', '--', path])
+      if (ignored.status !== 0) {
+        throw new Error('Agent guide paths are not effectively ignored; refusing to write guide context.')
+      }
+    }
+    return
+  }
+  if (repo.status !== 128) throw new Error('Cannot verify guide ignore status; refusing to write guide context.')
+
+  // Outside Git, check the workspace's .gitignore in a disposable real repo so
+  // negations and directory semantics are evaluated by Git itself.
+  const temp = mkdtempSync(join(tmpdir(), 'am-guide-ignore-check-'))
+  try {
+    const init = git(temp, ['init', '--quiet'])
+    if (init.status !== 0) throw new Error('Cannot verify guide ignore status; refusing to write guide context.')
+    let ignoreText = ''
+    try { ignoreText = readFileSync(join(root, '.gitignore'), 'utf8') } catch (error) { if (error?.code !== 'ENOENT') throw error }
+    writeFileSync(join(temp, '.gitignore'), ignoreText)
+    for (const path of ['agent.md', 'private-agent.md', '.amorphous-guides/private-check']) {
+      const ignored = git(temp, ['check-ignore', '--quiet', '--', path])
+      if (ignored.status !== 0) throw new Error('Agent guide paths are not effectively ignored; refusing to write guide context.')
+    }
+  } finally { rmSync(temp, { recursive: true, force: true }) }
+}
+
+function atomicWrite(path, data, mode = 0o600, safetyRoot = null) {
+  const parent = dirname(path)
+  assertNoSymlink(parent, { allowMissing: false })
+  assertNoSymlink(path)
+  const temp = join(parent, `.amorphous-guide-${process.pid}-${randomUUID()}.tmp`)
+  if (safetyRoot) assertArtifactPathsSafeToWrite(safetyRoot, [path, temp])
+  let fd
+  try {
+    fd = openSync(temp, 'wx', mode)
+    writeFileSync(fd, data)
+    fchmodSync(fd, mode)
+    closeSync(fd)
+    fd = undefined
+    assertNoSymlink(path)
+    renameSync(temp, path)
+    chmodSync(path, mode)
+  } catch (error) {
+    if (fd !== undefined) closeSync(fd)
+    try { unlinkSync(temp) } catch { /* no temporary file remains */ }
+    throw error
+  }
+}
+
+function readJsonFile(path) {
+  assertNoSymlinkChain(dirname(path))
+  assertNoSymlink(path)
+  try {
+    const info = lstatSync(path)
+    if (!info.isFile()) throw new Error(`Expected a regular guide metadata file: ${path}`)
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+function validRevisionEntry(entry) {
+  return entry && typeof entry === 'object' && !Array.isArray(entry) &&
+    Number.isSafeInteger(entry.revision) && entry.revision >= 0 &&
+    typeof entry.hash === 'string' && /^[a-f0-9]{64}$/.test(entry.hash)
+}
+
+function validateState(value, abstractId, userId) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.schemaVersion !== 1 ||
+    value.abstractId !== abstractId || value.userId !== userId || !value.guides ||
+    typeof value.guides !== 'object' || Array.isArray(value.guides) ||
+    Object.keys(value).some((key) => !['schemaVersion', 'abstractId', 'userId', 'guides'].includes(key))) {
+    throw new Error('Invalid guide sync state identity or format.')
+  }
+  for (const key of Object.keys(value.guides)) {
+    if (!['abstract', 'private'].includes(key) || !validRevisionEntry(value.guides[key]) ||
+      Object.keys(value.guides[key]).some((entryKey) => !['revision', 'hash'].includes(entryKey))) {
+      throw new Error('Invalid guide sync state metadata.')
+    }
+  }
+  return value
+}
+
+/** Return validated local paths for one abstract and authenticated user. */
+export function guidePaths(projectRoot, abstractId, userId) {
+  const root = projectRootOf(projectRoot)
+  const app = assertId(abstractId, 'abstract id')
+  const user = assertId(userId, 'user id')
+  const internal = (...parts) => checkedPath(root, '.amorphous-guides', ...parts)
+  return {
+    projectRoot: root,
+    abstractId: app,
+    userId: user,
+    abstractGuide: checkedPath(root, 'agent.md'),
+    privateGuide: checkedPath(root, 'private-agent.md'),
+    activeIdentity: internal('active.json'),
+    syncState: internal('state', app, user, 'sync.json'),
+    conflictsDirectory: internal('conflicts', app, user),
+    recoveryDirectory: internal('recovery', app, user),
+    tempDirectory: internal('tmp'),
+  }
+}
+
+/** SHA-256 of the exact UTF-8 guide body, for state comparisons only. */
+export function guideBodyHash(body) {
+  if (typeof body !== 'string') throw new Error('Guide body must be text.')
+  return sha256(body)
+}
+
+function gitIgnoreTarget(root) {
+  let current = root
+  for (;;) {
+    const dotGit = join(current, '.git')
+    assertNoSymlink(dotGit)
+    try {
+      const info = lstatSync(dotGit)
+      if (info.isDirectory()) return { path: join(dotGit, 'info', 'exclude'), gitRoot: current }
+      if (info.isFile()) {
+        const text = readFileSync(dotGit, 'utf8').trim()
+        const match = /^gitdir:\s*(.+)$/.exec(text)
+        if (match) {
+          const gitDir = resolve(current, match[1])
+          assertNoSymlinkChain(gitDir)
+          if (!lstatSync(gitDir).isDirectory()) throw new Error('Invalid Git directory for guide ignores.')
+          return { path: join(gitDir, 'info', 'exclude'), gitRoot: current, worktree: true }
+        }
+      }
+    } catch (error) { if (error?.code !== 'ENOENT') throw error }
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+function ignoreBlock(prefix) {
+  const encodedPrefix = prefix ? prefix.split('/').map((part) => part
+    .replace(/([\\*?\[\]])/g, '\\$1')
+    .replace(/ /g, '\\ ')
+    .replace(/^([#!])/, '\\$1')).join('/') : ''
+  const base = encodedPrefix ? `/${encodedPrefix}/` : '/'
+  return `${BEGIN}\n${base}agent.md\n${base}private-agent.md\n${base}.amorphous-guide-*.tmp\n${base}.amorphous-guides/\n${END}`
+}
+
+function managedBlock(text, block) {
+  const begin = text.indexOf(BEGIN)
+  const end = text.indexOf(END)
+  if ((begin < 0) !== (end < 0) || (begin >= 0 && end < begin)) throw new Error('Malformed managed guide ignore block.')
+  if (begin < 0) return `${text}${text && !text.endsWith('\n') ? '\n' : ''}${block}\n`
+  const endAfter = end + END.length
+  if (text.indexOf(BEGIN, begin + BEGIN.length) >= 0 || text.indexOf(END, endAfter) >= 0) {
+    throw new Error('Duplicate managed guide ignore block.')
+  }
+  const existingEntries = text.slice(begin + BEGIN.length, end).split('\n').map((line) => line.trim()).filter(Boolean)
+  const proposedEntries = block.split('\n').slice(1, -1)
+  const entries = [...new Set([...existingEntries, ...proposedEntries])]
+  return `${text.slice(0, begin)}${[BEGIN, ...entries, END].join('\n')}${text.slice(endAfter)}`
+}
+
+/** Add private guide/cache ignores without replacing user-authored ignore rules. */
+export function ensureGuideFilesIgnored(projectRoot) {
+  const root = projectRootOf(projectRoot)
+  const git = gitIgnoreTarget(root)
+  // A real .git directory has repo-root-relative excludes. A worktree pointer
+  // uses a workspace-local .gitignore fallback so its paths remain scoped.
+  const path = git && !git.worktree ? git.path : checkedPath(root, '.gitignore')
+  const ignoreRoot = git && !git.worktree ? git.gitRoot : root
+  const prefix = relative(ignoreRoot, root).split(sep).filter(Boolean).join('/')
+  assertNoSymlinkChain(dirname(path))
+  if (relative(root, dirname(path)).startsWith(`..${sep}`)) {
+    if (!existsSync(dirname(path))) throw new Error('Git ignore directory is unavailable.')
+  } else {
+    ensureIgnoreParent(root, path)
+  }
+  assertNoSymlink(path)
+  let current = ''
+  try {
+    const info = lstatSync(path)
+    if (!info.isFile()) throw new Error('Guide ignore target must be a regular file.')
+    current = readFileSync(path, 'utf8')
+  } catch (error) { if (error?.code !== 'ENOENT') throw error }
+  const next = managedBlock(current, ignoreBlock(prefix))
+  if (next !== current) {
+    let mode = 0o644
+    try { mode = lstatSync(path).mode & 0o777 } catch { /* use normal ignore-file permissions */ }
+  atomicWrite(path, next, mode)
+  }
+  return path
+}
+
+/** Load metadata only when its embedded abstract/user identity matches the requested key. */
+export function readGuideSyncState(projectRoot, abstractId, userId) {
+  const paths = guidePaths(projectRoot, abstractId, userId)
+  let value
+  try { value = readJsonFile(paths.syncState) } catch (error) {
+    if (error instanceof SyntaxError) throw new Error('Invalid guide sync state JSON.')
+    throw error
+  }
+  if (value === null) return null
+  return validateState(value, paths.abstractId, paths.userId)
+}
+
+/** Persist only revision/hash metadata under a path keyed by abstract and authenticated user. */
+export function writeGuideSyncState(projectRoot, abstractId, userId, guides) {
+  const paths = guidePaths(projectRoot, abstractId, userId)
+  ensureGuideFilesIgnored(paths.projectRoot)
+  assertGuidePathsSafeToWrite(paths.projectRoot)
+  if (!guides || typeof guides !== 'object' || Array.isArray(guides)) throw new Error('Guide state is required.')
+  const clean = {}
+  for (const [key, value] of Object.entries(guides)) {
+    if (!['abstract', 'private'].includes(key) || !validRevisionEntry(value)) throw new Error('Invalid guide revision metadata.')
+    clean[key] = { revision: value.revision, hash: value.hash }
+  }
+  const state = { schemaVersion: 1, abstractId: paths.abstractId, userId: paths.userId, guides: clean }
+  validateState(state, paths.abstractId, paths.userId)
+  ensureDirectory(paths.projectRoot, dirname(paths.syncState))
+  const existing = readJsonFile(paths.syncState)
+  if (existing && JSON.stringify(validateState(existing, paths.abstractId, paths.userId)) === JSON.stringify(state)) return paths.syncState
+  atomicWrite(paths.syncState, `${JSON.stringify(state, null, 2)}\n`, 0o600, paths.projectRoot)
+  return paths.syncState
+}
+
+function activeIdentity(paths) {
+  let value
+  try { value = readJsonFile(paths.activeIdentity) } catch (error) {
+    if (error instanceof SyntaxError) return { value: null, malformed: true }
+    throw error
+  }
+  if (value === null) return { value: null, malformed: false }
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.schemaVersion !== 1 ||
+    !UUID.test(value.abstractId || '') || !UUID.test(value.userId || '')) return { value: null, malformed: true }
+  return { value: { abstractId: value.abstractId.toLowerCase(), userId: value.userId.toLowerCase() }, malformed: false }
+}
+
+function validateActiveGuidePaths(paths) {
+  for (const path of [paths.abstractGuide, paths.privateGuide]) {
+    assertNoSymlinkChain(dirname(path))
+    assertNoSymlink(path)
+    try {
+      if (!lstatSync(path).isFile()) throw new Error(`Active guide must be a regular file: ${path}`)
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error
+    }
+  }
+}
+
+function recoverActiveFile(root, activePath, recoveryDir, filename) {
+  assertNoSymlinkChain(dirname(activePath))
+  assertNoSymlink(activePath)
+  let info
+  try { info = lstatSync(activePath) } catch (error) { if (error?.code === 'ENOENT') return null; throw error }
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error(`Unsafe active guide file: ${activePath}`)
+  ensureDirectory(root, recoveryDir)
+  const name = `${Date.now()}-${randomUUID()}-${filename}`
+  const destination = checkedPath(root, relative(root, recoveryDir), name)
+  const temp = join(dirname(destination), `.amorphous-guide-${process.pid}-recovery-preflight.tmp`)
+  assertArtifactPathsSafeToWrite(root, [destination, temp])
+  const bytes = readFileSync(activePath)
+  atomicWrite(destination, bytes, 0o600, root)
+  unlinkSync(activePath)
+  return destination
+}
+
+/**
+ * Bind active local guide files to the authenticated (abstract,user) pair.
+ * Call only after fresh server authorization. On mismatch, old files are moved
+ * to ignored identity-specific recovery paths and never remain active.
+ */
+export function activateGuideIdentity(projectRoot, abstractId, userId) {
+  const paths = guidePaths(projectRoot, abstractId, userId)
+  validateActiveGuidePaths(paths)
+  ensureGuideFilesIgnored(paths.projectRoot)
+  assertGuidePathsSafeToWrite(paths.projectRoot)
+  const active = activeIdentity(paths)
+  const same = active.value?.abstractId === paths.abstractId && active.value?.userId === paths.userId
+  if (same) return { status: 'active', privateSafeToLoad: true, recovered: [] }
+  if (!active.value && !active.malformed && !existsSync(paths.abstractGuide) && !existsSync(paths.privateGuide)) {
+    ensureDirectory(paths.projectRoot, dirname(paths.activeIdentity))
+    atomicWrite(paths.activeIdentity, `${JSON.stringify({ schemaVersion: 1, abstractId: paths.abstractId, userId: paths.userId })}\n`, 0o600, paths.projectRoot)
+    return { status: 'active', privateSafeToLoad: true, recovered: [] }
+  }
+
+  let recoveryDirectory
+  if (active.value) {
+    const prior = guidePaths(paths.projectRoot, active.value.abstractId, active.value.userId)
+    recoveryDirectory = prior.recoveryDirectory
+  } else {
+    let opaque = 'unbound'
+    try { opaque = sha256(readFileSync(paths.activeIdentity)).slice(0, 16) } catch {
+      const bytes = FILES.map((file) => {
+        try { return readFileSync(checkedPath(paths.projectRoot, file)) } catch { return Buffer.alloc(0) }
+      })
+      opaque = sha256(Buffer.concat(bytes)).slice(0, 16)
+    }
+    recoveryDirectory = checkedPath(paths.projectRoot, '.amorphous-guides', 'recovery', paths.abstractId, `unknown-${opaque}`)
+  }
+  const recovered = []
+  for (const filename of FILES) {
+    const found = recoverActiveFile(paths.projectRoot, checkedPath(paths.projectRoot, filename), recoveryDirectory, filename)
+    if (found) recovered.push(found)
+  }
+  ensureDirectory(paths.projectRoot, dirname(paths.activeIdentity))
+  atomicWrite(paths.activeIdentity, `${JSON.stringify({ schemaVersion: 1, abstractId: paths.abstractId, userId: paths.userId })}\n`, 0o600, paths.projectRoot)
+  return {
+    status: active.malformed || !active.value ? 'recovered-unknown-identity' : 'switched',
+    privateSafeToLoad: Boolean(active.value) && !active.malformed,
+    recovered,
+  }
+}
+
+/**
+ * Materialize one already-authorized guide revision. Remote changes never
+ * replace a local edit: the remote body goes to an ignored conflict file.
+ */
+export function materializeGuide({ projectRoot, abstractId, userId, kind, body, revision }) {
+  if (!['abstract', 'private'].includes(kind)) throw new Error('Guide kind must be abstract or private.')
+  if (typeof body !== 'string' || !Number.isSafeInteger(revision) || revision < 0) throw new Error('Invalid guide document.')
+  if (Buffer.byteLength(body, 'utf8') > GUIDE_MAX_BYTES) throw new Error('Guide exceeds the 32 KiB UTF-8 limit.')
+  const paths = guidePaths(projectRoot, abstractId, userId)
+  const identity = activateGuideIdentity(paths.projectRoot, paths.abstractId, paths.userId)
+  if (!identity.privateSafeToLoad) return { status: 'identity-uncertain', recovered: identity.recovered }
+  const path = kind === 'abstract' ? paths.abstractGuide : paths.privateGuide
+  assertNoSymlinkChain(dirname(path))
+  const hash = sha256(body)
+  const state = readGuideSyncState(paths.projectRoot, paths.abstractId, paths.userId)
+  const base = state?.guides?.[kind]
+  assertNoSymlink(path)
+  let local = null
+  try {
+    const info = lstatSync(path)
+    if (!info.isFile()) throw new Error(`Guide target must be a regular file: ${path}`)
+    local = readFileSync(path, 'utf8')
+  } catch (error) { if (error?.code !== 'ENOENT') throw error }
+
+  if (local === body) {
+    const guides = { ...(state?.guides ?? {}), [kind]: { revision, hash } }
+    writeGuideSyncState(paths.projectRoot, paths.abstractId, paths.userId, guides)
+    return { status: 'unchanged', path }
+  }
+  if (local !== null && base && sha256(local) !== base.hash && hash === base.hash) {
+    const guides = { ...(state?.guides ?? {}), [kind]: { revision, hash } }
+    writeGuideSyncState(paths.projectRoot, paths.abstractId, paths.userId, guides)
+    return { status: 'local-only', path, localHash: sha256(local) }
+  }
+  if (local !== null && (!base || sha256(local) !== base.hash)) {
+    ensureDirectory(paths.projectRoot, paths.conflictsDirectory)
+    const conflictPath = checkedPath(paths.projectRoot, relative(paths.projectRoot, paths.conflictsDirectory), `${kind}-remote-r${revision}-${randomUUID()}.md`)
+    atomicWrite(conflictPath, body, 0o600, paths.projectRoot)
+    return { status: 'conflict', path, conflictPath }
+  }
+
+  atomicWrite(path, body, 0o600, paths.projectRoot)
+  const guides = { ...(state?.guides ?? {}), [kind]: { revision, hash } }
+  writeGuideSyncState(paths.projectRoot, paths.abstractId, paths.userId, guides)
+  return { status: 'written', path }
+}