@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/server/local-sidecar.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs'
 import http from 'node:http'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { AtelierDiagnosticError } from '../project/config.mjs'
 import {
   atomicReplacePrivateText,
   ensureContainedPrivateDirectory,
@@ -24,6 +25,7 @@ import {
   trustedMutationRequest,
   trustedReadRequest,
 } from './security.mjs'
+import { canonicalize } from '../attestation/jcs.mjs'
 import { createProposalStore } from '../collaboration/proposals.mjs'
 import {
   renderProposalDetailPageHtml,
@@ -33,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'
@@ -196,6 +201,47 @@ function capabilityContract() {
   }
 }
 
+// A listen failure a person can fix by choosing another port becomes a typed
+// diagnostic the CLI prints with that remedy. Any other failure is returned
+// unchanged, so the CLI's own rule for unknown errors still decides what shows.
+function listenFailure(error, port) {
+  if (error?.code === 'EADDRINUSE') {
+    return new AtelierDiagnosticError('port-in-use', `port ${port} is already in use`, {
+      hint: 'Pass --port=<free port> to choose another.',
+      cause: error,
+    })
+  }
+  if (error?.code === 'EACCES') {
+    return new AtelierDiagnosticError('port-permission-denied', `permission to listen on port ${port} was denied`, {
+      hint: 'Pass --port=<free port from 1024 to 65535> to choose another; lower ports need elevated privileges.',
+      cause: error,
+    })
+  }
+  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,
@@ -211,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),
 } = {}) {
@@ -223,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')
@@ -233,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,
@@ -375,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
       }
@@ -391,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)
@@ -508,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)))
@@ -606,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
     }
