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

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' : ''}`)
 }

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'])
+  }
+}

package/src/templates/profile.mjs

@@ -0,0 +1,225 @@
+import fs from 'node:fs'
+import { createHash } from 'node:crypto'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs'
+import { validateDecisionRequest, validateDecisionResult } from '../decisions/contracts.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-template-profile.v1.schema.json', import.meta.url), 'utf8'))
+const shapes = Object.fromEntries(Object.keys(schema.$defs).map(kind => [kind, {
+  $schema: schema.$schema, $defs: schema.$defs, $ref: `#/$defs/${kind}`,
+}]))
+const forbidden = new Set(['__proto__', 'prototype', 'constructor'])
+const referenceKinds = new Set(Object.keys(schema.$defs).filter(kind => kind.endsWith('Ref')))
+
+// Inspect descriptors before traversing untrusted values; no getters or toJSON.
+// All public entry points snapshot once before relational or hash checks.
+function snapshot(input) {
+  const ancestors = new Set()
+  let nodes = 0, bytes = 0
+  function copy(value, depth) {
+    if (++nodes > 20000 || depth > 24) throw new TypeError('template input limit')
+    if (value === null || typeof value === 'boolean' || typeof value === 'string' || typeof value === 'number' && Number.isFinite(value)) {
+      if (typeof value === 'string' && value.length > 1048576) throw new TypeError('template input limit')
+      bytes += Buffer.byteLength(JSON.stringify(value))
+      if (bytes > 1048576) throw new TypeError('template input limit')
+      return value
+    }
+    if (!value || typeof value !== 'object' || ancestors.has(value)) throw new TypeError('template input is not JSON')
+    const array = Array.isArray(value), proto = Object.getPrototypeOf(value)
+    if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) throw new TypeError('template input prototype')
+    const descriptors = Object.getOwnPropertyDescriptors(value), keys = Reflect.ownKeys(descriptors)
+    if (keys.some(key => typeof key !== 'string' || forbidden.has(key))) throw new TypeError('template input key')
+    ancestors.add(value)
+    const result = array ? [] : {}
+    if (array && (descriptors.length.value > 20000 || keys.length !== descriptors.length.value + 1)) throw new TypeError('template array shape')
+    for (const key of keys) {
+      if (array && key === 'length') continue
+      const d = descriptors[key]
+      if (!Object.hasOwn(d, 'value') || !d.enumerable || array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new TypeError('template input descriptor')
+      bytes += Buffer.byteLength(key) + 4
+      if (bytes > 1048576) throw new TypeError('template input limit')
+      result[key] = copy(d.value, depth + 1)
+    }
+    if (array && result.length !== descriptors.length.value) throw new TypeError('template sparse array')
+    ancestors.delete(value)
+    return result
+  }
+  return copy(input, 0)
+}
+
+function shape(kind, value, errors) {
+  const invalid = validateJsonSchema(shapes[kind], value).length > 0
+  if (invalid) errors.push(`invalid ${kind} shape`)
+  return !invalid
+}
+function same(a, b) { return canonicalize(a) === canonicalize(b) }
+function unique(items, key, errors, label) {
+  if (new Set(items.map(key)).size !== items.length) errors.push(`duplicate ${label}`)
+}
+function refFor(kind, id, version, document) {
+  if (!referenceKinds.has(kind)) throw new TypeError('unsupported reference kind')
+  const domain = { schema: 'atelier-template-digest@v1', kind, id, version, document }
+  const digest = `sha256:${createHash('sha256').update(canonicalize(domain)).digest('hex')}`
+  const ref = { kind, id, version, digest }
+  if (validateJsonSchema(shapes[kind], ref).length) throw new TypeError('invalid reference identity')
+  return ref
+}
+
+/** Content identity only; neither signature verification nor owner acceptance. */
+export function templateReference(kind, id, version, document) {
+  const value = snapshot({ kind, id, version, document })
+  return refFor(value.kind, value.id, value.version, value.document)
+}
+
+function run(stage, input, inspect) {
+  const errors = [], diagnostics = []
+  try { inspect(snapshot(input), errors, diagnostics) }
+  catch { errors.push('expected bounded plain JSON and supported reference identity') }
+  return { ok: errors.length === 0, stage, errors: [...new Set(errors)], diagnostics,
+    authority: 'structural-only', executionAuthority: false, publicationAuthority: false }
+}
+
+function definition(value, errors) {
+  if (!shape('definition', value, errors)) return false
+  unique(value.semanticRoles, x => x.id, errors, 'semantic role')
+  unique(value.surfaceRoles, x => x.id, errors, 'surface role')
+  unique(value.carriers, x => x.id, errors, 'carrier')
+  unique(value.extensions, x => x.namespace, errors, 'extension namespace')
+  unique(value.optionalDecisions, x => x.id, errors, 'optional decision')
+  unique(value.compatibility.packRefs, x => x.id, errors, 'pack identity')
+  const roles = new Set(value.semanticRoles.map(x => x.id))
+  for (const view of value.surfaceRoles) {
+    if (view.semanticRoleRefs.some(id => !roles.has(id))) errors.push('dangling surface semantic role')
+  }
+  // No extension handlers are registered by this additive profile. Optional
+  // opaque payloads remain inert. Required semantics cannot be silently ignored.
+  if (value.extensions.some(x => x.required)) errors.push('required extension unsupported')
+  return errors.length === 0
+}
+
+export function validateTemplateDefinition(input) {
+  return run('definition', input, (value, errors) => definition(value, errors))
+}
+
+function inventory(records, errors) {
+  const entries = new Map(), identities = new Set()
+  if (!Array.isArray(records) || records.length > 256) {
+    errors.push('invalid reference inventory'); return entries
+  }
+  for (const record of records) {
+    if (!shape('record', record, errors)) continue
+    const { ref, document } = record
+    const key = canonicalize(ref), identity = canonicalize([ref.kind, ref.id, ref.version])
+    if (identities.has(identity)) errors.push('ambiguous reference inventory')
+    identities.add(identity)
+    if (!same(ref, refFor(ref.kind, ref.id, ref.version, document))) errors.push('reference digest mismatch')
+    entries.set(key, document)
+  }
+  return entries
+}
+function resolve(ref, entries, errors) {
+  const key = canonicalize(ref)
+  if (!entries.has(key)) errors.push('dangling exact reference')
+  return entries.get(key)
+}
+function extensions(value, entries, errors) {
+  for (const entry of value.extensions) {
+    resolve(entry.schemaRef, entries, errors)
+    resolve(entry.payloadRef, entries, errors)
+  }
+}
+function binding(profile, value, entries, errors) {
+  if (!shape('binding', value, errors)) return false
+  if (!same(value.templateRef, refFor('TemplateRef', profile.id, profile.version, profile))) errors.push('template binding mismatch')
+  unique(value.roles, x => x.roleRef, errors, 'role binding')
+  const roles = new Map(profile.semanticRoles.map(x => [x.id, x]))
+  for (const entry of value.roles) {
+    const role = roles.get(entry.roleRef)
+    if (!role) errors.push('unknown semantic role')
+    if (role?.cardinality === 'one' && entry.sourceRefs.length !== 1) errors.push('plural singular role binding')
+    for (const ref of entry.sourceRefs) resolve(ref, entries, errors)
+  }
+  for (const role of profile.semanticRoles) {
+    if (role.required && !value.roles.some(x => x.roleRef === role.id)) errors.push('required semantic role unbound')
+  }
+  extensions(profile, entries, errors)
+  return errors.length === 0
+}
+
+export function validateTemplateBinding(profile, projectBinding, records = []) {
+  return run('binding', { profile, projectBinding, records }, (value, errors) => {
+    if (!definition(value.profile, errors)) return
+    binding(value.profile, value.projectBinding, inventory(value.records, errors), errors)
+  })
+}
+
+export function validateTemplateRelease(profile, projectBinding, release, records = []) {
+  return run('release', { profile, projectBinding, release, records }, (value, errors) => {
+    if (!definition(value.profile, errors) || !shape('release', value.release, errors)) return
+    const entries = inventory(value.records, errors)
+    if (!binding(value.profile, value.projectBinding, entries, errors)) return
+    const templateRef = refFor('TemplateRef', value.profile.id, value.profile.version, value.profile)
+    const bindingRef = refFor('BindingRef', value.projectBinding.id, value.projectBinding.version, value.projectBinding)
+    if (!same(value.release.templateRef, templateRef) || !same(value.release.bindingRef, bindingRef)) errors.push('release binding mismatch')
+    const carriers = new Set(), sources = new Set(value.projectBinding.roles.flatMap(x => x.sourceRefs.map(canonicalize)))
+    for (const ref of value.release.projectionRefs) {
+      const projection = resolve(ref, entries, errors)
+      if (!shape('projection', projection, errors)) continue
+      if (projection.id !== ref.id || projection.version !== ref.version) errors.push('projection identity mismatch')
+      if (!same(projection.templateRef, templateRef) || !same(projection.bindingRef, bindingRef)) errors.push('projection binding mismatch')
+      if (carriers.has(projection.carrier)) errors.push('duplicate projection carrier')
+      carriers.add(projection.carrier)
+      if (!value.profile.carriers.some(x => x.id === projection.carrier)) errors.push('undeclared projection carrier')
+      for (const source of projection.sourceRefs) {
+        if (!sources.has(canonicalize(source))) errors.push('projection source outside project binding')
+        resolve(source, entries, errors)
+      }
+      for (const item of [...projection.policyRefs, ...projection.authorityDecisionRefs, projection.payloadRef, projection.capabilityRef]) resolve(item, entries, errors)
+    }
+    for (const carrier of value.profile.carriers) {
+      if (carrier.required && !carriers.has(carrier.id)) errors.push('required carrier missing')
+    }
+  })
+}
+
+/** Host declarations are structural observations, never runtime grants. */
+export function validateTemplateHost(profile, host) {
+  return run('host', { profile, host }, (value, errors, diagnostics) => {
+    if (!definition(value.profile, errors) || !shape('host', value.host, errors)) return
+    const { profile: p, host: h } = value
+    if (!same(h.templateRef, refFor('TemplateRef', p.id, p.version, p))) errors.push('host template mismatch')
+    if (!p.carriers.some(x => x.id === h.carrier)) errors.push('undeclared host carrier')
+    if (!p.compatibility.atelierVersions.includes(h.atelierVersion)) errors.push('incompatible host version')
+    unique(h.packRefs, x => x.id, errors, 'host pack')
+    for (const pack of p.compatibility.packRefs) {
+      if (!h.packRefs.some(x => same(x, pack))) errors.push('required exact pack unavailable')
+    }
+    for (const role of p.semanticRoles) if (!h.semanticPrimitives.includes(role.primitive)) {
+      if (role.required) errors.push('unsupported semantic primitive')
+      else diagnostics.push({ kind: 'semantic-role', id: role.id, status: 'unsupported', bindingAllowed: false })
+    }
+    for (const role of p.surfaceRoles) if (!h.surfacePrimitives.includes(role.primitive)) errors.push('unsupported surface primitive')
+    if (!same(p.runtimeProfileRef, h.runtimeProfileRef)) errors.push('runtime profile missing or mismatched')
+    unique(h.optionalDecisions, x => x.id, errors, 'host decision')
+    for (const observation of h.optionalDecisions) {
+      if (!p.optionalDecisions.some(x => x.id === observation.id)) errors.push('undeclared optional decision')
+      if (observation.status === 'available' && observation.capabilityRef === null) errors.push('available decision needs exact capability reference')
+      if (observation.status === 'absent' && observation.capabilityRef !== null) errors.push('absent decision cannot claim a capability reference')
+    }
+    for (const request of p.optionalDecisions) {
+      const status = h.optionalDecisions.find(x => x.id === request.id)?.status ?? 'absent'
+      diagnostics.push({ id: request.id, status, fallback: 'deterministic-or-manual', invocationAuthorized: false })
+    }
+  })
+}
+
+/** Reuse provider-neutral decision semantics; never select or invoke a provider. */
+export function validateTemplateDecision(profile, decisionId, request, result) {
+  return run('advisory-decision', { profile, decisionId, request, result }, (value, errors) => {
+    if (!definition(value.profile, errors)) return
+    if (!value.profile.optionalDecisions.some(x => x.id === value.decisionId)) errors.push('undeclared optional decision')
+    if (value.request?.task !== value.decisionId) errors.push('decision task binding mismatch')
+    if (!validateDecisionRequest(value.request).ok) errors.push('invalid decision request')
+    else if (!validateDecisionResult(value.request, value.result).ok) errors.push('invalid decision result')
+  })
+}