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

package/src/node/page-delete.ts

@@ -0,0 +1,106 @@
+import { fnv1a64, irBlocks, isRecord, jsonResponse, pageIncomingReferences, pageRemovalTargets, removePageSource } from '@lincyaw/kernel'
+import { WORKSPACE_CONFIG } from '@lincyaw/compiler'
+import type { IRBlock, IRSection, MdastNode, PageDeleteAnswer, PageDeletePlan, RequestContext, Route } from '@lincyaw/kernel'
+import { listDocuments, readWorkspaceConfig } 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 type { WorkbenchApi } from './workbench-api.ts'
+
+interface Options { config: WorkspaceConfig, editor: SourceEditor, workbench: WorkbenchApi, locks: DocumentLocks, revisions?: Revisions }
+const markdown = (node: MdastNode): MdastNode => ({ ...node, position: undefined, ...node.children ? { children: node.children.map(markdown) } : {} })
+const blockSemantic = (block: IRBlock): unknown => ({ ...block, source: undefined, node: block.node.type === 'markdown' ? { ...block.node, mdast: markdown(block.node.mdast) } : block.node.type === 'component' ? { ...block.node, ...block.node.children ? { children: block.node.children.map(blockSemantic) } : {}, ...block.node.fallback ? { fallback: markdown(block.node.fallback) } : {} } : block.node })
+const semantic = (section: IRSection): string => JSON.stringify({ ...section, index: undefined, source: undefined, blocks: section.blocks.map(blockSemantic) })
+
+/** Source ranges and incoming links are checked again at confirmation, never trusted from the browser's plan. */
+export function pageDeleteRoute({ config, editor, workbench, locks, revisions }: Options): Route {
+  const inspect = async (ctx: RequestContext, section: string) => {
+    const answer = await workbench.ir(ctx.document)
+    const page = answer.doc.sections.find(page => page.id === section)
+    if (!page) throw new RequestError(409, 'page-context-changed')
+    const source = editor.read(editor.scope(ctx.document), answer.doc.meta.entry, ctx.member)
+    if (answer.sourceFingerprints?.[source.path] !== fnv1a64(source.content)) throw new RequestError(409, 'page-context-changed')
+    const blocks = [...irBlocks(page.blocks)]
+    const plan: PageDeletePlan = {
+      document: ctx.document, section, revision: answer.revision, source: { path: source.path, version: source.version },
+      counts: { steps: page.steps + 1, blocks: blocks.length, narration: blocks.filter(block => block.role === 'narration').length },
+      last: answer.doc.sections.length === 1, allowed: true,
+    }
+    const emptyTitle = answer.doc.meta.lang?.startsWith('en') ? 'Untitled page' : '未命名页面'
+    let removal
+    try { removal = removePageSource(answer.doc, section, source.content, emptyTitle, answer.sourceCapabilities) }
+    catch (error) { plan.allowed = false; plan.reason = error instanceof Error ? error.message : 'page-boundary'; return { plan, answer, source } }
+    const targets = pageRemovalTargets(answer.doc, section, source.content)
+    const others = listDocuments(config).filter(document => document.dir !== ctx.document)
+    const checked = await Promise.all(others.map(async document => ({ document: document.dir, answer: await workbench.ir(document.dir) })))
+    const references = checked.flatMap(other => pageIncomingReferences(other.answer.doc, answer.doc.meta.entry, targets).map(reference => ({ document: other.document, ...reference })))
+    const dependencies = new Map<string, string>()
+    if (!config.singleDeck) {
+      const workspaceSource = editor.read(editor.scope(''), WORKSPACE_CONFIG, ctx.member)
+      const currentConfig = readWorkspaceConfig(config.root)
+      if (JSON.stringify(currentConfig.documents) !== JSON.stringify(config.documents)) throw new RequestError(409, 'page-references-unavailable')
+      dependencies.set(workspaceSource.path, workspaceSource.version)
+      const workspaceView = { ...answer.doc, meta: { ...answer.doc.meta, entry: WORKSPACE_CONFIG }, config: { ...answer.doc.config, presmium: { site: currentConfig.site } }, sections: [] }
+      if (pageIncomingReferences(workspaceView, answer.doc.meta.entry, targets).length) references.push({ document: '', section })
+    }
+    for (const other of checked) {
+      if (!other.answer.sourceFingerprints?.[other.answer.doc.meta.entry]) throw new RequestError(409, 'page-references-unavailable')
+      if (other.answer.sourceFingerprints[source.path]) references.push({ document: other.document, section: other.answer.doc.sections.find(page => page.source.file === source.path)?.id ?? '' })
+      for (const [path, fingerprint] of Object.entries(other.answer.sourceFingerprints)) {
+        const opened = editor.read(editor.scope(''), path, ctx.member)
+        if (fnv1a64(opened.content) !== fingerprint) throw new RequestError(409, 'page-references-unavailable')
+        dependencies.set(path, opened.version)
+      }
+    }
+    if (references.length) { plan.allowed = false; plan.reason = 'page-referenced'; plan.references = references }
+    return { plan, answer, source, removal, dependencies }
+  }
+  return {
+    role: 'editor', maxBody: 8192,
+    handle: (request, ctx) => catchRequestErrors(async () => {
+      if (request.method === 'GET') return jsonResponse((await inspect(ctx, new URL(request.url).searchParams.get('section') ?? '')).plan)
+      if (request.method !== 'POST') throw new RequestError(405, 'GET or POST')
+      const body: unknown = await request.json().catch(() => undefined)
+      if (!isRecord(body) || typeof body.section !== 'string' || typeof body.revision !== 'string' || typeof body.base !== 'string') throw new RequestError(400, '{ section, revision, base }')
+      // Other Studio writes cannot add a new incoming reference between this check and the commit.
+      const directories = listDocuments(config).map(document => document.dir)
+      // The empty document key is the global lock. The source save itself owns
+      // that lock when editing a root document; dependency versions cover the
+      // interval before it is acquired.
+      const claimed = locks.claimAll(ctx.document === '' ? [] : directories.filter(directory => directory !== ctx.document && directory !== ''), 'editor:page-delete-check')
+      if ('holder' in claimed) throw lockedError(claimed.document, claimed.holder)
+      try {
+        const { plan, answer, source, removal, dependencies } = await inspect(ctx, body.section)
+        if (!plan.allowed || !removal) throw new RequestError(409, plan.reason ?? 'page-boundary')
+        if (plan.revision !== body.revision || source.version !== body.base) throw new RequestError(409, 'page-context-changed')
+        const expected = answer.doc.sections.filter(page => page.id !== body.section)
+        let changed = answer
+        const saved = await editor.save(editor.scope(ctx.document), source.path, removal.content, source.version, ctx.member, async path => {
+          const started = Date.now()
+          while (changed.revision === answer.revision) {
+            if (Date.now() - started > 15000) throw new RequestError(409, 'page-compile-timeout')
+            await new Promise(resolve => setTimeout(resolve, 20))
+            changed = await workbench.ir(ctx.document)
+          }
+          const actual = changed.doc.sections
+          if (editor.read(editor.scope(ctx.document), source.path, ctx.member).content !== removal.content) throw new RequestError(409, 'page-context-changed')
+          for (const [path, version] of dependencies ?? []) if (editor.read(editor.scope(''), path, ctx.member).version !== version) throw new RequestError(409, 'page-references-unavailable')
+          if (removal.retainedEmpty ? actual.length !== 1 || actual[0]?.id !== body.section || actual[0]?.blocks.length !== 0
+            : actual.length !== expected.length || expected.some((page, index) => {
+              // The compiler treats the first H1 as its cover. Removing the old
+              // cover normalizes the next unchanged H1 from depth 1 to 0.
+              const normalized = index === 0 && page.depth === 1 && actual[index]?.depth === 0 ? { ...page, depth: 0 } : page
+              return actual[index]?.id !== page.id || semantic(actual[index]!) !== semantic(normalized)
+            })) throw new RequestError(409, 'page-result-changed')
+          if (JSON.stringify(listDocuments(config).map(document => document.dir)) !== JSON.stringify(directories)) throw new RequestError(409, 'page-context-changed')
+          return await revisions?.commit({ files: [path], message: answer.doc.meta.lang?.startsWith('en') ? `Delete page “${answer.doc.sections.find(page => page.id === body.section)!.title}”` : `删除页面“${answer.doc.sections.find(page => page.id === body.section)!.title}”`, origin: { kind: 'editor', member: ctx.member } })
+        })
+        return jsonResponse({ document: ctx.document, selected: removal.selected, retainedEmpty: removal.retainedEmpty, sourceVersion: saved.version, irRevision: changed.revision, ...saved.revision ? { commit: saved.revision } : {} } satisfies PageDeleteAnswer)
+      } finally { claimed.release() }
+    }),
+  }
+}
+

