@lincyaw/workspace 1.0.0-rc.0 → 1.0.0-rc.2

package/src/node/document-history.ts

@@ -0,0 +1,190 @@
+import { createHash } from 'node:crypto'
+import { DOCUMENT_ENTRY, DOCUMENT_HISTORY_MAX_FILE_BYTES, DOCUMENT_HISTORY_MAX_REQUEST_CHARS, DOCUMENT_HISTORY_MAX_RESPONSE_CHARS, DOCUMENT_HISTORY_PAGE_SIZE, fnv1a64, hasRole, jsonResponse, problemResponse } from '@lincyaw/kernel'
+import type { DocumentHistory, DocumentHistoryAnswer, DocumentHistoryBinding, DocumentHistoryChange, DocumentHistoryChanged, DocumentHistoryFile, DocumentHistorySource, HistoryRevision, Member, Route } from '@lincyaw/kernel'
+import { validateDocumentHistoryChange, validateDocumentHistoryQuery, validateDocumentHistoryRead } from '@lincyaw/kernel/node'
+import { listDocuments } from './config.ts'
+import type { WorkspaceConfig } from './config.ts'
+import { catchRequestErrors, RequestError } from './errors.ts'
+import { lockedError } from './locks.ts'
+import type { DocumentLocks } from './locks.ts'
+import type { Revisions } from './revisions.ts'
+import type { SourceEditor } from './source-editor.ts'
+import { documentDirOf } from './writer.ts'
+
+const MAX_RECEIPTS = 64
+const entryOf = (document: string) => document ? `${document}/${DOCUMENT_ENTRY}` : DOCUMENT_ENTRY
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+const digest = (bytes: Uint8Array | string) => createHash('sha256').update(bytes).digest('hex')
+const sameBinding = (a: DocumentHistoryBinding, b: DocumentHistoryBinding) => a.snapshot === b.snapshot && a.source.version === b.source.version && a.source.fingerprint === b.source.fingerprint
+const size = (value: unknown) => JSON.stringify(value, null, 2).length
+const requestSize = (value: unknown) => { if (JSON.stringify(value).length > DOCUMENT_HISTORY_MAX_REQUEST_CHARS) throw new RequestError(413, 'history-request-too-large') }
+
+export interface DocumentHistoryOptions {
+  config: WorkspaceConfig
+  editor: SourceEditor
+  locks: DocumentLocks
+  revisions?: Revisions
+  reviewRequired?: boolean
+  changed(before: string[], after: string[]): Promise<void> | void
+  reverted?(target: string, revision: string): Promise<void> | void
+}
+
+/** The one scoped history application boundary, borrowing the existing git transaction owner. */
+export function createDocumentHistory(options: DocumentHistoryOptions): { service: DocumentHistory, routes: Record<string, Route>, close(): Promise<void> } {
+  const { config, editor, locks, revisions } = options
+  let closed = false
+  const open = () => { if (closed) throw new RequestError(503, 'history-owner-closed') }
+  const receipts = new Map<string, { signature: string, answer: DocumentHistoryChanged }>()
+  const pending = new Map<string, { signature: string, work: Promise<DocumentHistoryChanged> }>()
+  const scope = (document: string, member: Member) => {
+    if (!hasRole(member, 'editor')) throw new RequestError(403, 'history-permission-denied')
+    if (!listDocuments(config).some(item => item.dir === document)) throw new RequestError(404, 'history-document-not-found')
+    return { document, home: false }
+  }
+  const source = (document: string, member: Member): DocumentHistorySource => {
+    const raw = editor.read(scope(document, member), entryOf(document), member)
+    return { version: raw.version, fingerprint: fnv1a64(raw.content) }
+  }
+  const binding = async (document: string, member: Member): Promise<DocumentHistoryBinding> => { const snapshot = await history().head(); if (!snapshot) throw new RequestError(409, 'history-empty-repository'); return { source: source(document, member), snapshot } }
+  const history = () => { if (!revisions) throw new RequestError(409, 'history-git-unavailable'); return revisions }
+  const pathAllowed = (document: string, path: string, member: Member) => {
+    const owned = scope(document, member)
+    editor.assertEditable(owned, path, member)
+    if ((/[\x00-\x1f\x7f]/.test(path) || path.split('/').some(part => part.startsWith('.'))) || documentDirOf(config, path) !== document) throw new RequestError(403, 'history-file-outside-document')
+  }
+  const compact = (document: string, entry: HistoryRevision, member: Member): HistoryRevision => {
+    const files = entry.files.filter(path => { try { pathAllowed(document, path, member); return path.length <= 500 } catch { return false } })
+    const message = (entry.message.split('\n')[0] ?? '').slice(0, 240)
+    return { id: entry.id, message, author: entry.author.slice(0, 120), date: entry.date, origin: { kind: entry.origin.kind }, files: files.slice(0, 6),
+      ...entry.revertedBy ? { revertedBy: entry.revertedBy } : {}, ...entry.reverts ? { reverts: entry.reverts } : {}, ...entry.redo ? { redo: true } : {},
+      ...entry.operation ? { operation: entry.operation } : {}, ...entry.revertible === false ? { revertible: false } : {}, ...entry.undone !== undefined ? { undone: entry.undone, revertTarget: entry.revertTarget } : {} }
+  }
+  const intent = (document: string, which: 'undo' | 'redo' | 'revert', request: DocumentHistoryChange, member: Member, origin: 'editor' | 'agent') => {
+    open()
+    requestSize(request)
+    if (!validateDocumentHistoryChange(request)) throw new RequestError(400, 'history-change-invalid')
+    scope(document, member)
+    if (origin === 'agent' && options.reviewRequired) throw new RequestError(409, 'authoring-review-required')
+    return { key: JSON.stringify([document, member.id, request.id]), signature: digest(JSON.stringify([which, request.id, request.snapshot, request.source.version, request.source.fingerprint, request.expect])) }
+  }
+  const targetPaths = async (document: string, request: DocumentHistoryChange, member: Member) => {
+    const paths = await history().filesOf(request.expect)
+    if (!paths.length) throw new RequestError(404, 'history-revision-not-found')
+    for (const path of paths) {
+      pathAllowed(document, path, member)
+      const owners = await Promise.all([history().ownerAt(request.expect, path), history().ownerAt(`${request.expect}^1`, path)])
+      if (!owners.includes(document) || owners.some(owner => owner !== undefined && owner !== document)) throw new RequestError(403, 'history-file-outside-document')
+    }
+    return paths
+  }
+  const guard = (document: string, request: DocumentHistoryChange, member: Member) => async (changed: string[]) => {
+    for (const path of changed) pathAllowed(document, path, member)
+    if (!sameBinding(await binding(document, member), { source: request.source, snapshot: request.snapshot })) throw new RequestError(409, 'history-source-changed')
+  }
+  const service: DocumentHistory = {
+    async list(document, query, member) {
+      open()
+      requestSize(query)
+      if (!validateDocumentHistoryQuery(query)) throw new RequestError(400, 'history-query-invalid')
+      scope(document, member)
+      if (!revisions) return { document, available: false, revisions: [] }
+      if (!await revisions.head()) { if (query.snapshot !== undefined || (query.offset ?? 0) > 0) throw new RequestError(409, 'history-snapshot-changed'); return { document, available: true, unborn: true, revisions: [] } }
+      const before = await binding(document, member)
+      if ((query.offset ?? 0) > 0 && !query.snapshot) throw new RequestError(400, 'history-snapshot-required')
+      if (query.snapshot !== undefined && query.snapshot !== before.snapshot) throw new RequestError(409, 'history-snapshot-changed')
+      const full = await revisions.historyWithUndo({ document }), changes = full.revisions.filter(entry => !entry.reverts), offset = query.offset ?? 0
+      if (offset > changes.length) throw new RequestError(400, 'history-offset-invalid')
+      const answer: DocumentHistoryAnswer = { document, available: true, historyBinding: before, revisions: [], ...full.undo ? { undo: full.undo } : {}, ...full.redo ? { redo: full.redo } : {} }
+      let index = offset
+      for (const entry of changes.slice(offset, offset + DOCUMENT_HISTORY_PAGE_SIZE)) {
+        const row = compact(document, entry, member)
+        const candidate = { ...answer, revisions: [...answer.revisions, row], nextOffset: index + 1, truncated: true }
+        if (size(candidate) > DOCUMENT_HISTORY_MAX_RESPONSE_CHARS) break
+        answer.revisions.push(row); index++
+        if (!same(row, entry)) answer.truncated = true
+      }
+      if (index < changes.length) { if (index === offset) throw new RequestError(413, 'history-entry-too-large'); answer.nextOffset = index }
+      if (!sameBinding(before, await binding(document, member))) throw new RequestError(409, 'history-snapshot-changed')
+      return answer
+    },
+    async read(document, query, member) {
+      open()
+      requestSize(query)
+      if (!validateDocumentHistoryRead(query)) throw new RequestError(400, 'history-read-invalid')
+      const path = query.path ?? entryOf(document)
+      pathAllowed(document, path, member)
+      const bytes = await history().readFile(query.revision, path, DOCUMENT_HISTORY_MAX_FILE_BYTES, document)
+      let content: string
+      try { content = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes) } catch { throw new RequestError(422, 'history-file-not-utf8') }
+      if (content.includes('\0')) throw new RequestError(422, 'history-file-not-utf8-text')
+      const offset = query.offset ?? 0
+      if (offset > content.length || offset > 0 && /[\uD800-\uDBFF]/.test(content[offset - 1]!) && /[\uDC00-\uDFFF]/.test(content[offset] ?? '')) throw new RequestError(400, 'history-offset-invalid')
+      const reply = (end: number): DocumentHistoryFile => ({ document, revision: query.revision, path, encoding: 'utf8-text-fragment', text: content.slice(offset, end), offset, ...end < content.length ? { nextOffset: end } : {}, totalChars: content.length, complete: end === content.length, sha256: digest(bytes), verification: 'historical-file-only' })
+      let low = offset, high = Math.min(content.length, offset + DOCUMENT_HISTORY_MAX_RESPONSE_CHARS)
+      while (low < high) { const middle = Math.ceil((low + high) / 2); if (size(reply(middle)) <= DOCUMENT_HISTORY_MAX_RESPONSE_CHARS) low = middle; else high = middle - 1 }
+      if (low < content.length && low > offset && /[\uD800-\uDBFF]/.test(content[low - 1]!) && /[\uDC00-\uDFFF]/.test(content[low]!)) low--
+      if (low === offset && offset < content.length) throw new RequestError(413, 'history-file-reply-too-large')
+      return reply(low)
+    },
+    async checkChange(document, which, request, member, origin = 'editor') {
+      const { key, signature } = intent(document, which, request, member, origin)
+      const known = receipts.get(key), flight = pending.get(key)
+      if (known || flight) {
+        if ((known ?? flight)!.signature !== signature) throw new RequestError(409, 'history-intent-reused')
+        if (known && !flight && !sameBinding(await binding(document, member), { source: known.answer.source, snapshot: known.answer.snapshot })) throw new RequestError(409, 'history-result-no-longer-current')
+        return
+      }
+      const paths = await targetPaths(document, request, member)
+      if (!sameBinding(await binding(document, member), { source: request.source, snapshot: request.snapshot })) throw new RequestError(409, 'history-source-changed')
+      const claimed = locks.claimAll(paths.map(path => documentDirOf(config, path)!), 'revision:revert')
+      if ('holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+      try {
+        const result = await history().checkRevert(request.expect, member, which === 'revert' ? undefined : { which, document }, guard(document, request, member))
+        if (!result.ok) throw new RequestError(409, 'history-conflict', { conflicts: result.conflicts.slice(0, 6).map(path => path.slice(0, 500)), conflictCount: result.conflicts.length })
+      } finally { claimed.release() }
+    },
+    async change(document, which, request, member, origin = 'editor') {
+      const { key, signature } = intent(document, which, request, member, origin)
+      const known = receipts.get(key), flight = pending.get(key)
+      if (known || flight) {
+        if ((known ?? flight)!.signature !== signature) throw new RequestError(409, 'history-intent-reused')
+        if (flight) return flight.work
+        if (!sameBinding(await binding(document, member), { source: known!.answer.source, snapshot: known!.answer.snapshot })) throw new RequestError(409, 'history-result-no-longer-current')
+        return structuredClone(known!.answer)
+      }
+      if (pending.size >= MAX_RECEIPTS) throw new RequestError(429, 'history-busy')
+      const work = Promise.resolve().then(async () => {
+        const paths = await targetPaths(document, request, member)
+        const claimed = locks.claimAll(paths.map(path => documentDirOf(config, path)!), 'revision:revert')
+        if ('holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+        try {
+          const beforeDocuments = listDocuments(config).map(item => item.dir)
+          const result = await history().revert(request.expect, member, which === 'revert' ? undefined : { which, document }, guard(document, request, member), origin)
+          if (!result.ok) throw new RequestError(409, 'history-conflict', { conflicts: result.conflicts.slice(0, 6).map(path => path.slice(0, 500)), conflictCount: result.conflicts.length })
+          const answer: DocumentHistoryChanged = { document, ok: true, revision: { id: result.revision.id, origin: { kind: result.revision.origin.kind } }, ...await binding(document, member), verification: { saved: true, compiled: 'not-requested', runtime: 'not-requested' } }
+          receipts.set(key, { signature, answer }); while (receipts.size > MAX_RECEIPTS) receipts.delete(receipts.keys().next().value!)
+          await options.changed(beforeDocuments, listDocuments(config).map(item => item.dir))
+          void Promise.resolve(options.reverted?.(request.expect, result.revision.id)).catch(() => undefined)
+          return structuredClone(answer)
+        } finally { claimed.release() }
+      })
+      pending.set(key, { signature, work })
+      try { return await work } finally { if (pending.get(key)?.work === work) pending.delete(key) }
+    },
+  }
+  const readRoute = (read: 'list' | 'read'): Route => ({ role: 'editor', handle: (request, ctx) => catchRequestErrors(async () => {
+    if (request.method !== 'GET') return problemResponse(405, 'GET')
+    let query: unknown
+    try { query = JSON.parse(new URL(request.url).searchParams.get('query') ?? '{}') } catch { throw new RequestError(400, 'history-query-invalid') }
+    if (read === 'list') { if (!validateDocumentHistoryQuery(query)) throw new RequestError(400, 'history-query-invalid'); return jsonResponse(await service.list(ctx.document, query, ctx.member)) }
+    if (!validateDocumentHistoryRead(query)) throw new RequestError(400, 'history-read-invalid')
+    return jsonResponse(await service.read(ctx.document, query, ctx.member))
+  }) })
+  const changeRoute = (which: 'undo' | 'redo' | 'revert'): Route => ({ role: 'editor', maxBody: 8192, handle: (request, ctx) => catchRequestErrors(async () => {
+    if (request.method !== 'POST') return problemResponse(405, 'POST')
+    const body: unknown = await request.json().catch(() => undefined)
+    if (!validateDocumentHistoryChange(body)) throw new RequestError(400, 'history-change-invalid')
+    return jsonResponse(await service.change(ctx.document, which, body, ctx.member))
+  }) })
+  return { service, async close() { closed = true; await Promise.allSettled([...pending.values()].map(item => item.work)); receipts.clear() }, routes: { 'revisions': readRoute('list'), 'history/list': readRoute('list'), 'history/file': readRoute('read'), 'history/undo': changeRoute('undo'), 'history/redo': changeRoute('redo'), 'revisions/revert': changeRoute('revert') } }
+}

