@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.14

package/src/runtime/obsidian/view-permission.mjs

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import { readObsidianEnablement } from './enablement.mjs'
+import { DEFAULT_FULL_RECONCILIATION_INTERVAL_MS, configFilesOf } from './engine.mjs'
+import { readFileFacts } from './observation.mjs'
+
+// Whether the project allows a view of this workspace right now.
+//
+// What the service stored about a view (its freshness, its pending edits) says
+// what was true when it was written. A view can be turned off, or taken out of
+// the project, or the project can point at another workspace, well before the
+// next tick writes that down; and what a tick then writes still carries the
+// view's generations and counts. So before a stored report is told to whoever
+// holds the view open, `permits(scopeId)` asks the project as it is at that
+// moment:
+//
+//   the view        the Obsidian settings are enabled and declare it
+//   the workspace   the project's pointer names this workspace, and its
+//                   private state is where this service keeps it
+//
+// Whatever cannot be established is "no": a project that does not load,
+// settings that refuse, a pointer that cannot be read, a load that has not
+// answered yet. Nothing is written. This is not about who may see a note; the
+// audiences of machine-settings.mjs decide that when a view is prepared.
+//
+// Cost. Loading a project runs Git in child processes, and a plugin asks every
+// two seconds for every vault it holds open. A project is therefore kept, and
+// loaded again only when a file that decides what it is changed: the files the
+// engine observes as configuration (configFilesOf), compared at every request
+// by a digest of what they hold, never by their times. The pointer and the
+// place of the workspace's private state are read at every request.
+//
+//   what a file holds   where it really is and the bytes there: its path
+//                       resolved as the system resolves it when the loader
+//                       opens it (realpath(3), through a link anywhere on the
+//                       way), so a link pointed elsewhere, its own or a
+//                       folder's above it, is a change. Nothing there is a
+//                       state like any other. A folder in a file's place, a
+//                       link that leads nowhere or to anything but a regular
+//                       file, and a file that does not read vouch for nothing.
+//                       Where the system resolves no path for a regular file
+//                       that is there and is not a link (some volumes on
+//                       Windows; a C library that needs /proc and has none),
+//                       the file holds its own path as given and its bytes: a
+//                       link above it pointed elsewhere is not seen there
+//   a project is kept   when two loads in a row, each started after the
+//                       files were read and found to hold the same, returned
+//                       the same project as far as this permission reads one:
+//                       the views it enables, and what the service's
+//                       workspace resolution reads of it, handed in as
+//                       `workspaceInputsOf` (where its pointer
+//                       is, the data root its local overlay prefers, the
+//                       roots it protects). One load is not enough: a file
+//                       changed and changed back while it ran leaves the same
+//                       bytes around a project read from other ones, and
+//                       reading the files once more when it answers shows
+//                       nothing. The second load reads the project again.
+//                       The first load of all only tells which files decide
+//                       the project, so three loads keep the first project
+//                       and two keep one after a change
+//   and used            only while the files hold what they held before
+//                       those loads, read again at every request
+//   and not for long    a kept project is loaded again once it is half as old
+//                       as the engine's full reconciliations are apart, and
+//                       is never used past that interval: whatever no file
+//                       here names is seen by then
+//
+// While a file vouches for nothing no project is kept: a loader that answers
+// at once is asked at every request, and its answer decides that request, as
+// it does for the two requests that come before a project is kept.
+//
+// A loader may answer a promise (one that composes a personal workspace off
+// the event loop). The answer to a request never waits for it: a plugin gives
+// a request a second and a half, and takes an answer that does not come for a
+// service that is gone. The load is started, one at a time, and a request is
+// only ever decided from a kept project: until two loads agreed the view is
+// not permitted, and while a kept project is loaded again it goes on deciding,
+// within its time. A load that has not answered by its deadline is given up,
+// whether a request or its own late answer is the first to see the deadline
+// passed, and what it answers then is ignored.
+//
+// A load that fails (it throws, it is refused, it is given up, or it answers a
+// promise while a file vouches for nothing) ends whatever was kept, and is not
+// asked for again at once: after two seconds, then four, up to thirty, for as
+// long as the files hold the same. A change to them is tried at once, once a
+// load has named them: until a load has answered, a corrected configuration
+// waits for the next try. And while one of them vouches for nothing there is
+// no digest to change: after a load that failed then (one that answers a
+// promise, or one that answers at once and threw), a change to another file
+// waits for the next try as well.
+//
+// `onLoad({ durationMs, outcome, promised, kept, sameFiles, vouched, at })` is
+// told how long each load took and how it ended (`answered`, `failed` or
+// `given-up`), whether a project is kept after it, whether it named the files
+// that decide the project as they were when it started (not the first load,
+// which started over none, nor one that named other files), whether those
+// files vouched then, and when it ended (`now()`): times, codes and flags
+// only. createLoadReport, below, counts them and decides which are worth a
+// log line.
+
+// A kept project is never used for longer than the engine goes without a full reconciliation.
+export const DEFAULT_KEEP_FOR_MS = DEFAULT_FULL_RECONCILIATION_INTERVAL_MS
+// Longer than the two minutes a composition in a worker is given, so one that runs out of its own time answers first.
+export const DEFAULT_LOAD_DEADLINE_MS = 150 * 1000
+export const DEFAULT_RETRY_AFTER_MS = 2 * 1000
+export const DEFAULT_RETRY_AT_MOST_MS = 30 * 1000
+
+// What one file holds, as [path, its real path, digest of the bytes there], or [path, null, null] when it is absent;
+// undefined when it vouches for nothing. The real path is the system's own (realpath(3)): JavaScript's realpathSync
+// takes a `..` after a link away before following the link, and names a file the loader never opens.
+function heldBy(file, realpath) {
+  let real
+  try { real = realpath(file) } catch {
+    // Unresolved. Nothing there is absent. A regular file that is there, and is not a link, is read where it is given
+    // (readFileFacts follows no link at its end). A link, resolved or not, never is: it leads nowhere, or nobody can say where.
+    let stat
+    try { stat = fs.lstatSync(file, { throwIfNoEntry: false }) } catch (inner) { return inner.code === 'ENOTDIR' ? [file, null, null] : undefined }
+    if (stat === undefined) return [file, null, null]
+    if (!stat.isFile()) return undefined
+    real = file
+  }
+  let facts
+  try { facts = readFileFacts(real) } catch { return undefined }
+  return facts === null ? undefined : [file, real, facts.digest]
+}
+
+// One digest over what every file holds, in order. Null when one of them vouches for nothing.
+function digestOver(files, realpath) {
+  const hash = createHash('sha256')
+  for (const file of files) {
+    const held = heldBy(file, realpath)
+    if (held === undefined) return null
+    hash.update(`${JSON.stringify(held)}\n`)
+  }
+  return hash.digest('hex')
+}
+
+// The views the project enables. Settings that refuse enable none.
+function viewsOf(project) {
+  try {
+    const enablement = readObsidianEnablement(project)
+    return new Set(enablement.state === 'enabled' ? enablement.scopes.map((scope) => scope.scopeId) : [])
+  } catch { return new Set() }
+}
+
+export const STATUS_LOAD_EVENT = 'status-project-loaded'
+// A second: most of the second and a half a plugin gives a request, spent on the listener's own event loop.
+export const DEFAULT_SLOW_LOAD_MS = 1000
+// How long a row of failed or slow loads goes on through loads that answered in time between them.
+export const DEFAULT_ROW_ENDS_AFTER_MS = 60 * 1000
+
+// Counts every load a permission is told about (onLoad), and writes a line for the ones somebody has to see:
+//
+//   failed, given up   the first in a row, then when the row is 2, 4, 8, ... long, so a loader that keeps failing
+//                      writes a line less and less often, never one per try
+//   answered           the one that ends a row of failures; one that answered at once and held the event loop for
+//                      `slowMs` or more, on the same doubling row while slow loads follow each other; and one after
+//                      which nothing is kept although it named the files it started over, from the second in a row
+//                      on the same doubling row: a load at every request
+//
+// A row of failures ends only at a load that answers `rowEndsAfterMs` or more after its last failure, and a row of
+// slow loads at a load that answers in time that long after its last slow one. While loads come closer together than
+// that (a load at every request, or the retries after a failure), a loader that fails, or is slow, every other load or
+// every third keeps one row, written less and less often, not a line per load. A kept project is loaded again only
+// every half of its keep time, so there a row of failures ends at the next reload that answers: a loader that answers
+// at least one reload between two failures writes each failure and the load that ends its row, as before, and one that
+// fails at every reload and answers only at its retry keeps one row. A row of loads after which nothing is kept ends
+// at the next that keeps a project. A load that named other files than it started over (the first, or one after a
+// change that names other files) neither counts nor ends that row, so a start and a change, each with one load that
+// has nothing to agree with yet, write none of these, unless the change lands while a load reads the files. Any other
+// load that answered in time and kept the project writes nothing unless it ends a row of failures: that is every load
+// of a healthy service. A line holds the event, milliseconds, the outcome, flags and counts; never a path, a view or a
+// message.
+export function createLoadReport({ write, slowMs = DEFAULT_SLOW_LOAD_MS, rowEndsAfterMs = DEFAULT_ROW_ENDS_AFTER_MS }) {
+  if (typeof write !== 'function') throw new TypeError('a load report needs somewhere to write')
+  const counts = { answered: 0, failed: 0, givenUp: 0, slow: 0, notKept: 0, longestMs: 0 }
+  const doubled = (row) => (row & (row - 1)) === 0
+  let failedInARow = 0
+  let lastFailedAt = 0
+  let slowInARow = 0
+  let lastSlowAt = 0
+  let notKeptInARow = 0
+  return {
+    // `kept` and `sameFiles` default to a load that kept its project, `vouched` to files that vouched, and `at` to now.
+    onLoad({ durationMs, outcome, promised, kept = true, sameFiles = true, vouched = true, at = performance.now() }) {
+      const ms = Math.round(durationMs)
+      counts.longestMs = Math.max(counts.longestMs, ms)
+      if (outcome !== 'answered') {
+        counts[outcome === 'given-up' ? 'givenUp' : 'failed'] += 1
+        failedInARow += 1
+        lastFailedAt = at
+        if (doubled(failedInARow)) write({ event: STATUS_LOAD_EVENT, durationMs: ms, outcome, promised, inARow: failedInARow })
+        return
+      }
+      counts.answered += 1
+      const afterFailures = failedInARow > 0 && at - lastFailedAt >= rowEndsAfterMs ? failedInARow : 0
+      if (afterFailures > 0) failedInARow = 0
+      const slow = !promised && ms >= slowMs
+      if (slow) {
+        counts.slow += 1
+        slowInARow += 1
+        lastSlowAt = at
+      } else if (slowInARow > 0 && at - lastSlowAt >= rowEndsAfterMs) slowInARow = 0
+      const notKept = sameFiles && !kept
+      if (notKept) {
+        counts.notKept += 1
+        notKeptInARow += 1
+      } else if (sameFiles) notKeptInARow = 0
+      const writeSlow = slow && doubled(slowInARow)
+      const writeNotKept = notKept && notKeptInARow >= 2 && doubled(notKeptInARow)
+      if (afterFailures > 0 || writeSlow || writeNotKept) {
+        write({
+          event: STATUS_LOAD_EVENT, durationMs: ms, outcome, promised,
+          ...(afterFailures > 0 ? { afterFailures } : {}),
+          ...(writeSlow ? { slow: true, inARow: slowInARow } : {}),
+          ...(writeNotKept ? { notKept: true, notKeptInARow, vouched } : {}),
+        })
+      }
+    },
+    // answered, failed, givenUp, slow and notKept loads so far, and the longest in milliseconds.
+    counts: () => ({ ...counts }),
+  }
+}
+
+// `resolveWorkspace(project)` answers { workspaceId, workspaceRoot } as the project names them now, or null, and
+// `workspaceInputsOf(project)` what it reads of a project to do so, as JSON: the service hands in its own of both
+// (resolveServiceWorkspace, serviceWorkspaceInputs), so what two loads are compared by is never a copy kept here.
+// `now()` answers milliseconds that only go up; the times are this module's defaults unless a test gives its own.
+// `realpath(file)` resolves a path as the system does; a test hands in one that fails.
+export function createViewPermission({
+  loadProject, resolveWorkspace, workspaceInputsOf, workspaceId, workspaceRoot, now = () => performance.now(),
+  keepForMs = DEFAULT_KEEP_FOR_MS, loadDeadlineMs = DEFAULT_LOAD_DEADLINE_MS, retryAfterMs = DEFAULT_RETRY_AFTER_MS, retryAtMostMs = DEFAULT_RETRY_AT_MOST_MS,
+  onLoad = () => {}, realpath = fs.realpathSync.native,
+}) {
+  if (typeof loadProject !== 'function') throw new TypeError('a view permission needs loadProject')
+  if (typeof resolveWorkspace !== 'function') throw new TypeError('a view permission needs resolveWorkspace')
+  if (typeof workspaceInputsOf !== 'function') throw new TypeError('a view permission needs workspaceInputsOf')
+  const digestOf = (files) => digestOver(files, realpath)
+  // What two loads have to agree on: the views, and what the workspace is resolved from. Nothing else of a project is
+  // compared, so a field that differs from load to load (a time, a binding under a symbol key) does not keep a project
+  // from being kept, and nothing a decision reads is left out.
+  const decidedBy = (project, views) => JSON.stringify([[...views].sort(), workspaceInputsOf(project)])
+  // The files that decided the project last loaded.
+  let files = null
+  // What the last load returned that was started over files that vouched: { digest, shape }.
+  let seen = null
+  // The project two such loads agreed on: { project, views, digest, since }, `since` the start of the second.
+  let kept = null
+  // A load that answered a promise and has not answered yet: { id, digest, startedAt }.
+  let underWay = null
+  // Loads that failed in a row while the files held the same: { digest, times, at }.
+  let failed = null
+  let started = 0
+
+  function fail(digest, at) {
+    kept = null
+    failed = { digest, times: failed !== null && failed.digest === digest ? failed.times + 1 : 1, at }
+  }
+  const tooSoon = (digest, at) => failed !== null && failed.digest === digest && at - failed.at < Math.min(retryAtMostMs, retryAfterMs * 2 ** (failed.times - 1))
+  // `before` and `vouched`: the files that decided the project when the load started, and whether they vouched then.
+  const sameList = (left, right) => left !== null && right !== null && left.length === right.length && left.every((file, index) => file === right[index])
+  const told = (startedAt, outcome, promised, { before, vouched }) => {
+    try { const at = now(); onLoad({ durationMs: Math.max(0, at - startedAt), outcome, promised, kept: kept !== null, sameFiles: sameList(before, files), vouched, at }) } catch { /* only told */ }
+  }
+
+  // What a load returned; `digest` was read before it started. A project that names other files than the ones read
+  // is kept under a digest the next request cannot read again, so it is dropped there, before it decides anything.
+  function answered(project, digest, since) {
+    files = configFilesOf(project).map((file) => file.absolute)
+    const views = viewsOf(project)
+    const loaded = { project, views, digest, since }
+    const shape = digest === null ? null : decidedBy(project, views)
+    kept = digest !== null && seen !== null && seen.digest === digest && seen.shape === shape ? loaded : null
+    seen = digest === null ? null : { digest, shape }
+    return loaded
+  }
+
+  // Asks the loader. What it returned, when it answers at once; null when it answers a promise.
+  function load(digest, at) {
+    const as = { before: files, vouched: digest !== null }
+    let answer
+    try {
+      answer = loadProject()
+      if (typeof answer?.then !== 'function') {
+        const loaded = answered(answer, digest, at)
+        failed = null
+        told(at, 'answered', false, as)
+        return loaded
+      }
+    } catch (error) { fail(digest, at); told(at, 'failed', false, as); throw error }
+    const id = (started += 1)
+    underWay = { id, digest, startedAt: at, as }
+    // Only the load under way is listened to: one given up answers nobody. An answer that comes once the deadline has
+    // passed gives the load up itself, when no request was there to see the deadline pass first.
+    const mine = () => {
+      if (underWay?.id !== id) return false
+      underWay = null
+      if (now() - at < loadDeadlineMs) return true
+      fail(digest, now())
+      told(at, 'given-up', true, as)
+      return false
+    }
+    Promise.resolve(answer).then((project) => {
+      if (!mine()) return
+      answered(project, digest, at)
+      // While a file vouches for nothing, nothing can be kept from this answer, and no request is here to be decided by it.
+      if (digestOf(files) === null) { fail(null, now()); told(at, 'failed', true, as) } else { failed = null; told(at, 'answered', true, as) }
+    }, () => { if (mine()) { fail(digest, now()); told(at, 'failed', true, as) } }).catch(() => { fail(digest, now()); told(at, 'failed', true, as) })
+    return null
+  }
+
+  // The project as it is now, or null while that is not known.
+  function current() {
+    const at = now()
+    const digest = files === null ? null : digestOf(files)
+    if (kept !== null && (digest !== kept.digest || at - kept.since >= keepForMs)) kept = null
+    if (underWay !== null && at - underWay.startedAt >= loadDeadlineMs) { const given = underWay; underWay = null; fail(given.digest, at); told(given.startedAt, 'given-up', true, given.as) }
+    if (kept !== null && at - kept.since < keepForMs / 2) return kept
+    if (underWay === null && !tooSoon(digest, at)) {
+      const loaded = load(digest, at)
+      if (loaded !== null) return loaded
+    }
+    return kept
+  }
+
+  return function permits(scopeId) {
+    try {
+      const known = current()
+      if (known === null || !known.views.has(scopeId)) return false
+      const workspace = resolveWorkspace(known.project)
+      return workspace?.workspaceId === workspaceId && workspace.workspaceRoot === workspaceRoot
+    } catch { return false }
+  }
+}

