create-egregore 0.18.0 → 0.18.1

package/runtime/codex/bin/lib/edit-loopback.mjs

@@ -1,652 +0,0 @@
-// /api/edit/* loopback handlers for the /edit skill.
-//
-// Spec: notes/edit-spec-contract.md (locked 2026-05-04).
-// Wired into bin/view-server.mjs. Co-exists with /api/comment — does not
-// modify any existing /view or /api/comment behavior.
-//
-// Sections referenced below map to the contract:
-//   §2  AnnotationSidecar JSON schema
-//   §3  Loopback API surface
-//   §4  Source-map renderer extension points
-//   §5  Token + session lifecycle
-//   §7  Path encoding / containment
-//
-// Design notes:
-// - One helper module instead of inlining everything in view-server.mjs to keep
-//   the existing comment path untouched and easy to read.
-// - The renderer (A2's work in packages/egregore-artifacts/lib/markdown.js) is
-//   imported softly: if `buildParagraphIndex` or the new `renderMarkdown(text,
-//   {sourceMap})` signature is missing, /api/edit/render returns a 503 with a
-//   clear error code. The other endpoints stay functional.
-// - Token derivation reuses the existing session-id at .egregore-session-id.
-//   No new on-disk token files (Contract §5 explicitly forbids it).
-
-import http from 'node:http';
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { pathToFileURL } from 'node:url';
-
-// --- Config ---------------------------------------------------------------
-
-const ALLOWED_ORIGIN = 'http://127.0.0.1:7321';
-const BLOCKED_DIRS = ['node_modules/', '.git/', 'bin/', '.claude/'];
-const SIDECAR_SUFFIX = '.annotations.json';
-const SESSION_ID_PATTERN = /^[0-9]{8}T[0-9]{6}-[a-z0-9_-]+-[0-9]+$/i;
-const ANN_ID_PATTERN = /^ann_[0-9TZ:.\-]+_[a-f0-9]{6}$/;
-const REP_ID_PATTERN = /^rep_[0-9TZ:.\-]+_[a-f0-9]{6}$/;
-const REPLY_KINDS = new Set(['proposal', 'acknowledge', 'discussion', 'applied']);
-const CLASSIFICATIONS = new Set(['green', 'yellow', 'red', null]);
-const STATUSES = new Set(['active', 'accepted', 'discarded', 'orphaned']);
-
-// State machine (Contract §2.4)
-const ALLOWED_TRANSITIONS = {
-  active: new Set(['accepted', 'discarded', 'orphaned']),
-  orphaned: new Set(['active']), // v0.2 manual re-anchor
-  accepted: new Set(),
-  discarded: new Set(),
-};
-
-// --- HTTP error helper ----------------------------------------------------
-
-class HttpError extends Error {
-  constructor(status, code, message) {
-    super(message || code);
-    this.status = status;
-    this.code = code;
-  }
-}
-
-// --- Body / response helpers ---------------------------------------------
-
-function readJsonBody(req, max = 1024 * 1024) {
-  return new Promise((resolve, reject) => {
-    let total = 0;
-    const chunks = [];
-    req.on('data', (c) => {
-      total += c.length;
-      if (total > max) {
-        reject(new HttpError(413, 'body_too_large', 'request body too large'));
-        req.destroy();
-        return;
-      }
-      chunks.push(c);
-    });
-    req.on('end', () => {
-      const text = Buffer.concat(chunks).toString('utf-8');
-      if (!text.trim()) return resolve(null);
-      try { resolve(JSON.parse(text)); }
-      catch (e) { reject(new HttpError(400, 'invalid_json', 'invalid JSON: ' + e.message)); }
-    });
-    req.on('error', (e) => reject(new HttpError(400, 'request_error', e.message)));
-  });
-}
-
-function sendEdit(res, status, body) {
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': ALLOWED_ORIGIN,
-    'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-    'Access-Control-Allow-Headers': 'Authorization, Content-Type',
-    'Vary': 'Origin',
-  });
-  res.end(JSON.stringify(body));
-}
-
-function sendEditError(res, err) {
-  if (err instanceof HttpError) {
-    return sendEdit(res, err.status, { error: err.message, code: err.code });
-  }
-  return sendEdit(res, 500, { error: err && err.message ? err.message : 'internal error' });
-}
-
-// --- Path validation (Contract §7) ---------------------------------------
-
-export function validateDocPath(encoded, repoRoot) {
-  if (!encoded || typeof encoded !== 'string') {
-    throw new HttpError(400, 'missing_doc', 'missing ?doc query parameter');
-  }
-  let decoded;
-  try {
-    decoded = Buffer.from(encoded, 'base64url').toString('utf8');
-  } catch {
-    throw new HttpError(400, 'invalid_encoding', 'doc is not valid base64url');
-  }
-  if (!decoded) throw new HttpError(400, 'empty_path', 'decoded path is empty');
-  if (decoded.startsWith('/')) throw new HttpError(400, 'absolute_path', 'absolute paths not allowed');
-  if (decoded.includes('..')) throw new HttpError(400, 'parent_traversal', '`..` not allowed in path');
-  if (!decoded.endsWith('.md')) throw new HttpError(400, 'not_markdown', 'doc must be a .md file');
-  if (BLOCKED_DIRS.some((b) => decoded.startsWith(b))) {
-    throw new HttpError(400, 'blocked_dir', `paths under ${BLOCKED_DIRS.join(', ')} are blocked`);
-  }
-  const resolved = path.resolve(repoRoot, decoded);
-  // Use path.sep guard so /repo and /repo-bak aren't conflated.
-  if (resolved !== repoRoot && !resolved.startsWith(repoRoot + path.sep)) {
-    throw new HttpError(400, 'outside_repo', 'resolved path falls outside repo root');
-  }
-  return {
-    docPath: decoded,
-    resolved,
-    sidecarPath: resolved + SIDECAR_SUFFIX,
-  };
-}
-
-// --- Token store (Contract §5) -------------------------------------------
-//
-// Keyed by sessionId. Holds {nonce, issuedAt}. Lost on view-server restart
-// (fail-secure — Contract §5.3). Never written to disk.
-
-const tokenStore = new Map();
-
-function readSessionIdFromDisk(repoRoot) {
-  const projectLocal = path.join(repoRoot, '.egregore-session-id');
-  try {
-    const v = fs.readFileSync(projectLocal, 'utf8').trim();
-    if (v) return v;
-  } catch { /* fall through */ }
-  // Fallback: ~/.egregore/session-<projHash>.id
-  try {
-    const projHash = crypto.createHash('md5').update(repoRoot).digest('hex');
-    const home = process.env.HOME || process.env.USERPROFILE;
-    if (home) {
-      const v = fs.readFileSync(path.join(home, '.egregore', `session-${projHash}.id`), 'utf8').trim();
-      if (v) return v;
-    }
-  } catch { /* fall through */ }
-  return null;
-}
-
-function deriveToken(sessionId, nonce) {
-  return crypto
-    .createHmac('sha256', sessionId)
-    .update(nonce)
-    .digest('base64url')
-    .slice(0, 32);
-}
-
-function timingSafeEq(a, b) {
-  if (typeof a !== 'string' || typeof b !== 'string') return false;
-  const A = Buffer.from(a);
-  const B = Buffer.from(b);
-  if (A.length !== B.length) return false;
-  return crypto.timingSafeEqual(A, B);
-}
-
-export function issueToken(sessionId, repoRoot) {
-  if (!sessionId || !SESSION_ID_PATTERN.test(sessionId)) {
-    throw new HttpError(400, 'invalid_session_id', 'sessionId format invalid');
-  }
-  const onDisk = readSessionIdFromDisk(repoRoot);
-  if (!onDisk) {
-    throw new HttpError(400, 'no_session_on_disk', 'no .egregore-session-id found in repo root');
-  }
-  if (onDisk !== sessionId) {
-    throw new HttpError(400, 'session_mismatch', 'sessionId does not match current project session');
-  }
-  // Reissue with a fresh nonce on every call — invalidates any prior token
-  // for this sessionId. Cheap (16 hex chars) and avoids stale-token confusion.
-  const nonce = crypto.randomBytes(8).toString('hex');
-  const token = deriveToken(sessionId, nonce);
-  tokenStore.set(sessionId, { nonce, issuedAt: new Date().toISOString() });
-  return { token, port: 7321, expiresHint: 'session-bound' };
-}
-
-function authenticate(req, repoRoot) {
-  const auth = req.headers['authorization'] || req.headers['Authorization'];
-  if (!auth || !auth.startsWith('Bearer ')) {
-    throw new HttpError(401, 'missing_token', 'missing Authorization: Bearer token');
-  }
-  const supplied = auth.slice('Bearer '.length).trim();
-  const sessionId = readSessionIdFromDisk(repoRoot);
-  if (!sessionId) {
-    throw new HttpError(401, 'no_session', 'view-server cannot read current session id');
-  }
-  const entry = tokenStore.get(sessionId);
-  if (!entry) {
-    throw new HttpError(401, 'no_active_token', 'no token issued for current session — call POST /api/edit/session/init');
-  }
-  const expected = deriveToken(sessionId, entry.nonce);
-  if (!timingSafeEq(expected, supplied)) {
-    throw new HttpError(401, 'bad_token', 'token does not match current session');
-  }
-  return { sessionId };
-}
-
-function checkOrigin(req, methodIsWrite) {
-  if (!methodIsWrite) return; // §3 only requires Origin check on writes
-  const origin = req.headers['origin'];
-  // Allow missing Origin (e.g. curl / agent-side calls); browsers will always
-  // send one, and a forged Origin from a hostile page is the threat we care
-  // about. Anything that doesn't match the locked origin is rejected.
-  if (origin && origin !== ALLOWED_ORIGIN) {
-    throw new HttpError(403, 'bad_origin', `Origin must be ${ALLOWED_ORIGIN}`);
-  }
-}
-
-// --- Sidecar I/O ---------------------------------------------------------
-
-function emptySidecar(docPath, sessionId) {
-  return {
-    schemaVersion: 1,
-    doc: docPath,
-    sessionId: sessionId || null,
-    annotations: [],
-  };
-}
-
-function readSidecar(sidecarPath, docPath, sessionId) {
-  if (!fs.existsSync(sidecarPath)) {
-    return emptySidecar(docPath, sessionId);
-  }
-  const raw = fs.readFileSync(sidecarPath, 'utf8');
-  let parsed;
-  try { parsed = JSON.parse(raw); }
-  catch (e) {
-    throw new HttpError(500, 'sidecar_corrupt', 'sidecar is not valid JSON: ' + e.message);
-  }
-  if (!parsed || typeof parsed !== 'object') {
-    throw new HttpError(500, 'sidecar_corrupt', 'sidecar root is not an object');
-  }
-  if (parsed.schemaVersion !== 1) {
-    throw new HttpError(500, 'sidecar_version', 'unsupported sidecar schemaVersion');
-  }
-  parsed.annotations = Array.isArray(parsed.annotations) ? parsed.annotations : [];
-  return parsed;
-}
-
-function atomicWriteJson(targetPath, obj) {
-  const dir = path.dirname(targetPath);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${targetPath}.tmp.${process.pid}.${Date.now()}`;
-  const data = JSON.stringify(obj, null, 2) + '\n';
-  const fd = fs.openSync(tmp, 'w');
-  try {
-    fs.writeSync(fd, data);
-    fs.fsyncSync(fd);
-  } finally {
-    fs.closeSync(fd);
-  }
-  fs.renameSync(tmp, targetPath);
-}
-
-// --- ID + timestamp helpers ----------------------------------------------
-
-function fsTimestamp() {
-  // ISO without colons (Contract §2.3 — colons stripped for fs safety):
-  // 2026-05-04T10-23-45.123Z → strip ms+Z to match the regex shape used in
-  // existing tooling. We keep ms precision in createdAt but the ID uses
-  // seconds-only.
-  const d = new Date();
-  const pad = (n, w = 2) => String(n).padStart(w, '0');
-  return (
-    d.getUTCFullYear() +
-    '-' + pad(d.getUTCMonth() + 1) +
-    '-' + pad(d.getUTCDate()) +
-    'T' + pad(d.getUTCHours()) +
-    '-' + pad(d.getUTCMinutes()) +
-    '-' + pad(d.getUTCSeconds())
-  );
-}
-
-function rand6hex() {
-  return crypto.randomBytes(3).toString('hex');
-}
-
-function newAnnotationId() {
-  return `ann_${fsTimestamp()}_${rand6hex()}`;
-}
-
-function newReplyId() {
-  return `rep_${fsTimestamp()}_${rand6hex()}`;
-}
-
-// --- Validators (Contract §2.2) ------------------------------------------
-
-function validateAnchor(anchor) {
-  if (!anchor || typeof anchor !== 'object') {
-    throw new HttpError(400, 'invalid_anchor', 'selection is required');
-  }
-  for (const k of ['section', 'paragraphId', 'charRange', 'fingerprint']) {
-    if (!(k in anchor)) throw new HttpError(400, 'invalid_anchor', `selection.${k} required`);
-  }
-  if (typeof anchor.section !== 'string' || !/^§[0-9]+(\.[0-9]+)?\.? .+/.test(anchor.section)) {
-    throw new HttpError(400, 'invalid_anchor', 'selection.section format invalid');
-  }
-  if (typeof anchor.paragraphId !== 'string' || !/^sha256:[a-f0-9]{16}$/.test(anchor.paragraphId)) {
-    throw new HttpError(400, 'invalid_anchor', 'selection.paragraphId format invalid');
-  }
-  if (!Array.isArray(anchor.charRange) || anchor.charRange.length !== 2 ||
-      !Number.isInteger(anchor.charRange[0]) || !Number.isInteger(anchor.charRange[1]) ||
-      anchor.charRange[0] < 0 || anchor.charRange[1] < 0) {
-    throw new HttpError(400, 'invalid_anchor', 'selection.charRange must be [int,int]');
-  }
-  if (typeof anchor.fingerprint !== 'string' || anchor.fingerprint.length === 0 ||
-      anchor.fingerprint.length > 64) {
-    throw new HttpError(400, 'invalid_anchor', 'selection.fingerprint must be 1-64 chars');
-  }
-}
-
-function validateAnnotationInput(ann) {
-  if (!ann || typeof ann !== 'object') {
-    throw new HttpError(400, 'invalid_annotation', 'annotation body required');
-  }
-  validateAnchor(ann.selection);
-  if ('classification' in ann && !CLASSIFICATIONS.has(ann.classification)) {
-    throw new HttpError(400, 'invalid_classification', 'classification must be green|yellow|red|null');
-  }
-  if (typeof ann.comment !== 'string' || ann.comment.length === 0) {
-    throw new HttpError(400, 'invalid_comment', 'comment is required');
-  }
-  if (typeof ann.author !== 'string' || ann.author.length === 0) {
-    throw new HttpError(400, 'invalid_author', 'author is required');
-  }
-  if ('status' in ann && !STATUSES.has(ann.status)) {
-    throw new HttpError(400, 'invalid_status', 'status must be active|accepted|discarded|orphaned');
-  }
-  if (ann.id !== undefined && (typeof ann.id !== 'string' || !ANN_ID_PATTERN.test(ann.id))) {
-    throw new HttpError(400, 'invalid_id', 'annotation id format invalid');
-  }
-}
-
-function validateReplyInput(rep) {
-  if (!rep || typeof rep !== 'object') {
-    throw new HttpError(400, 'invalid_reply', 'reply body required');
-  }
-  if (typeof rep.author !== 'string' || rep.author.length === 0) {
-    throw new HttpError(400, 'invalid_reply', 'author required');
-  }
-  if (!REPLY_KINDS.has(rep.kind)) {
-    throw new HttpError(400, 'invalid_reply', 'kind must be proposal|acknowledge|discussion|applied');
-  }
-  if (typeof rep.text !== 'string') {
-    throw new HttpError(400, 'invalid_reply', 'text required (may be empty)');
-  }
-  if (rep.id !== undefined && (typeof rep.id !== 'string' || !REP_ID_PATTERN.test(rep.id))) {
-    throw new HttpError(400, 'invalid_reply', 'reply id format invalid');
-  }
-}
-
-// --- Anchor validation against current paragraphIndex (Contract task 5) --
-
-function reanchor(annotation, paragraphIndex) {
-  // If the renderer produced no index, skip — leave status as-is.
-  if (!Array.isArray(paragraphIndex) || paragraphIndex.length === 0) return annotation;
-  const sel = annotation.selection;
-  if (!sel) return annotation;
-
-  const exact = paragraphIndex.find((p) => p.paragraphId === sel.paragraphId);
-  if (exact) {
-    if (annotation.status === 'orphaned') {
-      annotation.status = 'active'; // re-anchored; allowed transition
-    }
-    return annotation;
-  }
-
-  // Fuzzy: paragraph text contains the fingerprint, or fingerprint contains
-  // ≥80% of paragraph text. Cheap heuristic — anchor algorithms can grow.
-  if (sel.fingerprint) {
-    const fp = sel.fingerprint.trim();
-    const candidate = paragraphIndex.find((p) => {
-      if (!p.text) return false;
-      if (p.text.includes(fp)) return true;
-      if (fp.length >= 12 && fp.includes(p.text.trim().slice(0, 32))) return true;
-      return false;
-    });
-    if (candidate) {
-      annotation.selection = { ...sel, paragraphId: candidate.paragraphId, section: candidate.section || sel.section };
-      if (annotation.status === 'orphaned') annotation.status = 'active';
-      return annotation;
-    }
-  }
-
-  // No match — orphan it (only if currently active; respects state machine).
-  if (annotation.status === 'active') annotation.status = 'orphaned';
-  return annotation;
-}
-
-// --- Renderer integration (soft import) ----------------------------------
-//
-// A2 is extending packages/egregore-artifacts/lib/markdown.js. Until they
-// land buildParagraphIndex + the (text, opts) signature of renderMarkdown,
-// /api/edit/render returns 503 with code "renderer_not_ready".
-
-let cachedRenderer = null;
-
-async function loadRenderer(repoRoot) {
-  if (cachedRenderer) return cachedRenderer;
-  const mdPath = path.join(repoRoot, 'packages', 'egregore-artifacts', 'lib', 'markdown.js');
-  if (!fs.existsSync(mdPath)) {
-    throw new HttpError(503, 'renderer_not_ready', 'markdown.js not found at expected path');
-  }
-  let mod;
-  try {
-    mod = await import(pathToFileURL(mdPath).href);
-  } catch (e) {
-    throw new HttpError(503, 'renderer_not_ready', 'failed to load markdown.js: ' + e.message);
-  }
-  // renderMarkdownToHtml wraps renderMarkdown + renderToStaticMarkup so
-  // react-dom/server resolves from the artifact package's own node_modules.
-  if (typeof mod.renderMarkdownToHtml !== 'function' || typeof mod.buildParagraphIndex !== 'function') {
-    throw new HttpError(503, 'renderer_not_ready',
-      'renderer missing renderMarkdownToHtml/buildParagraphIndex exports');
-  }
-  cachedRenderer = mod;
-  return mod;
-}
-
-// --- Endpoint handlers ---------------------------------------------------
-
-async function handleSessionInit(req, res, repoRoot) {
-  // POST /api/edit/session/init
-  // No auth required (it issues the auth). Origin still checked.
-  checkOrigin(req, true);
-  const body = await readJsonBody(req);
-  if (!body || typeof body.sessionId !== 'string') {
-    throw new HttpError(400, 'invalid_session_id', 'request body must include sessionId');
-  }
-  const result = issueToken(body.sessionId, repoRoot);
-  sendEdit(res, 200, result);
-}
-
-async function handleRender(req, res, url, repoRoot) {
-  authenticate(req, repoRoot);
-  const { docPath, resolved } = validateDocPath(url.searchParams.get('doc'), repoRoot);
-  if (!fs.existsSync(resolved)) throw new HttpError(404, 'doc_not_found', `doc not found: ${docPath}`);
-  const text = fs.readFileSync(resolved, 'utf8');
-  const renderer = await loadRenderer(repoRoot);
-  const html = renderer.renderMarkdownToHtml(text, { sourceMap: true });
-  const paragraphIndex = renderer.buildParagraphIndex(text);
-  sendEdit(res, 200, { html, sourceText: text, paragraphIndex });
-}
-
-async function handleGetAnnotations(req, res, url, repoRoot) {
-  const { sessionId } = authenticate(req, repoRoot);
-  const { docPath, sidecarPath } = validateDocPath(url.searchParams.get('doc'), repoRoot);
-  const sidecar = readSidecar(sidecarPath, docPath, sessionId);
-  sendEdit(res, 200, sidecar);
-}
-
-async function handlePostAnnotation(req, res, url, repoRoot) {
-  const { sessionId } = authenticate(req, repoRoot);
-  checkOrigin(req, true);
-  const { docPath, resolved, sidecarPath } = validateDocPath(url.searchParams.get('doc'), repoRoot);
-  const ann = await readJsonBody(req);
-  validateAnnotationInput(ann);
-
-  const sidecar = readSidecar(sidecarPath, docPath, sessionId);
-  const idx = ann.id ? sidecar.annotations.findIndex((a) => a.id === ann.id) : -1;
-
-  // Status-transition enforcement on update
-  if (idx >= 0) {
-    const prev = sidecar.annotations[idx];
-    if (ann.status && ann.status !== prev.status) {
-      const allowed = ALLOWED_TRANSITIONS[prev.status];
-      if (!allowed || !allowed.has(ann.status)) {
-        throw new HttpError(409, 'bad_status_transition',
-          `cannot move from ${prev.status} to ${ann.status}`);
-      }
-    }
-  }
-
-  // Optional: re-anchor against current paragraphIndex. Only attempt if the
-  // renderer is ready; if it isn't, skip silently — anchoring stays as-is.
-  let paragraphIndex = null;
-  try {
-    if (fs.existsSync(resolved)) {
-      const renderer = await loadRenderer(repoRoot);
-      paragraphIndex = renderer.buildParagraphIndex(fs.readFileSync(resolved, 'utf8'));
-    }
-  } catch (e) {
-    if (!(e instanceof HttpError && e.code === 'renderer_not_ready')) throw e;
-  }
-
-  const now = new Date().toISOString();
-  const merged = idx >= 0
-    ? { ...sidecar.annotations[idx], ...ann, id: sidecar.annotations[idx].id }
-    : {
-        id: ann.id || newAnnotationId(),
-        selection: ann.selection,
-        classification: ann.classification ?? null,
-        autoClassified: !!ann.autoClassified,
-        comment: ann.comment,
-        author: ann.author,
-        createdAt: ann.createdAt || now,
-        thread: Array.isArray(ann.thread) ? ann.thread : [],
-        status: ann.status || 'active',
-      };
-
-  if (paragraphIndex) reanchor(merged, paragraphIndex);
-
-  if (idx >= 0) sidecar.annotations[idx] = merged;
-  else sidecar.annotations.push(merged);
-
-  if (!sidecar.sessionId) sidecar.sessionId = sessionId;
-  atomicWriteJson(sidecarPath, sidecar);
-
-  sendEdit(res, idx >= 0 ? 200 : 201, { id: merged.id, annotation: merged });
-}
-
-async function handlePostReply(req, res, url, repoRoot) {
-  const { sessionId } = authenticate(req, repoRoot);
-  checkOrigin(req, true);
-  const { docPath, sidecarPath } = validateDocPath(url.searchParams.get('doc'), repoRoot);
-  const annId = (url.searchParams.get('id') || '').trim();
-  if (!annId || !ANN_ID_PATTERN.test(annId)) {
-    throw new HttpError(400, 'invalid_id', 'missing or malformed ?id=<annotationId>');
-  }
-  const reply = await readJsonBody(req);
-  validateReplyInput(reply);
-
-  const sidecar = readSidecar(sidecarPath, docPath, sessionId);
-  const target = sidecar.annotations.find((a) => a.id === annId);
-  if (!target) throw new HttpError(404, 'annotation_not_found', `annotation ${annId} not found`);
-  if (!Array.isArray(target.thread)) target.thread = [];
-
-  const now = new Date().toISOString();
-  const newReply = {
-    id: reply.id || newReplyId(),
-    author: reply.author,
-    kind: reply.kind,
-    createdAt: reply.createdAt || now,
-    text: reply.text,
-  };
-  if (reply.metadata && typeof reply.metadata === 'object') newReply.metadata = reply.metadata;
-  target.thread.push(newReply);
-
-  atomicWriteJson(sidecarPath, sidecar);
-  sendEdit(res, 201, { replyId: newReply.id, annotationId: annId });
-}
-
-async function handleDeleteAnnotation(req, res, url, repoRoot) {
-  const { sessionId } = authenticate(req, repoRoot);
-  checkOrigin(req, true);
-  const { docPath, sidecarPath } = validateDocPath(url.searchParams.get('doc'), repoRoot);
-  const annId = (url.searchParams.get('id') || '').trim();
-  if (!annId || !ANN_ID_PATTERN.test(annId)) {
-    throw new HttpError(400, 'invalid_id', 'missing or malformed ?id=<annotationId>');
-  }
-  const sidecar = readSidecar(sidecarPath, docPath, sessionId);
-  const target = sidecar.annotations.find((a) => a.id === annId);
-  if (!target) throw new HttpError(404, 'annotation_not_found', `annotation ${annId} not found`);
-
-  const allowed = ALLOWED_TRANSITIONS[target.status] || new Set();
-  if (target.status === 'discarded' || !allowed.has('discarded')) {
-    if (target.status === 'discarded') {
-      // idempotent — already discarded; report 200 + current state
-      return sendEdit(res, 200, { id: target.id, status: target.status });
-    }
-    throw new HttpError(409, 'bad_status_transition',
-      `cannot move from ${target.status} to discarded`);
-  }
-  target.status = 'discarded';
-  atomicWriteJson(sidecarPath, sidecar);
-  sendEdit(res, 200, { id: target.id, status: target.status });
-}
-
-// --- Top-level dispatcher -------------------------------------------------
-
-export function isEditPath(reqUrl) {
-  const u = (reqUrl || '').split('?')[0];
-  return u.startsWith('/api/edit/');
-}
-
-// Returns true if handled (so view-server skips its own 404 fallback).
-export async function handleEditRequest(req, res, repoRoot) {
-  const url = new URL(req.url, `http://127.0.0.1:7321`);
-  const pathname = url.pathname;
-
-  // OPTIONS preflight (Contract §3.7) — locked-down origin
-  if (req.method === 'OPTIONS') {
-    res.writeHead(204, {
-      'Access-Control-Allow-Origin': ALLOWED_ORIGIN,
-      'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-      'Access-Control-Allow-Headers': 'Authorization, Content-Type',
-      'Access-Control-Max-Age': '600',
-      'Vary': 'Origin',
-    });
-    res.end();
-    return true;
-  }
-
-  try {
-    if (req.method === 'POST' && pathname === '/api/edit/session/init') {
-      await handleSessionInit(req, res, repoRoot);
-      return true;
-    }
-    if (req.method === 'GET' && pathname === '/api/edit/render') {
-      await handleRender(req, res, url, repoRoot);
-      return true;
-    }
-    if (req.method === 'GET' && pathname === '/api/edit/annotations') {
-      await handleGetAnnotations(req, res, url, repoRoot);
-      return true;
-    }
-    if (req.method === 'POST' && pathname === '/api/edit/annotations') {
-      await handlePostAnnotation(req, res, url, repoRoot);
-      return true;
-    }
-    if (req.method === 'POST' && pathname === '/api/edit/replies') {
-      await handlePostReply(req, res, url, repoRoot);
-      return true;
-    }
-    if (req.method === 'DELETE' && pathname === '/api/edit/annotations') {
-      await handleDeleteAnnotation(req, res, url, repoRoot);
-      return true;
-    }
-    sendEdit(res, 404, { error: 'edit endpoint not found', code: 'not_found' });
-    return true;
-  } catch (err) {
-    sendEditError(res, err);
-    return true;
-  }
-}
-
-// --- Test exports (for smoke tests) --------------------------------------
-
-export const _testing = {
-  validateDocPath,
-  deriveToken,
-  tokenStore,
-  ALLOWED_ORIGIN,
-  BLOCKED_DIRS,
-};