package/src/node/document-images.ts

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { lstat, open, stat } from 'node:fs/promises'
+import { basename, extname, join, relative } from 'node:path'
+import { imageSize } from 'image-size'
+import { ASSET_TITLE_MAX_LENGTH, DOCUMENT_IMAGE_MAX_BYTES, fnv1a64, hasRole, isRecord, jsonResponse } from '@lincyaw/kernel'
+import type { Asset, CanonicalSource, DocumentImageAuthoring, DocumentImageImport, DocumentImageImportAnswer, DocumentWorkspaceImageImport, Member, RequestContext, Route, TeachingDocument, VerifiedDocumentImageImport } from '@lincyaw/kernel'
+import { productionAssetFile, validateDocumentWorkspaceImageImport, validateDocumentWorkspaceImageInspect } from '@lincyaw/kernel/node'
+import { readAuthoringDocument } from './document-editor.ts'
+import { catchRequestErrors, RequestError } from './errors.ts'
+import type { Revisions } from './revisions.ts'
+import type { SourceEditor, SourceTransactionHistory } from './source-editor.ts'
+
+interface Options { root: string, editor: SourceEditor, revisions?: Revisions, reviewRequired?: boolean }
+interface ImageFormat { extension: string, mediaType: string }
+interface Receipt { signature: string, assetId: string, version: string, files?: DocumentImageImportAnswer['files'], commit?: DocumentImageImportAnswer['commit'] }
+const FORMATS: Record<string, ImageFormat> = {
+  png: { extension: 'png', mediaType: 'image/png' }, jpg: { extension: 'jpg', mediaType: 'image/jpeg' },
+  gif: { extension: 'gif', mediaType: 'image/gif' }, webp: { extension: 'webp', mediaType: 'image/webp' },
+  svg: { extension: 'svg', mediaType: 'image/svg+xml' }, bmp: { extension: 'bmp', mediaType: 'image/bmp' },
+}
+const MAX_DIMENSION = 16384, MAX_PIXELS = 40_000_000
+const header = (value: unknown): value is DocumentImageImport => isRecord(value) && typeof value.id === 'string' && value.id.length > 0 && value.id.length <= 200 && typeof value.baseDocumentVersion === 'string' && /^[\da-f]{20}$/.test(value.baseDocumentVersion) && Object.keys(value).every(key => key === 'id' || key === 'baseDocumentVersion')
+
+/** Only an allowed header and bounded dimensions are inspected; this does not fully decode an image. */
+function inspect(bytes: Uint8Array) {
+  let found: ReturnType<typeof imageSize>
+  try { found = imageSize(bytes) } catch { throw new RequestError(422, 'document-image-format') }
+  const format = found.type && Object.hasOwn(FORMATS, found.type) ? FORMATS[found.type] : undefined
+  if (!format) throw new RequestError(422, 'document-image-format')
+  const { width, height } = found
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0 || width > MAX_DIMENSION || height > MAX_DIMENSION || width * height > MAX_PIXELS) throw new RequestError(422, 'document-image-dimensions')
+  return { ...format, dimensions: { width, height } }
+}
+
+/** Original bytes and the canonical asset bank are committed or rolled back together. */
+export function createDocumentImageAuthoring({ root, editor, revisions, reviewRequired = false }: Options): { service: DocumentImageAuthoring, routes: Record<string, Route> } {
+  const receipts = new Map<string, Receipt>(), pending = new Map<string, { signature: string, done: Promise<DocumentImageImportAnswer> }>()
+  const binding = (current: ReturnType<typeof readAuthoringDocument>): CanonicalSource => ({ documentId: current.content.id, version: current.source.version, fingerprint: fnv1a64(current.source.content) })
+  const opened = (ctx: RequestContext, version?: string, source?: CanonicalSource) => {
+    const current = readAuthoringDocument(editor, ctx)
+    if (version !== undefined && current.source.version !== version || source && (current.content.id !== source.documentId || fnv1a64(current.source.content) !== source.fingerprint)) throw new RequestError(409, 'document-version-changed', { version: current.source.version })
+    return current
+  }
+  const matches = async (ctx: RequestContext, asset: Asset, bytes: Uint8Array, format: ImageFormat, signal: AbortSignal): Promise<boolean> => {
+    if (asset.kind !== 'image' || asset.mediaType !== undefined && asset.mediaType !== format.mediaType) return false
+    const file = productionAssetFile(join(root, ctx.document), asset.location)
+    if (!file || ![`.${format.extension}`, ...(format.extension === 'jpg' ? ['.jpeg'] : [])].includes(extname(file).toLowerCase())) return false
+    const path = relative(root, file).split('\\').join('/')
+    let handle: Awaited<ReturnType<typeof open>> | undefined
+    try {
+      editor.readableFile({ document: ctx.document, home: false }, path, ctx.member)
+      signal.throwIfAborted()
+      handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW)
+      const before = await handle.stat()
+      if (!before.isFile() || before.size !== bytes.byteLength) return false
+      const actual = Buffer.alloc(bytes.byteLength)
+      let offset = 0
+      while (offset < actual.length) {
+        signal.throwIfAborted()
+        const next = await handle.read(actual, offset, actual.length - offset, offset)
+        if (!next.bytesRead) return false
+        offset += next.bytesRead
+      }
+      const after = await handle.stat(), pathNow = await stat(editor.readableFile({ document: ctx.document, home: false }, path, ctx.member))
+      return before.size === after.size && before.mtimeMs === after.mtimeMs && before.ino === pathNow.ino && before.dev === pathNow.dev && actual.equals(bytes)
+    } catch (error) {
+      signal.throwIfAborted()
+      if (error instanceof RequestError || error && typeof error === 'object' && 'code' in error && ['ENOENT', 'ELOOP', 'EACCES'].includes(String(error.code))) return false
+      throw error
+    } finally { await handle?.close() }
+  }
+  const answer = (ctx: RequestContext, change: DocumentImageImport, current: ReturnType<typeof readAuthoringDocument>, assetId: string, dimensions: { width: number, height: number }): DocumentImageImportAnswer => ({
+    changeId: change.id, document: ctx.document, version: current.source.version, fingerprint: fnv1a64(current.source.content), content: current.content, issues: current.issues, files: [], assetId, dimensions,
+  })
+  const remember = (key: string, receipt: Receipt) => {
+    receipts.set(key, receipt)
+    while (receipts.size > 64) receipts.delete(receipts.keys().next().value!)
+  }
+  const history = (ctx: RequestContext, document: TeachingDocument, signal: AbortSignal, origin: 'editor' | 'agent'): SourceTransactionHistory => ({
+    run: work => {
+      const guarded = () => { signal.throwIfAborted(); return work() }
+      return revisions ? revisions.transaction(guarded) : guarded()
+    },
+    commit: async paths => {
+      if (!revisions) return undefined
+      const ignored = (await Promise.all(paths.map(async path => await revisions.ignores(path) ? path : undefined))).filter((path): path is string => Boolean(path))
+      if (ignored.length) throw new RequestError(409, 'document-files-ignored', { ignored })
+      return revisions.commitWhileLocked({ paths, summary: document.metadata.lang.startsWith('en') ? 'Import image' : '导入图片', body: '', origin: { kind: origin, member: ctx.member } })
+    },
+  })
+  const signatureOf = (change: DocumentImageImport, title: string, hash: string, origin: 'editor' | 'agent', source?: CanonicalSource, inputPath?: string) => createHash('sha256').update(JSON.stringify([change.id, change.baseDocumentVersion, source?.documentId ?? null, source?.fingerprint ?? null, origin, inputPath ?? null, title, hash])).digest('hex')
+  const keyOf = (ctx: RequestContext, change: DocumentImageImport) => JSON.stringify([ctx.document, ctx.member.id, change.id])
+  const apply = async (ctx: RequestContext, change: DocumentImageImport, title: string, bytes: Uint8Array, image: ReturnType<typeof inspect>, hash: string, signal: AbortSignal, origin: 'editor' | 'agent', source?: CanonicalSource, inputPath?: string): Promise<DocumentImageImportAnswer> => {
+    const signature = signatureOf(change, title, hash, origin, source, inputPath), key = keyOf(ctx, change)
+    const replay = async () => {
+      const previous = receipts.get(key)
+      if (!previous) return undefined
+      if (previous.signature !== signature) throw new RequestError(409, 'document-change-id-reused')
+      const current = opened(ctx, previous.version), asset = current.content.assets[previous.assetId]
+      if (!asset || !await matches(ctx, asset, bytes, image, signal)) throw new RequestError(409, 'document-image-asset-changed')
+      return { ...answer(ctx, change, opened(ctx, previous.version), previous.assetId, image.dimensions), ...origin === 'agent' && previous.files ? { files: previous.files } : {}, ...origin === 'agent' && previous.commit ? { commit: previous.commit } : {} }
+    }
+    const previous = await replay()
+    if (previous) return previous
+    const active = pending.get(key)
+    if (active) {
+      if (active.signature !== signature) throw new RequestError(409, 'document-change-id-reused')
+      await active.done
+      const repeated = await replay()
+      if (!repeated) throw new RequestError(409, 'document-image-receipt-expired')
+      return repeated
+    }
+    const work = async (): Promise<DocumentImageImportAnswer> => {
+      const current = opened(ctx, change.baseDocumentVersion, source)
+      const candidates = Object.values(current.content.assets).filter(asset => asset.kind === 'image' && (asset.fingerprint === undefined || asset.fingerprint === `sha256:${hash}`)).sort((a, b) => Number(b.fingerprint !== undefined) - Number(a.fingerprint !== undefined))
+      for (const asset of candidates) if (await matches(ctx, asset, bytes, image, signal)) {
+        const fresh = opened(ctx, change.baseDocumentVersion, source)
+        remember(key, { signature, assetId: asset.id, version: fresh.source.version })
+        return answer(ctx, change, fresh, asset.id, image.dimensions)
+      }
+      const assetId = `image_${randomUUID().replaceAll('-', '')}`, location = `assets/images/${assetId}.${image.extension}`, path = ctx.document ? `${ctx.document}/${location}` : location
+      const candidate = structuredClone(current.content)
+      candidate.assets[assetId] = { id: assetId, kind: 'image', location, ...title ? { title } : {}, fingerprint: `sha256:${hash}`, mediaType: image.mediaType }
+      const content = `${JSON.stringify(candidate, null, 2)}\n`
+      signal.throwIfAborted()
+      const saved = await editor.transactionWithBinary({ document: ctx.document, home: false }, { path: current.source.path, content, base: current.source.version }, { path, content: bytes }, ctx.member, history(ctx, candidate, signal, origin))
+      const version = saved.versions.find(file => file.path === current.source.path)!.version
+      remember(key, { signature, assetId, version, files: saved.versions, ...saved.revision ? { commit: saved.revision } : {} })
+      return { changeId: change.id, document: ctx.document, version, fingerprint: fnv1a64(content), content: candidate, issues: current.issues, files: saved.versions, assetId, dimensions: image.dimensions, ...saved.revision ? { commit: saved.revision } : {} }
+    }
+    const done = Promise.resolve().then(work)
+    pending.set(key, { signature, done })
+    try { return await done }
+    finally { if (pending.get(key)?.done === done) pending.delete(key) }
+  }
+  const ctxOf = (document: string, member: Member): RequestContext => ({ document, member, rest: '' })
+  const authorize = (member: Member) => { if (!hasRole(member, 'editor')) throw new RequestError(403, 'image-authoring-permission-denied') }
+  const workspacePath = (ctx: RequestContext, path: string) => {
+    editor.assertEditable({ document: ctx.document, home: false }, path, ctx.member)
+    if (path.split('/').some(part => part.startsWith('.'))) throw new RequestError(403, 'image-file-path')
+  }
+  const reader = async (ctx: RequestContext, path: string, signal?: AbortSignal) => {
+    workspacePath(ctx, path); signal?.throwIfAborted()
+    const file = editor.readableFile({ document: ctx.document, home: false }, path, ctx.member)
+    const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(error => {
+      if (error.code === 'ELOOP') throw new RequestError(403, 'image-file-path')
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') throw new RequestError(404, 'image-file-missing')
+      throw error
+    })
+    try {
+      const before = await handle.stat(), named = await lstat(editor.readableFile({ document: ctx.document, home: false }, path, ctx.member))
+      if (!before.isFile() || before.dev !== named.dev || before.ino !== named.ino) throw new RequestError(403, 'image-file-path')
+      if (!before.size || before.size > DOCUMENT_IMAGE_MAX_BYTES) throw new RequestError(413, 'document-image-size')
+      const bytes = new Uint8Array(before.size + 1); let length = 0
+      while (length < bytes.length) { signal?.throwIfAborted(); const read = await handle.read(bytes, length, bytes.length - length, length); if (!read.bytesRead) break; length += read.bytesRead }
+      const after = await handle.stat(), current = await lstat(editor.readableFile({ document: ctx.document, home: false }, path, ctx.member))
+      const stamp = (value: typeof before) => [value.dev, value.ino, value.size, value.mtimeMs, value.ctimeMs].join(':')
+      if (length !== before.size || stamp(before) !== stamp(after) || after.dev !== current.dev || after.ino !== current.ino) throw new RequestError(409, 'image-file-changed')
+      signal?.throwIfAborted(); return bytes.slice(0, length)
+    } finally { await handle.close() }
+  }
+  const workspaceImport = async (ctx: RequestContext, request: DocumentWorkspaceImageImport, signal?: AbortSignal) => {
+    const bytes = await reader(ctx, request.file.path, signal), sha256 = createHash('sha256').update(bytes).digest('hex')
+    if (bytes.length !== request.file.byteLength || sha256 !== request.file.sha256) throw new RequestError(409, 'image-file-changed')
+    const image = inspect(bytes), title = [...basename(request.file.path).replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim()].slice(0, ASSET_TITLE_MAX_LENGTH).join('')
+    return { bytes, image, sha256, title }
+  }
+  let active = 0
+  const limited = async <T>(work: () => Promise<T>): Promise<T> => {
+    if (active >= 4) throw new RequestError(503, 'image-authoring-busy')
+    active++
+    try { return await work() } finally { active-- }
+  }
+  const service: DocumentImageAuthoring = {
+    async capabilities(document, member) {
+      authorize(member)
+      const source = binding(opened(ctxOf(document, member)))
+      return { source, available: true, verification: 'configuration-only', actions: { inspectWorkspace: true, importWorkspace: !reviewRequired }, ...reviewRequired ? { importUnavailableReason: 'review-required' as const } : {}, limits: { imageBytes: DOCUMENT_IMAGE_MAX_BYTES, receipts: 64, concurrent: 4 }, workspaceFileScope: 'same-document', idempotency: 'process-current-source', review: reviewRequired ? 'required-unsupported' : revisions ? 'locks-and-history' : 'locks-only' }
+    },
+    async inspectWorkspace(document, request, member, signal) {
+      authorize(member)
+      if (!validateDocumentWorkspaceImageInspect(request)) throw new RequestError(400, 'document-image-query-invalid')
+      return limited(async () => {
+      const ctx = ctxOf(document, member); opened(ctx, request.source.version, request.source)
+      const bytes = await reader(ctx, request.path, signal), image = inspect(bytes), sha256 = createHash('sha256').update(bytes).digest('hex')
+      signal?.throwIfAborted(); opened(ctx, request.source.version, request.source)
+      return { document, source: request.source, file: { path: request.path, sha256, byteLength: bytes.length }, image: { mediaType: image.mediaType, dimensions: image.dimensions } }
+      })
+    },
+    async checkWorkspaceImport(document, request, member, signal) {
+      authorize(member)
+      if (reviewRequired) throw new RequestError(409, 'authoring-review-required')
+      if (!validateDocumentWorkspaceImageImport(request)) throw new RequestError(400, 'document-image-import-invalid')
+      return limited(async () => {
+      const ctx = ctxOf(document, member), change = { id: request.id, baseDocumentVersion: request.source.version }, key = keyOf(ctx, change)
+      if (!receipts.has(key) && !pending.has(key)) opened(ctx, request.source.version, request.source)
+      const { sha256, title } = await workspaceImport(ctx, request, signal), signature = signatureOf(change, title, sha256, 'agent', request.source, request.file.path)
+      const receipt = receipts.get(key), known = receipt ?? pending.get(key)
+      if (known && known.signature !== signature) throw new RequestError(409, 'document-change-id-reused')
+      // A receipt of this exact import replays while the source is still the one it saved; an import in flight decides itself.
+      if (receipt) opened(ctx, receipt.version)
+      else if (!known) opened(ctx, request.source.version, request.source)
+      })
+    },
+    async importWorkspace(document, request, member, signal) {
+      authorize(member)
+      if (reviewRequired) throw new RequestError(409, 'authoring-review-required')
+      if (!validateDocumentWorkspaceImageImport(request)) throw new RequestError(400, 'document-image-import-invalid')
+      return limited(async () => {
+      const ctx = ctxOf(document, member), { bytes, image, sha256, title } = await workspaceImport(ctx, request, signal)
+      const result = await apply(ctx, { id: request.id, baseDocumentVersion: request.source.version }, title, bytes, image, sha256, signal ?? new AbortController().signal, 'agent', request.source, request.file.path)
+      try {
+        const current = opened(ctx, result.version), asset = current.content.assets[result.assetId], file = asset && productionAssetFile(join(root, document), asset.location)
+        if (!asset || !file || !await matches(ctx, asset, bytes, image, new AbortController().signal)) throw new Error('asset-changed')
+        const verified = opened(ctx, result.version)
+        return { ...result, content: verified.content, fingerprint: fnv1a64(verified.source.content), verification: { saved: true, source: binding(verified), asset: { assetId: result.assetId, path: relative(root, file).split('\\').join('/'), sha256, byteLength: bytes.length }, compiled: 'not-requested', runtime: 'not-requested' } } satisfies VerifiedDocumentImageImport
+      } catch (error) {
+        throw new RequestError(409, 'image-readback-changed', { committed: result.files.length > 0, changeId: request.id, version: result.version, assetId: result.assetId, reason: error instanceof Error ? error.message : 'readback-failed' })
+      }
+      })
+    },
+  }
+  const routes: Record<string, Route> = {
+    'document/image': { role: 'editor', maxBody: DOCUMENT_IMAGE_MAX_BYTES + (64 << 10), handle: (request, ctx) => catchRequestErrors(async () => {
+      if (request.method !== 'POST') throw new RequestError(405, 'POST')
+      const form = await request.formData().catch(() => undefined)
+      if (!form || [...form.keys()].some(key => key !== 'change' && key !== 'file') || form.getAll('change').length !== 1 || form.getAll('file').length !== 1) throw new RequestError(400, 'document-image-form-invalid')
+      const text = form.get('change'), file = form.get('file')
+      if (typeof text !== 'string' || text.length > 4096 || !(file instanceof File)) throw new RequestError(400, 'document-image-form-invalid')
+      let change: unknown
+      try { change = JSON.parse(text) } catch { throw new RequestError(400, 'document-image-change-invalid') }
+      if (!header(change)) throw new RequestError(400, 'document-image-change-invalid')
+      if (!file.size || file.size > DOCUMENT_IMAGE_MAX_BYTES) throw new RequestError(413, 'document-image-size')
+      const bytes = new Uint8Array(await file.arrayBuffer()), image = inspect(bytes), hash = createHash('sha256').update(bytes).digest('hex')
+      const title = [...(file.name.replaceAll('\\', '/').split('/').at(-1) ?? '').replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim()].slice(0, ASSET_TITLE_MAX_LENGTH).join('')
+      return jsonResponse(await apply(ctx, change, title, bytes, image, hash, request.signal, 'editor'))
+    }) },
+  }
+  return { service, routes }
+}