@@ -662,14 +849,13 @@ export function createAtelierSidecarServer({
       if (!isLoopbackHost(host)) {
         return Promise.reject(new Error(`non-loopback listen host refused: ${host}`))
       }
-      // A busy port is an ordinary condition, not a crash: surface it as a
-      // rejection the CLI can print, instead of an unhandled 'error' event.
+      // A busy or refused port is an ordinary condition, not a crash: surface
+      // it as a typed rejection the CLI prints with its remedy, instead of an
+      // unhandled 'error' event or a redacted internal error.
       return new Promise((resolve, reject) => {
         const onError = (error) => {
           server.removeListener('listening', onListening)
-          reject(error.code === 'EADDRINUSE'
-            ? new Error(`port ${listenPort} is already in use — pass --port=<free port> to choose another`)
-            : error)
+          reject(listenFailure(error, listenPort))
         }
         const onListening = () => {
           server.removeListener('error', onError)

package/src/server/server.mjs

@@ -1,6 +1,27 @@
-import { resolveProjectConfig } from '../project/config.mjs'
+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) {
@@ -11,17 +32,35 @@ function parseServerArgs(argv = []) {
   return args
 }
 
+// argv > PORT env > default. Supervisors that assign a free port (preview
+// panes, dev harnesses) pass it via PORT, and an Atelier that ignores that
+// fights whatever already holds the canonical port instead of coexisting.
+// A value listen would refuse is refused here, naming where it came from;
+// Node's own range error names neither the flag nor the variable.
+function resolvePort(args, env = process.env) {
+  const [source, raw] = args.port ? ['--port', args.port] : env.PORT ? ['PORT', env.PORT] : [null, '8137']
+  const port = Number(raw)
+  if (Number.isInteger(port) && port >= 0 && port <= 65535) return port
+  throw new AtelierDiagnosticError('port-invalid', `${source} must be a whole number from 0 to 65535, got ${JSON.stringify(raw)}`, {
+    hint: source === 'PORT'
+      ? 'Set PORT to a free port or unset it, or pass --port=<free port> to override it.'
+      : 'Pass a free port, for example --port=8138.',
+  })
+}
+
 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,
-    // argv > PORT env > default. Supervisors that assign a free port (preview
-    // panes, dev harnesses) pass it via PORT, and an Atelier that ignores that
-    // fights whatever already holds the canonical port instead of coexisting.
-    port: args.smoke ? 0 : Number(args.port || process.env.PORT || 8137),
+    knowledgeProject: argv.includes('--knowledge') ? project : null,
+    port,
   })
 
   if (args.smoke) {
@@ -40,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' : ''}`)
 }

package/src/template-bindings/project.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs'
+import { buildCanonicalGraph, createGraphFileCache } from '../graph/graph.mjs'
+import { projectGraph, PROJECTION_TARGETS } from '../projection/policy.mjs'
+import { renderReadOnlyDocument, validatePresentation } from '../ui/presentation/index.mjs'
+import { templateReference, validateTemplateDefinition, validateTemplateBinding, validateTemplateHost } from '../templates/profile.mjs'
+
+const packageVersion = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version
+const identity = value => templateReference('PayloadRef', 'identity', '1', value).digest.slice(7, 39)
+const outcome = (ok, errors, rest = {}) => ({ ok, errors, authority: 'structural-only', executionAuthority: false, publicationAuthority: false, conformanceClaim: 'none', ...rest })
+
+/** Read-only composition over a loaded project, not a graph or source writer.
+ * The request is bounded JSON text: {profile, projectRef, roleNodeIds, target,
+ * theme?}. This initial binding supports classified active Markdown resources,
+ * Resource bindings and CollectionView/StatusView. Other requirements
+ * refuse instead of being converted to a superficially similar surface.
+ */
+export function createTemplateProjectView(project, requestJson) {
+  try {
+    if (typeof requestJson !== 'string' || Buffer.byteLength(requestJson) > 1048576) return outcome(false, ['invalid request'])
+    const request = JSON.parse(requestJson)
+    // The profile reference validator also enforces bounded plain JSON before
+    // the request is used; no caller-supplied accessors enter this adapter.
+    templateReference('PayloadRef', 'request', '1', request)
+    if (!request || Array.isArray(request) || Object.keys(request).some(key => !['profile', 'projectRef', 'roleNodeIds', 'target', 'theme'].includes(key))) return outcome(false, ['invalid request'])
+    const { profile, projectRef, roleNodeIds, target, theme = 'light' } = request
+    const definition = validateTemplateDefinition(profile)
+    if (!definition.ok) return outcome(false, definition.errors)
+    if (!Object.hasOwn(PROJECTION_TARGETS, target)) return outcome(false, ['unknown projection target'])
+    if (!roleNodeIds || Array.isArray(roleNodeIds) || typeof roleNodeIds !== 'object') return outcome(false, ['invalid role selection'])
+    if (profile.runtimeProfileRef !== null) return outcome(false, ['runtime profile requires its owning adapter'])
+    const templateRef = templateReference('TemplateRef', profile.id, profile.version, profile)
+    const host = validateTemplateHost(profile, {
+      schema: 'atelier-template-host@v1', templateRef, carrier: 'web', atelierVersion: packageVersion,
+      packRefs: [], semanticPrimitives: ['Resource'], surfacePrimitives: ['CollectionView', 'StatusView'],
+      runtimeProfileRef: null, optionalDecisions: [],
+    })
+    if (!host.ok) return outcome(false, host.errors)
+    const cache = createGraphFileCache()
+    const graph = buildCanonicalGraph(project, { fileCache: cache })
+    if (!graph.ok) return outcome(false, ['canonical graph invalid'])
+    const projected = projectGraph(graph, { target })
+    const visible = new Map(projected.nodes.filter(node => node.classification === 'classified' && node.status === 'active').map(node => [node.id, node]))
+    const records = [], sources = new Map(), roles = []
+    for (const [roleRef, ids] of Object.entries(roleNodeIds)) {
+      if (!profile.semanticRoles.some(role => role.id === roleRef) || !Array.isArray(ids) || !ids.length || ids.length > 256 || ids.some(id => typeof id !== 'string') || new Set(ids).size !== ids.length) return outcome(false, ['invalid role selection'])
+      if (profile.semanticRoles.find(role => role.id === roleRef).primitive !== 'Resource') return outcome(false, ['semantic role has no canonical binding'])
+      const refs = []
+      for (const id of ids) {
+        const node = visible.get(id)
+        // A node's audience cannot widen its repository's read boundary.
+        if (!node || !PROJECTION_TARGETS[target].has(node.repoAccess?.readBoundary)) return outcome(false, ['selected source unavailable for this view'])
+        const source = cache.files.get(`${node.repo}\u0000${node.path}`)
+        if (!source || !/^[a-f0-9]{64}$/.test(source.digest)) return outcome(false, ['source byte pin unavailable'])
+        if (!sources.has(id)) {
+          const document = { nodeId: id, repository: node.repo, path: node.path, rawDigest: `sha256:${source.digest}`, title: node.title, summary: node.summary }
+          const ref = templateReference('SourceRef', `source.${identity(id)}`, document.rawDigest, document)
+          sources.set(id, { ref, document }); records.push({ ref, document })
+        }
+        refs.push(sources.get(id).ref)
+      }
+      roles.push({ roleRef, sourceRefs: refs })
+    }
+    const binding = { schema: 'atelier-template-binding@v1', id: `binding.${identity(projectRef)}`, version: '1.0.0', templateRef, projectRef, roles }
+    const checked = validateTemplateBinding(profile, binding, records)
+    if (!checked.ok) return outcome(false, checked.errors)
+    const bindingRef = templateReference('BindingRef', binding.id, binding.version, binding)
+    const nodes = profile.surfaceRoles.map((view, index) => {
+      const id = `view-${index}`
+      if (view.primitive === 'StatusView') return { id, type: 'status', label: view.id, text: 'Read-only local projection. Runtime actions and publication are unavailable.', tone: 'neutral', details: host.diagnostics.map(item => ({ label: item.id, value: item.kind === 'semantic-role' ? 'Optional role unsupported; binding unavailable' : `${item.status}; deterministic or manual fallback` })), actions: [] }
+      const sourceIds = [...new Set(view.semanticRoleRefs.flatMap(role => roleNodeIds[role] ?? []))]
+      return { id, type: 'collection', label: view.id, items: sourceIds.map(sourceId => ({ id: `item-${identity(sourceId)}`, label: sources.get(sourceId).document.title, detail: sources.get(sourceId).document.summary })) }
+    })
+    nodes.unshift({ id: 'description', type: 'text', label: 'Inputs and limits', text: `Inputs: ${profile.inputs.join('; ')}. Limits: ${profile.limitations.join('; ')}` })
+    nodes.push({ id: 'identity', type: 'text', label: 'Template and binding identity', text: `Template: ${templateRef.id}@${templateRef.version}; ${templateRef.digest}. Binding: ${bindingRef.id}@${bindingRef.version}; ${bindingRef.digest}. Release: none (local preview). Structural references only; not verified authorship, release acceptance or rights.` })
+    // Provenance travels with readable exports, not only the API envelope.
+    // Use opaque refs and byte pins; never expose local repository paths here.
+    for (let offset = 0; offset < records.length; offset += 128) nodes.push({
+      id: `provenance-${offset}`, type: 'collection', label: 'Source provenance',
+      items: records.slice(offset, offset + 128).map(({ ref, document }) => ({ id: `source-${identity(ref.id)}`, label: document.title, detail: `SourceRef: ${ref.id}; ${ref.digest}. Source bytes: ${document.rawDigest}.` })),
+    })
+    const model = { schema: 'atelier.presentation/v1', version: '1.0.0', id: `template-${identity(profile.id)}`, title: profile.purpose, lang: 'en', direction: 'ltr', theme, density: 'comfortable', navigation: [], panes: [{ id: 'content', label: 'Template preview', role: 'primary', blocks: nodes.map(node => node.id) }], nodes }
+    if (validatePresentation(model).length) return outcome(false, ['presentation binding invalid'])
+    // Reuse the exact same non-interactive renderer for local web and document
+    // preview. This creates bytes only; it does not publish or erase old copies.
+    const html = renderReadOnlyDocument(model)
+    const textPreview = [model.title, ...nodes.flatMap(node => [node.label, ...(node.items ? node.items.flatMap(item => [item.label, item.detail]) : [node.text]), ...(node.details ?? []).map(item => `${item.label}: ${item.value}`)])].join('\n\n')
+    return outcome(true, [], { templateRef, bindingRef, binding, records, model, html, textPreview, capabilityDiagnostics: host.diagnostics, optionalDecisions: host.diagnostics.filter(item => item.kind !== 'semantic-role'), target, lifecycle: 'active-only', artifacts: { web: html, documents: html } })
+  } catch {
+    // Do not disclose source paths or source text through exception messages.
+    return outcome(false, ['template project composition refused'])
+  }
+}