package/src/node/project-files.ts

@@ -0,0 +1,163 @@
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import { DOCUMENT_ENTRY, parseAnchor, validateDocument } from '@lincyaw/kernel'
+import type { ProjectOperation, TeachingDocument, DocumentFileChange } from '@lincyaw/kernel'
+import { invalidDocumentDir, isWithin, movedUrl, rewriteLinks } from '../domain/paths.ts'
+import { isDocumentDir, listDocuments, readWorkspaceConfig } from './config.ts'
+import type { WorkspaceConfig } from './config.ts'
+import { RequestError } from './errors.ts'
+import { DOCUMENT_OPERATION_MAX_BACKUP_BYTES, DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES, documentSourceEntries } from './writer.ts'
+import { findTemplate, listTemplates, DEFAULT_TEMPLATE } from './templates.ts'
+
+export const projectDigest = (value: string | Uint8Array) => createHash('sha256').update(value).digest('hex')
+const entry = (dir: string) => dir ? `${dir}/${DOCUMENT_ENTRY}` : DOCUMENT_ENTRY
+const remote = /^(?:[a-z][a-z\d+.-]*:|\/|#|\?)/i
+export function projectConfiguration(config: WorkspaceConfig): string {
+  const file = join(config.root, 'presmium.workspace.yaml'), stat = lstatSync(file, { throwIfNoEntry: false })
+  if (stat && (!stat.isFile() || stat.size > 1 << 20)) throw new RequestError(413, 'project-configuration-limit')
+  const current = readWorkspaceConfig(config.root)
+  if (JSON.stringify(current) !== JSON.stringify(config)) throw new RequestError(409, 'project-configuration-changed')
+  return projectDigest(Buffer.concat([Buffer.from(JSON.stringify(config)), existsSync(file) ? readFileSync(file) : Buffer.alloc(0)]))
+}
+
+/** Bounded actual directory bytes plus every canonical reference and legacy relink input. No compilation. */
+export function projectMaterial(config: WorkspaceConfig, operation: ProjectOperation, documentId?: string, result = false) {
+  if (operation.dir !== '' && invalidDocumentDir(operation.dir)) throw new RequestError(400, 'project-directory-invalid')
+  if ((operation.op === 'create' && invalidDocumentDir(operation.dir)) || ((operation.op === 'copy' || operation.op === 'rename') && invalidDocumentDir(operation.to))) throw new RequestError(400, 'project-directory-invalid')
+  const hash = createHash('sha256'), seen = new Set<string>(), known = listDocuments(config)
+  let files = 0, bytes = 0
+  const add = (label: string, value: string | Uint8Array) => { hash.update(JSON.stringify([label, projectDigest(value)])) }
+  const limit = () => { throw new RequestError(413, 'project-tree-limit', { maxEntries: DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES, maxBytes: DOCUMENT_OPERATION_MAX_BACKUP_BYTES }) }
+  const walk = (path: string, label: string, documentRoot: string) => {
+    if (seen.has(path)) return
+    seen.add(path)
+    const stat = lstatSync(path, { throwIfNoEntry: false })
+    if (!stat) { add(label, 'absent'); return }
+    if (++files > DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES || (bytes += stat.isDirectory() ? 0 : stat.size) > DOCUMENT_OPERATION_MAX_BACKUP_BYTES) limit()
+    if (stat.isSymbolicLink()) {
+      const target = readlinkSync(path), resolved = posix.normalize(posix.join(posix.dirname(label), target))
+      if (target.startsWith('/') || !isWithin(resolved, documentRoot)) throw new RequestError(409, 'project-external-link-unavailable', { path: label })
+      add(label, 'link:' + target); return
+    }
+    add(label + ':mode', String(stat.mode & 0o777))
+    if (stat.isDirectory()) {
+      for (const name of readdirSync(path).sort()) {
+        if (name === '.git') throw new RequestError(409, 'project-nested-repository')
+        walk(join(path, name), label ? `${label}/${name}` : name, documentRoot)
+      }
+    } else if (stat.isFile()) add(label, readFileSync(path))
+    else throw new RequestError(409, 'project-file-kind-unavailable')
+  }
+  const safeParents = (dir: string) => {
+    let path = config.root
+    for (const part of dir.split('/').filter(Boolean)) {
+      path = join(path, part)
+      const stat = lstatSync(path, { throwIfNoEntry: false })
+      if (!stat) break
+      if (!stat.isDirectory()) throw new RequestError(409, 'project-directory-unavailable')
+      if (existsSync(join(path, '.git'))) throw new RequestError(409, 'project-nested-repository')
+    }
+  }
+  const dirs = operation.op === 'copy' || operation.op === 'rename' ? [operation.dir, operation.to] : [operation.dir]
+  if (operation.op === 'retitle') walk(join(config.root, entry(operation.dir)), entry(operation.dir), operation.dir)
+  else for (const dir of dirs) { safeParents(dir); walk(join(config.root, dir), dir, dir) }
+  const canonical = new Map<string, TeachingDocument>()
+  for (const doc of known) {
+    safeParents(doc.dir)
+    const path = join(config.root, doc.entry), stat = lstatSync(path)
+    if (!stat.isFile() || stat.size > 2 << 20) throw new RequestError(413, 'project-document-limit', { document: doc.dir })
+    if (++files > DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES || (bytes += stat.size) > DOCUMENT_OPERATION_MAX_BACKUP_BYTES) limit()
+    const raw = readFileSync(path); add(doc.entry, raw)
+    let parsed: unknown
+    try { parsed = JSON.parse(raw.toString('utf8')) } catch { throw new RequestError(422, 'project-document-invalid', { document: doc.dir }) }
+    const checked = validateDocument(parsed)
+    if (!checked.document) throw new RequestError(422, 'project-document-invalid', { document: doc.dir })
+    canonical.set(doc.dir, checked.document)
+    if (operation.op === 'rename' || operation.op === 'delete') for (const item of documentSourceEntries(join(config.root, doc.dir), () => { if (++files > DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES) limit() })) {
+      if (item.link !== undefined || !item.path.endsWith('.md')) continue
+      const rel = doc.dir ? `${doc.dir}/${item.path}` : item.path, content = readFileSync(join(config.root, rel))
+      if ((bytes += content.length) > DOCUMENT_OPERATION_MAX_BACKUP_BYTES || ++files > DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES) limit()
+      add(rel, content)
+      if (!result && operation.op === 'delete' && !isWithin(rel, operation.dir) && rewriteLinks(content.toString('utf8'), rel, rel, operation.dir, '__removed__') !== content.toString('utf8')) throw new RequestError(409, 'project-referenced', { path: rel })
+    }
+  }
+  let template: string | undefined
+  if (operation.op === 'create') {
+    const templates = listTemplates(config)
+    template = operation.template ?? (templates.includes(DEFAULT_TEMPLATE) ? DEFAULT_TEMPLATE : templates[0])
+    const source = template && findTemplate(config, template)
+    if (!source) throw new RequestError(400, 'project-template-unavailable')
+    walk(source, '@template', '@template')
+    const stat = lstatSync(join(source, DOCUMENT_ENTRY), { throwIfNoEntry: false })
+    if (!stat?.isFile() || stat.size > 2 << 20) throw new RequestError(422, 'project-template-invalid')
+    const checked = validateDocument(JSON.parse(readFileSync(join(source, DOCUMENT_ENTRY), 'utf8')))
+    if (!checked.document) throw new RequestError(422, 'project-template-invalid')
+    canonical.set('@template', checked.document)
+  }
+  if (result) return { impactFiles: 0, impactBytes: 0, tree: hash.digest('hex'), files, bytes, changes: [] as DocumentFileChange[], template }
+  if (operation.op !== 'create' && !canonical.has(operation.dir)) throw new RequestError(404, 'project-document-not-found')
+  const target = operation.op === 'create' ? operation.dir : operation.op === 'copy' || operation.op === 'rename' ? operation.to : undefined
+  if (target !== undefined) {
+    if (invalidDocumentDir(target) || !isDocumentDir(config, target)) throw new RequestError(400, 'project-directory-invalid')
+    if (existsSync(join(config.root, target))) throw new RequestError(409, 'project-target-exists')
+    if (known.some(doc => doc.dir !== '' && (isWithin(target, doc.dir) || isWithin(doc.dir, target)))) throw new RequestError(409, 'project-nested-document')
+  }
+  const impactRoot = operation.op === 'create' ? findTemplate(config, template!)! : join(config.root, operation.dir)
+  const impactEntries = operation.op === 'retitle' ? [{ path: DOCUMENT_ENTRY }] : operation.op === 'delete' || operation.op === 'rename'
+    ? (() => { const entries: { path: string }[] = []; const collect = (dir: string, prefix: string) => { for (const name of readdirSync(dir)) { const path = prefix ? `${prefix}/${name}` : name, stat = lstatSync(join(impactRoot, path)); if (stat.isDirectory()) collect(join(impactRoot, path), path); else entries.push({ path }) } }; collect(impactRoot, ''); return entries })()
+    : documentSourceEntries(impactRoot)
+  const impactFiles = impactEntries.length, impactBytes = impactEntries.reduce((sum, item) => sum + lstatSync(join(impactRoot, item.path)).size, 0)
+  const changes: DocumentFileChange[] = []
+  const moving = operation.op === 'copy' || operation.op === 'rename', deleting = operation.op === 'delete'
+  for (const [dir, document] of canonical) {
+    const own = dir === operation.dir || dir === '@template', from = dir === '@template' ? '' : dir
+    if (operation.op === 'copy' && !own || operation.op === 'create' && dir !== '@template' || operation.op === 'retitle' && !own || deleting && own) continue
+    const to = own && moving ? operation.to : own && operation.op === 'create' ? operation.dir : from
+    const was = entry(from), next = entry(to), before = JSON.stringify(document)
+    const refused = (pointer: string) => { throw new RequestError(409, 'project-reference-unsupported', { document: dir, pointer }) }
+    const url = (value: string, pointer: string): string => {
+      if (remote.test(value)) return value
+      let path: string
+      try { path = decodeURI(value.split(/[?#]/)[0]!) } catch { return refused(pointer) }
+      if (deleting && isWithin(posix.normalize(posix.join(from, path)), operation.dir)) throw new RequestError(409, 'project-referenced', { document: dir, pointer })
+      return moving ? movedUrl(value, next, was, operation.dir, operation.to) ?? value : value
+    }
+    for (const [id, asset] of Object.entries(document.assets)) asset.location = url(asset.location, `/assets/${id}/location`)
+    for (const [id, definition] of Object.entries(document.definitions)) if (definition.implementation.type === 'file') definition.implementation.path = url(definition.implementation.path, `/definitions/${id}/implementation/path`)
+    const rich = (value: unknown, pointer: string) => {
+      if (!value || typeof value !== 'object') return
+      if (Array.isArray(value)) { value.forEach((node, index) => rich(node, `${pointer}/${index}`)); return }
+      const node = value as Record<string, unknown>
+      if (node.type === 'link' && typeof node.href === 'string') node.href = url(node.href, `${pointer}/href`)
+      // Only the typed rich-text tree is traversed; plugin data and arbitrary strings are never rewritten.
+      if (Array.isArray(node.children)) rich(node.children, pointer + '/children')
+      if (Array.isArray(node.fallback)) rich(node.fallback, pointer + '/fallback')
+    }
+    for (const [id, block] of Object.entries(document.blocks)) {
+      if (block.type === 'text') rich(block.content, `/blocks/${id}/content`)
+      if (block.type === 'image') rich(block.caption, `/blocks/${id}/caption`)
+      if (block.type === 'code') for (const origin of [block.origin, ...block.variants?.map(variant => variant.origin) ?? []]) {
+        if (!origin || origin.repo) continue
+        const parsed = parseAnchor(origin.anchor), at = parsed?.scheme === 'pattern' ? parsed.target.indexOf('#') : parsed?.target.lastIndexOf('#')
+        if (!parsed || !['region', 'symbol', 'pattern'].includes(parsed.scheme) || at === undefined || at < 1) { if (own && moving) refused(`/blocks/${id}/origin`); continue }
+        const path = parsed.target.slice(0, at)
+        if (deleting && isWithin(path, operation.dir)) throw new RequestError(409, 'project-referenced', { document: dir, pointer: `/blocks/${id}/origin` })
+        if (moving && isWithin(path, operation.dir) && origin.pin) {
+          if (operation.op === 'rename') throw new RequestError(409, 'project-pinned-anchor-rename-unavailable', { document: dir, pointer: `/blocks/${id}/origin` })
+          continue
+        }
+        if (moving && isWithin(path, operation.dir)) origin.anchor = `${parsed.scheme}:${operation.to}${path.slice(operation.dir.length)}${parsed.target.slice(at)}`
+      }
+    }
+    for (const [threadId, thread] of Object.entries(document.comments ?? {})) for (const comment of thread.comments) rich(comment.content, `/comments/${threadId}/comments/${comment.id}/content`)
+    if (document.metadata.translationOf) document.metadata.translationOf.entry = url(document.metadata.translationOf.entry, '/metadata/translationOf/entry')
+    if (document.metadata.translations) for (const lang of Object.keys(document.metadata.translations)) document.metadata.translations[lang] = url(document.metadata.translations[lang]!, `/metadata/translations/${lang}`)
+    if (own && (operation.op === 'create' || operation.op === 'copy')) { document.id = documentId!; if (operation.title) { document.metadata.title = operation.title; for (const section of Object.values(document.sections)) if (section.title === '{{title}}') section.title = operation.title } }
+    if (own && operation.op === 'retitle') document.metadata.title = operation.title
+    if (JSON.stringify(document) !== before || own && (operation.op === 'create' || operation.op === 'copy')) changes.push({ path: next, content: Buffer.from(JSON.stringify(document, null, 2) + '\n') })
+  }
+  if (operation.op === 'retitle' && changes.length === 0) throw new RequestError(409, 'project-no-change')
+  if (changes.length > 16 || changes.reduce((size, change) => size + ('content' in change ? change.content.length : 0), 0) > 2 << 20) throw new RequestError(413, 'project-reference-limit', { maxFiles: 16, maxBytes: 2 << 20 })
+  return { impactFiles, impactBytes, tree: hash.digest('hex'), files, bytes, changes, template }
+}

package/src/node/projects.ts

@@ -0,0 +1,192 @@
+import type { DocumentEditor } from './document-authoring.ts'
+import { listDocuments } from './config.ts'
+import { randomUUID } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_MAX_PLANS, PROJECT_PLAN_TTL_MS, PROJECT_MAX_REQUEST_CHARS, PROJECT_MAX_RESPONSE_CHARS, hasRole, jsonResponse, problemResponse, validateDocument } from '@lincyaw/kernel'
+import type { CanonicalSource, DocumentChange, ProjectApplied, ProjectApply, ProjectAuthoring, ProjectCaller, ProjectOperation, ProjectPlan, ProjectPlanRequest, Route } from '@lincyaw/kernel'
+import { validateProjectApply, validateProjectPlan } from '@lincyaw/kernel/node'
+import type { WorkspaceConfig } from './config.ts'
+import type { DocumentOperations } from './document-operations.ts'
+import type { Git } from './git.ts'
+import type { Revisions } from './revisions.ts'
+import { DOCUMENT_OPERATION_MAX_BACKUP_BYTES, DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES, documentDirOf } from './writer.ts'
+import { catchRequestErrors, RequestError } from './errors.ts'
+import { projectConfiguration, projectDigest, projectMaterial } from './project-files.ts'
+
+type Admission = { signature: string, admission: Promise<ProjectPlan> }
+type Stored = { member: string, origin: ProjectCaller['origin'], signature: string, plan: ProjectPlan, material?: ReturnType<typeof projectMaterial>, canonical?: { change: DocumentChange, planId: string, source: CanonicalSource }, receipt?: ProjectApplied, work?: Promise<ProjectApplied> }
+const budget = (value: unknown) => { const raw = JSON.stringify(value); if (raw === undefined) throw new RequestError(400, 'project-request-invalid'); if (raw.length > PROJECT_MAX_REQUEST_CHARS) throw new RequestError(413, 'project-request-too-large') }
+const bounded = <T>(value: T): T => { if (JSON.stringify(value, null, 2).length > PROJECT_MAX_RESPONSE_CHARS) throw new RequestError(413, 'project-response-too-large'); return value }
+const signature = (request: ProjectPlanRequest) => projectDigest(JSON.stringify([request.id, Object.fromEntries(Object.entries(request.operation).sort(([a], [b]) => a.localeCompare(b)))]))
+
+/** One project plan owner; directory and metadata changes retain their existing transaction owners. */
+export function createProjectAuthoring(options: { config: WorkspaceConfig, operations?: DocumentOperations, revisions?: Revisions, git?: Git, documentEditor?: DocumentEditor }) {
+  const { config, operations, revisions, git, documentEditor } = options, plans = new Map<string, Stored | Admission>()
+  const settled = (): Stored[] => [...plans.values()].filter((value): value is Stored => 'plan' in value)
+  let closed = false
+  const reasons = (caller: ProjectCaller, operation?: ProjectOperation) => [
+    ...!hasRole(caller.member, 'editor') ? ['project-permission-denied'] : [],
+    ...caller.boundDocument !== undefined && (!operation || operation.op !== 'retitle' || operation.dir !== caller.boundDocument) ? ['project-workspace-scope-required'] : [],
+    ...operation?.op === 'retitle' ? (!documentEditor ? ['project-metadata-unavailable'] : []) : [
+      ...config.singleDeck ? ['project-single-document-workspace'] : [],
+      ...!operations || !revisions || !git ? ['project-git-unavailable'] : [],
+    ],
+    ...caller.origin === 'agent' && config.approvals.operate === 'off' ? ['project-operation-disabled'] : [],
+    ...caller.origin === 'agent' && config.settings['presmium.assistant']?.review === 'required' ? ['authoring-review-required'] : [],
+  ]
+  const authorize = (caller: ProjectCaller, operation?: ProjectOperation) => {
+    if (closed) throw new RequestError(503, 'project-owner-closed')
+    const refusal = reasons(caller, operation)[0]
+    if (refusal) throw new RequestError(refusal === 'project-permission-denied' || refusal === 'project-workspace-scope-required' ? 403 : 409, refusal)
+  }
+  const sourceOf = (value: Awaited<ReturnType<DocumentEditor['read']>>): CanonicalSource => ({ documentId: value.content.id, version: value.version, fingerprint: value.fingerprint })
+  const compactRevision = (value: ProjectApplied['revision']) => value && { ...value, message: value.message.split('\n')[0]!.slice(0, 240), author: value.author.slice(0, 120), origin: { kind: value.origin.kind }, files: value.files.filter(path => path.length <= 500).slice(0, 6) }
+  const observation = async () => ({ snapshot: await revisions?.head(), configuration: projectConfiguration(config) })
+  const current = async (stored: Stored, result: boolean, caller: ProjectCaller) => {
+    if (stored.canonical) {
+      if (projectConfiguration(config) !== stored.plan.observation.configuration) throw new RequestError(409, 'project-configuration-changed')
+      const actual = sourceOf(await documentEditor!.read(stored.plan.operation.dir, caller.member))
+      const expected = result ? stored.receipt?.source : stored.canonical.source
+      if (!expected || actual.documentId !== expected.documentId || actual.version !== expected.version || actual.fingerprint !== expected.fingerprint) throw new RequestError(409, 'document-version-changed', { source: actual })
+      return
+    }
+    const observed = await observation()
+    const expected = result ? stored.receipt : stored.plan.observation
+    if (observed.configuration !== stored.plan.observation.configuration || observed.snapshot !== (result ? stored.receipt?.snapshot : expected?.snapshot)) throw new RequestError(409, 'project-source-changed', { observation: observed })
+    const material = projectMaterial(config, stored.plan.operation, stored.plan.documentId, result)
+    if (material.tree !== (result ? stored.receipt?.tree : stored.plan.tree)) throw new RequestError(409, 'project-tree-changed')
+  }
+  const key = (request: ProjectPlanRequest, caller: ProjectCaller) => JSON.stringify([caller.member.id, caller.origin, request.id])
+  const service: ProjectAuthoring = {
+    async capabilities(caller) {
+      if (closed) throw new RequestError(503, 'project-owner-closed')
+      const observed = await observation(), directory = reasons(caller), metadata = reasons(caller, { op: 'retitle', dir: caller.boundDocument ?? '', title: 'capability' })
+      if (!observed.snapshot && !directory.includes('project-git-unavailable')) directory.push('project-head-unavailable')
+      const actions = Object.fromEntries(['create', 'copy', 'rename', 'delete', 'retitle'].map(op => { const unavailable = op === 'retitle' ? metadata : directory; return [op, { available: unavailable.length === 0, reasons: unavailable }] })) as import('@lincyaw/kernel').ProjectCapabilities['actions']
+      const available = Object.values(actions).some(action => action.available)
+      return bounded({ available, actions, reasons: available ? [] : [...new Set([...directory, ...metadata])], observation: observed, verification: 'configuration-only', rootDirectoryOperations: false,
+        limits: { requestChars: PROJECT_MAX_REQUEST_CHARS, responseChars: PROJECT_MAX_RESPONSE_CHARS, backupEntries: DOCUMENT_OPERATION_MAX_BACKUP_ENTRIES, backupBytes: DOCUMENT_OPERATION_MAX_BACKUP_BYTES, plans: PROJECT_MAX_PLANS, ttlMs: PROJECT_PLAN_TTL_MS } })
+    },
+    async plan(request, caller) {
+      budget(request)
+      if (!validateProjectPlan(request)) throw new RequestError(400, 'project-plan-invalid')
+      authorize(caller, request.operation)
+      if (request.operation.op === 'retitle') {
+        if (!listDocuments(config).some(document => document.dir === request.operation.dir)) throw new RequestError(404, 'project-document-not-found')
+        const id = key(request, caller), signatureValue = signature(request), existing = plans.get(id)
+        if (existing) { if (existing.signature !== signatureValue) throw new RequestError(409, 'project-intent-id-reused'); if ('admission' in existing) return existing.admission; await current(existing, Boolean(existing.receipt), caller); return structuredClone(existing.plan) }
+        for (const [id, value] of plans) if ('plan' in value && !value.work && Date.parse(value.plan.expiresAt) <= Date.now()) plans.delete(id)
+        if (plans.size >= PROJECT_MAX_PLANS) throw new RequestError(429, 'project-plan-capacity')
+        const operation = { ...request.operation, title: request.operation.title.trim() }
+        if (!operation.title) throw new RequestError(400, 'project-title-required')
+        const admission = (async () => {
+          const before = await documentEditor!.read(operation.dir, caller.member), source = sourceOf(before)
+          const change: DocumentChange = { id: 'project-title:' + randomUUID(), baseDocumentVersion: source.version, replacement: { ...before.content, metadata: { ...before.content.metadata, title: operation.title } } }
+          const canonical = await documentEditor!.plan(operation.dir, change, caller.member)
+          authorize(caller, operation)
+          const draft = { id: request.id, planId: randomUUID(), operation, observation: { configuration: projectConfiguration(config) }, source, documentId: source.documentId, expiresAt: canonical.expiresAt, impact: { added: [operation.dir], removed: [], files: 1, bytes: Buffer.byteLength(JSON.stringify(before.content)), referenceDocuments: [] as string[], referencePolicy: 'preserve-or-refuse' as const } }
+          const plan = bounded({ ...draft, digest: projectDigest(JSON.stringify([draft, canonical.digest])) })
+          plans.set(id, { member: caller.member.id, origin: caller.origin, signature: signatureValue, plan, canonical: { source, change, planId: canonical.planId } })
+          return structuredClone(plan)
+        })()
+        const pending: Admission = { signature: signatureValue, admission }; plans.set(id, pending)
+        try { return await admission } catch (error) { if (plans.get(id) === pending) plans.delete(id); throw error }
+      }
+      if (request.operation.dir === '' && !['create', 'retitle'].includes(request.operation.op)) throw new RequestError(409, 'project-root-operation-unavailable')
+      return git!.exclusive(async () => {
+        authorize(caller, request.operation)
+        for (const [id, stored] of plans) if ('plan' in stored && !stored.work && Date.parse(stored.plan.expiresAt) <= Date.now()) plans.delete(id)
+        const id = key(request, caller), existing = plans.get(id), sig = signature(request)
+        if (existing) { if (existing.signature !== sig) throw new RequestError(409, 'project-intent-id-reused'); if ('admission' in existing) return existing.admission; await current(existing, Boolean(existing.receipt), caller); return structuredClone(existing.plan) }
+        if (plans.size >= PROJECT_MAX_PLANS) throw new RequestError(429, 'project-plan-capacity')
+        const observed = await observation()
+        if (!observed.snapshot) throw new RequestError(409, 'project-head-unavailable')
+        const documentId = request.operation.op === 'create' || request.operation.op === 'copy' ? randomUUID() : undefined
+        const input = request.operation.op === 'create' ? { ...request.operation, title: request.operation.title?.trim() || request.operation.dir.split('/').at(-1)! } : structuredClone(request.operation)
+        const material = projectMaterial(config, input, documentId)
+        const operation = input.op === 'create' ? { ...input, template: material.template } : input
+        {
+          const dirty = await revisions!.uncommittedFiles([...material.changes.map(change => change.path), ...operation.op === 'delete' || operation.op === 'rename' ? [operation.dir] : []])
+          if (dirty.length) throw new RequestError(409, 'project-uncommitted-target', { count: dirty.length })
+        }
+        const draft = { id: request.id, planId: randomUUID(), operation, observation: observed, tree: material.tree, ...documentId ? { documentId } : {}, expiresAt: new Date(Date.now() + PROJECT_PLAN_TTL_MS).toISOString(),
+          impact: { added: operation.op === 'delete' ? [] : [operation.op === 'rename' || operation.op === 'copy' ? operation.to : operation.dir], removed: operation.op === 'delete' || operation.op === 'rename' ? [operation.dir] : [], files: material.impactFiles, bytes: material.impactBytes, referenceDocuments: [...new Set(material.changes.map(change => documentDirOf(config, change.path)).filter((dir): dir is string => dir !== undefined && dir !== (operation.op === 'rename' || operation.op === 'copy' ? operation.to : operation.dir)))], referencePolicy: 'preserve-or-refuse' as const } }
+        const plan = bounded({ ...draft, digest: projectDigest(JSON.stringify(draft)) })
+        plans.set(id, { member: caller.member.id, origin: caller.origin, signature: sig, plan, material })
+        return structuredClone(plan)
+      })
+    },
+    async readPlan(request, caller) {
+      budget(request)
+      if (!validateProjectApply(request)) throw new RequestError(400, 'project-apply-invalid')
+      const stored = settled().find(item => item.plan.planId === request.planId && item.member === caller.member.id && item.origin === caller.origin)
+      if (!stored || stored.plan.digest !== request.digest) throw new RequestError(404, 'project-plan-not-found')
+      authorize(caller, stored.plan.operation)
+      if (!stored.receipt && Date.parse(stored.plan.expiresAt) <= Date.now()) throw new RequestError(409, 'project-plan-expired')
+      await current(stored, Boolean(stored.receipt), caller)
+      return structuredClone(stored.plan)
+    },
+    async apply(request: ProjectApply, caller: ProjectCaller, signal?: AbortSignal) {
+      signal?.throwIfAborted()
+      budget(request)
+      if (!validateProjectApply(request)) throw new RequestError(400, 'project-apply-invalid')
+      const stored = settled().find(item => item.plan.planId === request.planId && item.member === caller.member.id && item.origin === caller.origin)
+      if (!stored || stored.plan.digest !== request.digest) throw new RequestError(404, 'project-plan-not-found')
+      authorize(caller, stored.plan.operation)
+      if (stored.plan.operation.op === 'delete' && request.confirmDeletion !== true) throw new RequestError(409, 'project-deletion-confirmation-required')
+      if (stored.receipt) { await current(stored, true, caller); return structuredClone(stored.receipt) }
+      if (Date.parse(stored.plan.expiresAt) <= Date.now()) throw new RequestError(409, 'project-plan-expired')
+      if (stored.work) return stored.work
+      const work = (async () => {
+        if (stored.canonical) {
+          await current(stored, false, caller); signal?.throwIfAborted(); authorize(caller, stored.plan.operation)
+          const answer = caller.origin === 'agent'
+            ? await documentEditor!.apply(stored.plan.operation.dir, { change: stored.canonical.change, planId: stored.canonical.planId }, caller.member)
+            : await documentEditor!.change(stored.plan.operation.dir, stored.canonical.change, caller.member)
+          const source = sourceOf(answer), actual = sourceOf(await documentEditor!.read(stored.plan.operation.dir, caller.member))
+          if (JSON.stringify(source) !== JSON.stringify(actual)) throw new RequestError(409, 'project-readback-changed', { saved: true, source })
+          const receipt: ProjectApplied = bounded({ id: stored.plan.id, planId: stored.plan.planId, dir: stored.plan.operation.dir, documentId: source.documentId, source,
+            ...answer.commit ? { snapshot: answer.commit.id, revision: compactRevision(answer.commit), revisionTruncated: true, fileCount: answer.commit.files.length } : {}, verification: { saved: true, readback: 'verified', compiled: 'not-requested' } })
+          stored.receipt = receipt
+          return structuredClone(receipt)
+        }
+        if (stored.plan.operation.op === 'retitle' || !stored.material) throw new RequestError(409, 'project-plan-invalid')
+        // DocumentOperations owns the queue; verify runs inside that transaction before any mutation.
+        const answer = await operations!.apply(stored.plan.operation, caller.member, { documentId: stored.plan.documentId, origin: caller.origin, changes: stored.material.changes,
+          verify: async () => { signal?.throwIfAborted(); authorize(caller, stored.plan.operation); if (Date.parse(stored.plan.expiresAt) <= Date.now()) throw new RequestError(409, 'project-plan-expired'); await current(stored, false, caller)
+            const op = stored.plan.operation
+            if ((await revisions!.uncommittedFiles([...stored.material!.changes.map(change => change.path), ...op.op === 'rename' || op.op === 'delete' ? [op.dir] : []])).length) throw new RequestError(409, 'project-uncommitted-target')
+          } })
+        try {
+          const snapshot = await revisions!.head()
+          if (!snapshot || answer.revision?.id !== snapshot) throw new RequestError(409, 'project-readback-changed', { committed: true })
+          const material = projectMaterial(config, stored.plan.operation, stored.plan.documentId, true)
+          const revision = answer.revision && { ...answer.revision, message: answer.revision.message.split('\n')[0]!.slice(0, 240), author: answer.revision.author.slice(0, 120), origin: { kind: answer.revision.origin.kind }, files: answer.revision.files.filter(path => path.length <= 500).slice(0, 6) }
+          const receipt: ProjectApplied = { dir: answer.dir, revision, revisionTruncated: true, fileCount: answer.revision?.files.length, id: stored.plan.id, planId: stored.plan.planId, snapshot, tree: material.tree, ...stored.plan.documentId ? { documentId: stored.plan.documentId } : {}, verification: { saved: true, readback: 'verified', compiled: 'not-requested' } }
+          const op = stored.plan.operation
+          if (op.op === 'rename' || op.op === 'delete') if (existsSync(join(config.root, op.dir))) throw new RequestError(409, 'project-readback-changed', { committed: true })
+          for (const change of stored.material!.changes) if ('content' in change && projectDigest(readFileSync(join(config.root, change.path))) !== projectDigest(change.content)) throw new RequestError(409, 'project-readback-changed', { committed: true })
+          if (stored.plan.documentId && answer.dir) {
+            const checked = validateDocument(JSON.parse(readFileSync(join(config.root, answer.dir, 'lecture.json'), 'utf8')))
+            if (checked.document?.id !== stored.plan.documentId) throw new RequestError(409, 'project-readback-changed', { committed: true })
+          }
+          stored.receipt = bounded(receipt)
+          return structuredClone(stored.receipt)
+        } catch (error) {
+          if (error instanceof RequestError && error.detail?.committed === true) throw error
+          throw new RequestError(409, 'project-readback-changed', { committed: true, planId: stored.plan.planId })
+        }
+      })()
+      stored.work = work
+      try { return await work } finally { if (stored.work === work) stored.work = undefined }
+    },
+  }
+  const caller = (member: ProjectCaller['member']): ProjectCaller => ({ member, origin: 'editor' })
+  const routes: Record<string, Route> = {
+    'project/capabilities': { role: 'reader', handle: (request, ctx) => catchRequestErrors(async () => request.method === 'GET' ? jsonResponse(await service.capabilities(caller(ctx.member))) : problemResponse(405, 'GET')) },
+    'project/plan': { role: 'editor', maxBody: PROJECT_MAX_REQUEST_CHARS * 4, handle: (request, ctx) => catchRequestErrors(async () => { if (request.method !== 'POST') return problemResponse(405, 'POST'); return jsonResponse(await service.plan(await request.json().catch(() => undefined), caller(ctx.member))) }) },
+    'project/apply': { role: 'editor', maxBody: PROJECT_MAX_REQUEST_CHARS * 4, handle: (request, ctx) => catchRequestErrors(async () => { if (request.method !== 'POST') return problemResponse(405, 'POST'); return jsonResponse(await service.apply(await request.json().catch(() => undefined), caller(ctx.member), request.signal)) }) },
+  }
+  return { service, routes, async close() { closed = true; await Promise.allSettled<unknown>([...plans.values()].map(value => 'admission' in value ? value.admission : value.work)); plans.clear() } }
+}