package/src/node/document-operations.ts

@@ -0,0 +1,191 @@
+import { existsSync, mkdirSync, renameSync, rmdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { DocumentOperation, DocumentFileChange, Member, OperationAnswer, RevisionOperation } from '@lincyaw/kernel'
+import { hasRole } from '@lincyaw/kernel'
+import type { CommitOrigin } from '../domain/commit-message.ts'
+import { invalidDocumentDir, isWithin } from '../domain/paths.ts'
+import { isDocumentDir, listDocuments } from './config.ts'
+import type { WorkspaceConfig } from './config.ts'
+import { RequestError } from './errors.ts'
+import type { Git } from './git.ts'
+import { lockedError } from './locks.ts'
+import type { DocumentLocks } from './locks.ts'
+import type { Revisions } from './revisions.ts'
+import { DEFAULT_TEMPLATE, listTemplates } from './templates.ts'
+import { DocumentCheckpointRefusal, makeDocumentDir } from './writer.ts'
+import type { DocumentWriter } from './writer.ts'
+
+export interface DocumentsChange {
+  removed: string[]
+  added: string[]
+}
+
+export function documentsDiff(before: string[], after: string[]): DocumentsChange {
+  return { removed: before.filter(dir => !after.includes(dir)), added: after.filter(dir => !before.includes(dir)) }
+}
+
+export interface DocumentOperationsOptions {
+  config: WorkspaceConfig
+  git: Git
+  revisions: Revisions
+  writer: DocumentWriter
+  changed?: (change: DocumentsChange) => void | Promise<void>
+  locks?: DocumentLocks
+}
+
+function touched(operation: DocumentOperation): string[] {
+  return operation.op === 'create' || operation.op === 'delete' ? [operation.dir] : [operation.dir, operation.to]
+}
+
+/** Creating, renaming, copying and deleting a document, each under the document locks and as one commit. */
+export class DocumentOperations {
+  readonly #config: WorkspaceConfig
+  readonly #revisions: Revisions
+  readonly #writer: DocumentWriter
+  readonly #changed: (change: DocumentsChange) => void | Promise<void>
+  readonly #locks?: DocumentLocks
+
+  constructor(options: DocumentOperationsOptions) {
+    this.#config = options.config
+    this.#revisions = options.revisions
+    this.#writer = options.writer
+    this.#changed = options.changed ?? (() => {})
+    this.#locks = options.locks
+  }
+
+  async apply(operation: DocumentOperation, member: Member, prepared?: { documentId?: string, origin: 'editor' | 'agent', changes?: DocumentFileChange[], verify(): Promise<void> }): Promise<OperationAnswer> {
+    if (!hasRole(member, 'editor')) throw new RequestError(403, 'document operations need the role editor')
+    if (this.#config.singleDeck) throw new RequestError(409, 'this workspace is a single deck: it has no document operations')
+    if (operation.op !== 'create' && operation.dir === '') throw new RequestError(409, 'project-root-operation-unavailable')
+    let release: (() => void) | undefined, committedError: RequestError | undefined, cleanupError: unknown
+    try {
+      const answer = await this.#revisions.transaction(async () => {
+        if (prepared) {
+          const claimed = this.#locks?.claimAll([''], `document:${operation.op}`)
+          if (claimed && 'holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+          release ??= claimed?.release
+        }
+        await prepared?.verify()
+        const head = await this.#revisions.head()
+        const before = await this.#writer.checkpoint(touched(operation), operation.op === 'rename' ? { from: operation.dir, to: operation.to } : undefined, prepared?.changes?.map(change => change.path)).catch(error => {
+          if (error instanceof DocumentCheckpointRefusal) throw new RequestError(error.status, error.message, error.detail)
+          throw error
+        })
+        let discardCheckpoint = true
+        try {
+          const claimed = prepared ? undefined : this.#locks?.claimAll(before.documents, `document:${operation.op}`)
+          if (claimed && 'holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+          release ??= claimed?.release
+          let mutationStarted = false
+          try {
+            const result = await this.#apply(operation, member, () => { mutationStarted = true; discardCheckpoint = false }, prepared)
+            discardCheckpoint = true
+            return result
+          }
+          catch (error) {
+            if (!mutationStarted) throw error
+            let after: string | undefined
+            try { after = await this.#revisions.head() }
+            catch { throw new RequestError(500, 'project-commit-state-unavailable', { committed: 'unknown', recovery: before.recovery }) }
+            if (after === undefined) throw new RequestError(500, 'project-commit-state-unavailable', { committed: 'unknown', recovery: before.recovery })
+            if (after !== head) { discardCheckpoint = true; committedError = new RequestError(409, 'project-readback-changed', { committed: true, snapshot: after }); return undefined }
+            try { await before.restore() }
+            catch { throw new RequestError(500, 'project-rollback-failed', { committed: false, recovery: before.recovery }) }
+            discardCheckpoint = true
+            throw error
+          }
+        } finally { if (discardCheckpoint) try { before.dispose() } catch (error) { cleanupError = error } }
+      })
+      if (committedError) throw committedError
+      if (!answer) throw new RequestError(409, 'project-result-unavailable')
+      if (cleanupError) throw new RequestError(500, 'project-checkpoint-cleanup-failed', { committed: Boolean(answer.revision), snapshot: await this.#revisions.head() })
+      const added = operation.op === 'delete' ? [] : [answer.dir!]
+      const removed = operation.op === 'rename' || operation.op === 'delete' ? [operation.dir] : []
+      await this.#changed({ removed, added })
+      return answer
+    } finally {
+      release?.()
+    }
+  }
+
+  async #fill(dir: string, fill: () => Promise<void>): Promise<void> {
+    makeDocumentDir(this.#config.root, dir)
+    try {
+      await fill()
+    } catch (error) {
+      await this.#remove(dir).catch(() => undefined)
+      throw error
+    }
+  }
+
+  async #remove(dir: string): Promise<void> {
+    for (let attempt = 0; ; attempt++) {
+      await this.#writer.empty(dir)
+      try {
+        rmdirSync(join(this.#config.root, dir))
+        return
+      } catch (error) {
+        if (attempt > 0 || (error as NodeJS.ErrnoException).code !== 'ENOTEMPTY') throw new RequestError(409, `${dir} could not be removed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+
+  async #apply(operation: DocumentOperation, member: Member, beforeWrite: () => void, prepared?: { documentId?: string, origin: 'editor' | 'agent', changes?: DocumentFileChange[] }): Promise<OperationAnswer> {
+    const config = this.#config
+    const origin = (done: RevisionOperation): CommitOrigin => ({ kind: prepared?.origin === 'agent' ? 'agent' : 'document', member, operation: done })
+    const commit = (paths: string[], summary: string, body: string, done: RevisionOperation) => this.#revisions.commitWhileLocked({ paths, summary, body, origin: origin(done) })
+    const known = listDocuments(config).map(doc => doc.dir)
+    const existing = (dir: string) => {
+      if (!known.includes(dir)) throw new RequestError(404, `no document ${JSON.stringify(dir)}`)
+      return dir
+    }
+    const fresh = (dir: string) => {
+      const invalid = invalidDocumentDir(dir)
+      if (invalid) throw new RequestError(400, invalid)
+      if (!isDocumentDir(config, dir)) throw new RequestError(400, `"${dir}" is not where the workspace configuration's documents are (${config.documents.join(', ')})`)
+      const holder = known.find(doc => doc !== '' && (isWithin(dir, doc) || isWithin(doc, dir)))
+      if (holder !== undefined) throw new RequestError(409, `${dir} would hold or be inside the document ${holder}`)
+      if (existsSync(join(config.root, dir))) throw new RequestError(409, `${dir} exists already`)
+      return dir
+    }
+    switch (operation.op) {
+      case 'create': {
+        const dir = fresh(operation.dir)
+        const templates = listTemplates(config)
+        const name = operation.template ?? (templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0])
+        if (!name || !templates.includes(name)) throw new RequestError(400, `no document template ${JSON.stringify(name ?? '')}`)
+        const title = operation.title?.trim() || dir.split('/').at(-1)!
+        beforeWrite()
+        await this.#fill(dir, async () => { await this.#writer.template(dir, name, title, prepared?.documentId); if (prepared?.changes) await this.#writer.write(prepared.changes) })
+        const revision = await commit([dir], `Create document ${dir}`, `Title: ${title}\nTemplate: ${name}`, { op: 'create', dir })
+        return { revision, dir }
+      }
+      case 'rename': {
+        const from = existing(operation.dir)
+        const to = fresh(operation.to)
+        beforeWrite()
+        mkdirSync(dirname(join(config.root, to)), { recursive: true })
+        renameSync(join(config.root, from), join(config.root, to))
+        const rewritten = (await this.#writer.relink(from, to)).filter(path => !isWithin(path, to))
+        if (prepared?.changes) { await this.#writer.write(prepared.changes); rewritten.push(...prepared.changes.map(change => change.path)) }
+        const revision = await commit([from, to, ...rewritten], `Rename document ${from} to ${to}`, rewritten.length ? `Links rewritten in: ${rewritten.join(', ')}` : '', { op: 'rename', dir: from, to })
+        return { revision, dir: to }
+      }
+      case 'copy': {
+        const from = existing(operation.dir)
+        const to = fresh(operation.to)
+        beforeWrite()
+        await this.#fill(to, async () => { await this.#writer.copy(from, to, prepared?.documentId, operation.title); if (prepared?.changes) await this.#writer.write(prepared.changes) })
+        const revision = await commit([to], `Copy document ${from} to ${to}`, '', { op: 'copy', dir: from, to })
+        return { revision, dir: to }
+      }
+      case 'delete': {
+        const dir = existing(operation.dir)
+        beforeWrite()
+        await this.#remove(dir)
+        const revision = await commit([dir], `Delete document ${dir}`, '', { op: 'delete', dir })
+        return { revision }
+      }
+    }
+  }
+}