package/src/server/local-sidecar.mjs

@@ -25,6 +25,7 @@ import {
   trustedMutationRequest,
   trustedReadRequest,
 } from './security.mjs'
+import { canonicalize } from '../attestation/jcs.mjs'
 import { createProposalStore } from '../collaboration/proposals.mjs'
 import {
   renderProposalDetailPageHtml,
@@ -34,6 +35,9 @@ import {
 import { createReviewStore } from '../collaboration/review-store.mjs'
 import { loadBoundRun, currentRunEligibility } from '../readiness-protocols/evidence.mjs'
 import { renderReviewPage } from '../ui/review-page.mjs'
+import { renderKnowledgePage } from '../ui/knowledge-page.mjs'
+import { knowledgeDashboard, knowledgeQuestionContext, loadKnowledgeWorkspace } from '../knowledge/workspace.mjs'
+import { createKnowledgeSessions } from '../knowledge/sessions.mjs'
 
 export const ATELIER_CONTEXT_SCHEMA = 'atelier-context@v1'
 export const ATELIER_PRESENCE_SCHEMA = 'atelier-presence@v1'
@@ -216,6 +220,28 @@ function listenFailure(error, port) {
   return error
 }
 
+function knowledgeError(error) {
+  const message = error instanceof Error ? error.message : ''
+  if (message === 'coauthor requires a Git workspace with untracked, ignored .atelier-local/ state')
+    return 'coauthor requires a Git workspace with untracked, ignored local state. Initialize Git and ignore the .atelier-local directory.'
+  if (/^collaboration (ledger|event).*ceiling/.test(message))
+    return 'knowledge history capacity reached. Preserve the ledger and saved values for operator inspection; do not compact active session chains.'
+  if (message.startsWith('EEXIST: private state is locked'))
+    return 'knowledge writer is busy. Preserve the request and retry after the active writer finishes.'
+  const safe = [
+    'workspace changed', 'stale revision', 'event id conflict', 'source changed',
+    'coauthor session not found', 'coauthor requires', 'unknown knowledge',
+    'invalid knowledge', 'request UUID', 'retry budget exhausted',
+    'receipt and failure events are store-owned', 'event refused in',
+    'coauthor plan must', 'knowledge session configuration mismatch',
+    'knowledge session identity mismatch', 'knowledge session exceeds',
+    'knowledge session list exceeds',
+    'knowledge history unavailable', 'knowledge start marker mismatch',
+  ]
+  return safe.some(prefix => message.startsWith(prefix)) && !message.includes('/')
+    ? message : 'Knowledge operation unavailable. Preserve your draft and inspect the local workspace or active writer.'
+}
+
 function doctorEnvelope() {
   return {
     ok: true,
@@ -231,6 +257,7 @@ export function createAtelierSidecarServer({
   workspaceRoot = process.cwd(),
   stateDir = workspaceRoot,
   reviewProject = null,
+  knowledgeProject = null,
   port = 0,
   presenceTtlMs = Number(process.env.ATELIER_PRESENCE_TTL_MS || 5 * 60 * 1000),
 } = {}) {
@@ -243,6 +270,7 @@ export function createAtelierSidecarServer({
   })
   const publication = loadPublishedWorkspaceManifest(root)
   const review = reviewProject ? createReviewStore(reviewProject) : null
+  const knowledge = knowledgeProject ? createKnowledgeSessions(knowledgeProject) : null
   const workspaceId = workspaceIdForRoot(root)
   const noncePath = path.join(stateDirReal, '.atelier-nonce')
   const presencePath = path.join(stateDirReal, '.atelier-presence.json')
@@ -253,6 +281,95 @@ export function createAtelierSidecarServer({
     workspaceId,
   })
 
+  // One copy-only declaration is retained from the workshop: this path, this
+  // action, from this view. The request stays `{ sessionId }`; everything
+  // retained is derived here from fresh owning readbacks, and the generic
+  // /api/proposals route keeps its published-HTML fence.
+  const WORKSHOP_HANDOFF_TARGET = Object.freeze({ path: 'records/checklist.md', action: 'copy.repoPath', viewId: 'knowledge-workshop' })
+  const sameJson = (left, right) => canonicalize(left) === canonicalize(right)
+  const refusedRetention = (error, status = 'refused') => ({ status: 409, body: { ok: false, error, retention: { status } } })
+  const retentionSummary = (record, outcome, sourceCurrent) => ({
+    status: 'retained',
+    outcome,
+    sourceCurrent,
+    proposalId: record.proposal.id,
+    readback: `/api/proposals/${record.proposal.id}`,
+    receipt: {
+      sessionId: record.retention.sessionId,
+      requestId: record.retention.requestId,
+      valueDigest: record.retention.valueDigest,
+    },
+    payloadDigest: record.retention.payloadDigest,
+    proposalStatus: record.proposal.status,
+    eventVersion: record.proposal.eventVersion,
+  })
+
+  function retainWorkshopHandoff(body) {
+    if (!body || Array.isArray(body) || Object.keys(body).join(',') !== 'sessionId' || typeof body.sessionId !== 'string') {
+      return refusedRetention('workshop handoff accepts a session id only')
+    }
+    // A fresh owning readback: this throws when the session, its ledger or a
+    // saved value is missing, redirected or altered.
+    const session = knowledge.read(body.sessionId)
+    const selected = session.record.flow === 'workshop-review'
+      ? session.state.saved.find((value) => value.fieldId === 'authored-revision')
+      : null
+    if (!selected) {
+      // No separately selected draft receipt: prepared only, as before. An
+      // incomplete Review or a response that selects nothing is refused by
+      // the existing preparation.
+      return { status: 200, body: { ...knowledge.workshopHandoff(body), retention: { status: 'not-retained', reason: 'no separately selected draft receipt' } } }
+    }
+    const own = session.owningReadbacks?.verified === true
+      ? session.owningReadbacks.immutableValues.find((value) => sameJson(value.receipt, selected.receipt))
+      : null
+    if (!own || own.text !== selected.text || selected.receipt.sessionId !== session.record.id) {
+      return refusedRetention('the selected draft receipt is not confirmed by its owning readback')
+    }
+    if (!session.current) {
+      // Reopen after a source change: read back what was retained, never append.
+      const known = proposals.lookupRetainedProposal(selected.receipt)
+      if (known.outcome === 'retained') {
+        return {
+          status: 200,
+          body: {
+            ok: true,
+            handoff: proposals.retainedHandoff(known.record),
+            sourceEditsApplied: false,
+            directWrite: false,
+            retention: retentionSummary(known.record, 'existing', false),
+          },
+        }
+      }
+      return known.outcome === 'not-found'
+        ? refusedRetention('the source changed before this draft was retained; nothing is retained for this receipt', 'not-retained')
+        : refusedRetention(known.error, known.outcome === 'conflict' ? 'refused' : 'unknown')
+    }
+    const prepared = knowledge.workshopHandoff(body)
+    const handoff = prepared.handoff
+    if (
+      !sameJson(handoff.proposal.selectedDraftReceipt, selected.receipt) || handoff.sessionId !== session.record.id ||
+      handoff.path !== WORKSHOP_HANDOFF_TARGET.path || handoff.action !== WORKSHOP_HANDOFF_TARGET.action ||
+      handoff.viewId !== WORKSHOP_HANDOFF_TARGET.viewId || handoff.directWrite !== false ||
+      handoff.applyEndpoint !== null || handoff.diff?.replacement !== selected.text
+    ) {
+      return refusedRetention('the prepared handoff does not match the selected draft readback')
+    }
+    // The original contribution is read back from its own session as well.
+    const original = knowledge.read(handoff.proposal.contributionSessionId)
+    const values = original.owningReadbacks?.verified === true ? original.owningReadbacks.immutableValues : null
+    if (
+      !values ||
+      !sameJson([...values.map((value) => value.receipt), selected.receipt], handoff.proposal.savedDraftReceipts) ||
+      values.find((value) => value.receipt.fieldId === 'original-words')?.text !== handoff.proposal.originalWords
+    ) {
+      return refusedRetention('the original contribution is not confirmed by its owning readback')
+    }
+    const result = proposals.retainProposal(handoff)
+    if (!result.ok) return refusedRetention(result.error, result.outcome === 'unknown' ? 'unknown' : 'refused')
+    return { status: 200, body: { ...prepared, retention: retentionSummary(result.record, result.outcome, true) } }
+  }
+
   function resolvePublishedPath({ rel, requireFile = false, requireHtml = false } = {}) {
     const resolved = resolveWorkspacePath({
       workspaceRoot: root,
@@ -395,8 +512,8 @@ export function createAtelierSidecarServer({
     // Browsers send Origin on POST; same-origin GET normally omits it. Keep
     // the strict origin gate for nonce disclosure instead of relaxing the
     // existing session-auth GET contract or accepting unclassified reads.
-    if (review && url.pathname === '/api/review/session') {
-      if (!trustedMutationRequest(req.headers) || !body || Array.isArray(body) || Object.keys(body).length) {
+    if ((review && url.pathname === '/api/review/session') || (knowledge && url.pathname === '/api/knowledge/session')) {
+      if (!trustedMutationRequest(req.headers) || !body || Array.isArray(body) || Object.keys(body).length || (url.pathname === '/api/knowledge/session' && url.search)) {
         json(res, 403, { ok: false, error: 'review session requires a same-origin empty request' })
         return
       }
@@ -411,6 +528,22 @@ export function createAtelierSidecarServer({
       return
     }
 
+    if (knowledge && url.pathname.startsWith('/api/knowledge/')) {
+      const operation = url.pathname.slice('/api/knowledge/'.length)
+      if (!['start', 'event', 'recover', 'lookup', 'workshop-handoff', 'workshop-review'].includes(operation) || url.search) {
+        json(res, 404, { ok: false, error: 'unknown knowledge action' }); return
+      }
+      try {
+        if (operation === 'workshop-handoff') {
+          const retained = retainWorkshopHandoff(body)
+          json(res, retained.status, retained.body)
+        } else {
+          json(res, 200, knowledge[operation === 'workshop-review' ? 'workshopReview' : operation](body))
+        }
+      } catch (error) { json(res, 409, { ok: false, error: knowledgeError(error) }) }
+      return
+    }
+
     if (review && url.pathname === '/api/review/contributions') {
       const result = review.contribute(body)
       json(res, result.status, result)
@@ -528,6 +661,38 @@ export function createAtelierSidecarServer({
       return
     }
 
+    if (knowledge && url.pathname === '/knowledge' && !url.search) {
+      const body = renderKnowledgePage()
+      res.writeHead(200, htmlDocumentHeaders(Buffer.byteLength(body)))
+      res.end(body)
+      return
+    }
+    if (knowledge && url.pathname.startsWith('/api/knowledge/')) {
+      try {
+        let result
+        const operation = url.pathname.slice('/api/knowledge/'.length)
+        const parameters = operation === 'context' ? ['id', 'mode'] : operation === 'read' ? ['id'] : []
+        if ([...url.searchParams.keys()].some(k => !parameters.includes(k)) || [...url.searchParams.keys()].length !== new Set(url.searchParams.keys()).size) throw new Error('invalid knowledge query')
+        if (operation === 'dashboard') {
+          const dashboard = knowledgeDashboard(loadKnowledgeWorkspace(knowledgeProject))
+          try {
+            const profile = knowledge.workshopProfile()
+            dashboard.flows = [profile.flow, ...dashboard.flows]
+            dashboard.workshop = { available: true, context: profile.context }
+          } catch {
+            dashboard.workshop = { available: false, reason: 'No current actionable public workshop finding.' }
+          }
+          result = { dashboard }
+        }
+        else if (operation === 'context') result = { context: knowledgeQuestionContext(loadKnowledgeWorkspace(knowledgeProject), url.searchParams.get('id'), url.searchParams.get('mode') || 'graph') }
+        else if (operation === 'sessions') result = knowledge.list()
+        else if (operation === 'read') result = knowledge.read(url.searchParams.get('id'))
+        else { json(res, 404, { ok: false, error: 'unknown knowledge action' }); return }
+        json(res, 200, { ok: true, ...result })
+      } catch (error) { json(res, 409, { ok: false, error: knowledgeError(error) }) }
+      return
+    }
+
     if (review && url.pathname === '/review') {
       const body = renderReviewPage()
       res.writeHead(200, htmlDocumentHeaders(Buffer.byteLength(body)))
@@ -626,6 +791,8 @@ export function createAtelierSidecarServer({
         proposal: record.proposal,
         diff: record.diff,
         copyable: record.copyable,
+        // A retained workshop handoff is read back whole; other proposals are unchanged.
+        ...(record.retention ? { payload: record.payload, retention: record.retention } : {}),
       } : { ok: false, error: result.error, diagnostics: result.diagnostics })
       return
     }

package/src/server/server.mjs

@@ -1,6 +1,27 @@
+import fs from 'node:fs'
+import path from 'node:path'
 import { AtelierDiagnosticError, resolveProjectConfig } from '../project/config.mjs'
 import { createAtelierSidecarServer } from './local-sidecar.mjs'
 
+// dev serves what build wrote and builds nothing itself. Before build, the
+// output folder (or, after graph alone, its manifest) is absent, and the
+// sidecar failed with a raw ENOENT carrying an absolute path or a redacted
+// internal error. Name the missing steps instead, and name the folder only
+// relative to the project config. A non-directory is left to the sidecar.
+function assertProjectionBuilt(project) {
+  const stat = fs.statSync(project.outputRoot, { throwIfNoEntry: false })
+  if (stat && !stat.isDirectory()) return
+  const manifestMissing = stat && !fs.existsSync(path.join(project.outputRoot, 'atelier.manifest.json'))
+  if (stat && !manifestMissing) return
+  const rel = path.relative(project.configDir, project.outputRoot)
+  const contained = rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)
+  const folder = contained ? `projection output folder ${rel}` : 'the projection output folder'
+  const state = manifestMissing ? 'has no atelier.manifest.json' : 'does not exist'
+  throw new AtelierDiagnosticError('projection-output-missing', `${folder} ${state}; this project has not been built yet`, {
+    hint: 'Run atelier graph, then atelier build, with the same --project path, then retry.',
+  })
+}
+
 function parseServerArgs(argv = []) {
   const args = { projectArgs: [] }
   for (const arg of argv) {
@@ -30,11 +51,16 @@ function resolvePort(args, env = process.env) {
 export async function runServerCommand(argv = process.argv.slice(2)) {
   const args = parseServerArgs(argv)
   const project = resolveProjectConfig({ argv: args.projectArgs })
+  // An unusable --port or PORT is refused before the project's build state,
+  // so a mistyped argument is named even in a project not built yet.
+  const port = args.smoke ? 0 : resolvePort(args)
+  assertProjectionBuilt(project)
   const sidecar = createAtelierSidecarServer({
     workspaceRoot: project.outputRoot,
     stateDir: project.outputRoot,
     reviewProject: argv.includes('--review') ? project : null,
-    port: args.smoke ? 0 : resolvePort(args),
+    knowledgeProject: argv.includes('--knowledge') ? project : null,
+    port,
   })
 
   if (args.smoke) {
@@ -53,5 +79,5 @@ export async function runServerCommand(argv = process.argv.slice(2)) {
   }
 
   const address = await sidecar.listen()
-  console.log(`MNSTRY Atelier listening on http://127.0.0.1:${address.port}/`)
+  console.log(`MNSTRY Atelier listening on http://127.0.0.1:${address.port}/${argv.includes('--knowledge') ? 'knowledge' : ''}`)
 }