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

package/src/knowledge/sessions.mjs

@@ -0,0 +1,467 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { createCoauthorStore } from '../coauthor/store.mjs'
+import {
+  ensureContainedPrivateDirectory,
+  openRegularFileNoFollow,
+} from '../project/private-state.mjs'
+import {
+  publishPrivateFile,
+  withPrivateLock,
+} from '../project/durable-state.mjs'
+import { digest } from './plan.mjs'
+import {
+  KNOWLEDGE_FLOWS,
+  knowledgeQuestionContext,
+  loadKnowledgeWorkspace,
+} from './workspace.mjs'
+
+import { publicWorkshopProfile, publicWorkshopReviewProfile, validatePublicWorkshopEvent, preparePublicWorkshopHandoff, PUBLIC_PARTICIPANT_PROFILE } from '../knowledge-health/workshop-profile.mjs'
+
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
+const identifier =
+  /^kg-[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
+const shape = (value, keys) => {
+  if (
+    !value ||
+    Array.isArray(value) ||
+    typeof value !== 'object' ||
+    Object.keys(value).some((k) => !keys.includes(k)) ||
+    keys.some((k) => !Object.hasOwn(value, k))
+  )
+    throw new Error('invalid knowledge request fields')
+}
+function readDescriptor(file) {
+  const fd = openRegularFileNoFollow(file)
+  try {
+    if (fs.fstatSync(fd).size > 1024 * 1024)
+      throw new Error('knowledge session exceeds byte limit')
+    const value = JSON.parse(
+      new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd))
+    )
+    shape(value, ['record', 'sha256'])
+    if (
+      digest(canonicalize(value.record)) !== value.sha256 ||
+      value.record.schema !== 'atelier-knowledge-session/experimental-v1'
+    )
+      throw new Error('invalid knowledge session record')
+    return value.record
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+// The descriptor preserves the prompts and the evidence shown at session start.
+// Accepted intents and draft receipts live only in the existing coauthor ledger.
+// None of these records are canonical plan edits or authenticated decisions.
+export function createKnowledgeSessions(
+  initial,
+  planName = 'knowledge-plan.json'
+) {
+  const root = fs.realpathSync(initial.configDir)
+  const location = path.join(root, '.atelier-local', 'knowledge', 'sessions')
+  const store = () => createCoauthorStore({ workspaceRoot: root })
+  const directory = () =>
+    ensureContainedPrivateDirectory({
+      workspaceRoot: root,
+      directory: location,
+      label: 'knowledge sessions',
+    })
+  function descriptor(id) {
+    if (typeof id === 'string') id = id.toLowerCase()
+    if (!identifier.test(id)) throw new Error('invalid knowledge session id')
+    const record = readDescriptor(path.join(directory(), `${id}.json`))
+    if (record.id !== id) throw new Error('knowledge session identity mismatch')
+    return record
+  }
+  const exists = (file) => {
+    try {
+      fs.lstatSync(file)
+      return true
+    } catch (error) {
+      if (error.code === 'ENOENT') return false
+      throw error
+    }
+  }
+  const completionFile = (record) =>
+    path.join(directory(), `${record.id}.started.json`)
+  function canResumeStart(record) {
+    if (
+      record.startProtocol !== 'completion-marker-v1' ||
+      exists(completionFile(record)) ||
+      exists(
+        path.join(root, '.atelier-local/coauthor/values', digest(record.id))
+      )
+    )
+      return false
+    // A missing ledger is not evidence that this is a never-completed start.
+    // Legacy descriptors without a completion protocol require inspection too.
+    try {
+      const fd = openRegularFileNoFollow(
+        path.join(root, '.atelier-local/coauthor/events.ndjson')
+      )
+      fs.closeSync(fd)
+      return true
+    } catch {
+      return false
+    }
+  }
+  function assertState(record, state) {
+    if (
+      state.id !== record.id ||
+      canonicalize(state.fields) !== canonicalize(record.config.fields)
+    )
+      throw new Error('knowledge session configuration mismatch')
+  }
+  function markStarted(record, state) {
+    assertState(record, state)
+    const file = completionFile(record)
+    const bytes = canonicalize({
+      schema: 'atelier-knowledge-start-completed/experimental-v1',
+      sessionId: record.id,
+      descriptorSha256: digest(canonicalize(record)),
+    })
+    let fd
+    try {
+      fd = openRegularFileNoFollow(file)
+      if (
+        fs.fstatSync(fd).size > 1024 ||
+        !fs.readFileSync(fd).equals(Buffer.from(bytes))
+      )
+        throw new Error(
+          'knowledge start marker mismatch; preserve history for inspection'
+        )
+      return
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error
+    } finally {
+      if (fd !== undefined) fs.closeSync(fd)
+    }
+    publishPrivateFile(file, bytes)
+  }
+  function resumeStart(record, adapter, newIntent = false) {
+    let state
+    try {
+      state = adapter.read(record.id)
+      assertState(record, state)
+    } catch (error) {
+      if (error.message !== 'coauthor session not found') throw error
+      if (
+        exists(completionFile(record)) ||
+        exists(
+          path.join(root, '.atelier-local/coauthor/values', digest(record.id))
+        ) ||
+        (!newIntent && !canResumeStart(record))
+      )
+        throw new Error(
+          'knowledge history unavailable; preserve the ledger, markers, and values for inspection'
+        )
+    }
+    // An existing history is only read; never call start again to reconstruct it.
+    if (!state) state = adapter.start(record.config)
+    markStarted(record, state)
+    return result(record, state)
+  }
+  function currency(record, cache = new Map()) {
+    try {
+      const ref = ['workshop', 'workshop-review'].includes(record.flow) ? planName : record.config.fields[0].source.ref
+      if (!cache.has(ref)) {
+        try {
+          cache.set(ref, loadKnowledgeWorkspace(initial, ref).snapshot)
+        } catch {
+          cache.set(ref, null)
+        }
+      }
+      const snapshot = cache.get(ref)
+      return snapshot === null
+        ? 'unavailable'
+        : snapshot === record.snapshot
+        ? 'current'
+        : 'changed'
+    } catch {
+      return 'unavailable'
+    }
+  }
+  function result(record, state) {
+    assertState(record, state)
+    const sourceState = currency(record)
+    let owningReadbacks
+    if (record.context?.participantResponseProfile === PUBLIC_PARTICIPANT_PROFILE) {
+      const actual = store().readSavedFields(record.id)
+      if (canonicalize(actual.state) !== canonicalize(state)) throw new Error('session changed during owning readback; look up the original request')
+      owningReadbacks = { verified: true, descriptorAndLedger: { sessionId: record.id, revision: state.revision,
+        descriptorSha256: digest(canonicalize(record)) }, immutableValues: actual.values }
+    }
+    return {
+      ok: true,
+      record,
+      state,
+      current: sourceState === 'current',
+      currency: sourceState,
+      ...(owningReadbacks ? { owningReadbacks } : {}),
+      savedMeaning: 'private-draft-only',
+      sourceEditsApplied: false,
+    }
+  }
+  return {
+    workshopProfile() {
+      const workspace = loadKnowledgeWorkspace(initial, planName)
+      return { ...publicWorkshopProfile(root), snapshot: workspace.snapshot }
+    },
+    workshopReview(input) {
+      shape(input, ['requestId', 'sessionId'])
+      const parent = this.read(input.sessionId)
+      publicWorkshopReviewProfile(root, parent) // read-only before any start intent
+      return this.start({ requestId: input.requestId, flow: 'workshop-review',
+        questionId: 'workshop-readiness', snapshot: parent.record.snapshot,
+        author: parent.record.author, participantSessionId: parent.record.id })
+    },
+    workshopHandoff(input) {
+      shape(input, ['sessionId'])
+      const record = descriptor(input.sessionId)
+      return { ok: true, handoff: preparePublicWorkshopHandoff(result(record, store().read(record.id))),
+        sourceEditsApplied: false, directWrite: false }
+    },
+    lookup(input) {
+      shape(input, ['sessionId', 'eventId'])
+      if (!identifier.test(input.sessionId) || (input.eventId !== null && typeof input.eventId !== 'string'))
+        throw new Error('invalid original request lookup')
+      try {
+        const record = descriptor(input.sessionId), state = store().read(record.id)
+        const found = input.eventId === null || state.events.some(e => e.id === input.eventId)
+        return { ok: true, outcome: found ? 'observed' : 'not-found', session: result(record, state) }
+      } catch (error) {
+        // Lost descriptors or ledger custody are unknown, never absence fences.
+        // A known descriptor still permits exact missing-event lookup above.
+        return { ok: true, outcome: 'unknown', session: null }
+      }
+    },
+    start(input) {
+      shape(input, ['requestId', 'flow', 'questionId', 'snapshot', 'author', ...(input?.flow === 'workshop-review' ? ['participantSessionId'] : [])])
+      input = {
+        ...input,
+        requestId:
+          typeof input.requestId === 'string'
+            ? input.requestId.toLowerCase()
+            : input.requestId,
+      }
+      if (
+        !uuid.test(input.requestId) ||
+        typeof input.author !== 'string' ||
+        !input.author.trim() ||
+        input.author.length > 160
+      )
+        throw new Error('request UUID and locally asserted author required')
+      const adapter = store() // Verify private Git placement before any descriptor write.
+      return withPrivateLock(path.join(directory(), 'start.lock'), () => {
+        const workspace = loadKnowledgeWorkspace(initial, planName)
+        if (input.snapshot !== workspace.snapshot)
+          throw new Error(
+            'workspace changed; refresh before starting a new session'
+          )
+        const participant = input.flow === 'workshop-review' ? this.read(input.participantSessionId) : null
+        if (participant && input.author.trim() !== participant.record.author) throw new Error('Review must preserve the locally asserted participant author')
+        const workshop = input.flow === 'workshop' ? publicWorkshopProfile(root)
+          : participant ? publicWorkshopReviewProfile(root, participant) : null
+        const flow = workshop?.flow || KNOWLEDGE_FLOWS.find((f) => f.id === input.flow)
+        if (workshop && input.questionId !== 'workshop-readiness') throw new Error('workshop question required')
+        const sourceDigest = workshop?.sourceDigest || workspace.sourceDigest
+        const question = workspace.plan.questions.find(
+          (q) => q.id === input.questionId
+        )
+        if (!flow || !question)
+          throw new Error('unknown knowledge flow or question')
+        const ref = workshop?.ref || path
+          .relative(root, workspace.file)
+          .split(path.sep)
+          .join('/')
+        if (
+          !ref ||
+          ref.split('/').some((p) => !p || p.startsWith('.')) ||
+          path.isAbsolute(ref)
+        )
+          throw new Error(
+            'coauthor plan must be a visible workspace-relative file'
+          )
+        let sourcePath = root
+        for (const segment of ref.split('/')) {
+          sourcePath = path.join(sourcePath, segment)
+          if (fs.lstatSync(sourcePath).isSymbolicLink())
+            throw new Error('coauthor plan must not be redirected')
+        }
+        const id = `kg-${input.requestId}`
+        const file = path.join(directory(), `${id}.json`)
+        // A descriptor is a recoverable start intent. Keep its original prompts,
+        // evidence, timestamp, and identity on an exact retry after interruption.
+        if (fs.existsSync(file)) {
+          const record = descriptor(id)
+          if (
+            record.snapshot !== input.snapshot ||
+            record.flow !== input.flow ||
+            record.question.id !== input.questionId ||
+            record.author !== input.author.trim() ||
+            (input.flow === 'workshop-review' && record.context.participant?.sessionId !== input.participantSessionId) ||
+            record.config.fields.some(
+              (field) =>
+                field.source.ref !== ref ||
+                field.source.digest !== sourceDigest
+            )
+          )
+            throw new Error(
+              'invalid knowledge request: session id already bound'
+            )
+          return resumeStart(record, adapter)
+        }
+        const config = {
+          id,
+          fields: flow.prompts.map(([field]) => ({
+            id: field,
+            source: { ref, digest: sourceDigest },
+          })),
+        }
+        const record = {
+          schema: 'atelier-knowledge-session/experimental-v1',
+          id,
+          createdAt: new Date().toISOString(),
+          startProtocol: 'completion-marker-v1',
+          snapshot: workspace.snapshot,
+          flow: flow.id,
+          title: flow.title,
+          prompts: flow.prompts,
+          question,
+          author: input.author.trim(),
+          identity: 'locally-asserted',
+          context: workshop?.context || (workspace.graph.ok
+            ? knowledgeQuestionContext(workspace, question.id)
+            : null),
+          config,
+        }
+        const bytes = canonicalize({
+          record,
+          sha256: digest(canonicalize(record)),
+        })
+        if (Buffer.byteLength(bytes) > 1024 * 1024)
+          throw new Error('knowledge session exceeds byte limit')
+        // Non-overwriting publication makes a retry of the same request exact.
+        publishPrivateFile(file, bytes)
+        return resumeStart(record, adapter, true)
+      })
+    },
+    read(id) {
+      const record = descriptor(id)
+      return result(record, store().read(record.id))
+    },
+    list() {
+      const limit = 200
+      if (!fs.existsSync(location))
+        return { sessions: [], total: 0, limit, truncated: false }
+      const names = fs
+        .readdirSync(directory())
+        .filter((n) => identifier.test(n.slice(0, -5)) && n.endsWith('.json'))
+        .map((name) => {
+          try {
+            return {
+              name,
+              time: fs.lstatSync(path.join(location, name)).mtimeMs,
+            }
+          } catch {
+            return { name, time: 0 }
+          }
+        })
+        .sort((a, b) => b.time - a.time || a.name.localeCompare(b.name))
+      const adapter = store()
+      const cache = new Map()
+      const states = adapter.readMany(
+        names.slice(0, limit).map(({ name }) => name.slice(0, -5))
+      )
+      const sessions = names.slice(0, limit).map(({ name }) => {
+        const id = name.slice(0, -5)
+        let record
+        try {
+          record = descriptor(id)
+          const loaded = states.get(id)
+          if (!loaded.ok) throw new Error(loaded.error)
+          const state = loaded.state
+          if (canonicalize(state.fields) !== canonicalize(record.config.fields))
+            throw new Error('knowledge session configuration mismatch')
+          const sourceState = currency(record, cache)
+          return {
+            id,
+            available: true,
+            createdAt: record.createdAt || null,
+            flow: record.flow,
+            title: record.title,
+            question: record.question.question,
+            author: record.author,
+            phase: state.phase,
+            saved: state.saved.length,
+            fields: state.fields.length,
+            current: sourceState === 'current',
+            currency: sourceState,
+          }
+        } catch (error) {
+          const incomplete =
+            record &&
+            error.message === 'coauthor session not found' &&
+            canResumeStart(record)
+          const recoverable = Boolean(
+            incomplete && currency(record, cache) === 'current'
+          )
+          return {
+            id,
+            available: false,
+            recoverable,
+            reason: recoverable
+              ? 'Start incomplete. Its bound sources match; it can be resumed.'
+              : 'Session unavailable. Preserve its local files for inspection.',
+          }
+        }
+      })
+      return {
+        sessions,
+        total: names.length,
+        limit,
+        truncated: names.length > limit,
+        order: 'newest-local-descriptor-first',
+      }
+    },
+    event(input) {
+      shape(input, ['sessionId', 'event'])
+      const record = descriptor(input.sessionId)
+      if (currency(record) !== 'current')
+        throw new Error(
+          'workspace changed; retained history is readable; start a newly bound session'
+        )
+      const adapter = store()
+      // Complete the durable start marker before any guided answer can be kept.
+      // A later missing aggregate must never be mistaken for a new empty start.
+      const previous = adapter.read(record.id)
+      markStarted(record, previous)
+      if (!previous.events.some(e => e.id === input.event?.id)) validatePublicWorkshopEvent(record, previous, input.event)
+      const state = adapter.dispatch(record.id, input.event)
+      return result(record, state)
+    },
+    recover(input) {
+      shape(input, ['sessionId'])
+      const record = descriptor(input.sessionId)
+      if (currency(record) !== 'current')
+        throw new Error(
+          'workspace changed; retained history is readable; start a newly bound session'
+        )
+      const adapter = store()
+      let state
+      try {
+        state = adapter.read(record.id)
+      } catch (error) {
+        if (error.message !== 'coauthor session not found') throw error
+        return resumeStart(record, adapter)
+      }
+      markStarted(record, state)
+      return result(
+        record,
+        state.phase === 'saving' ? adapter.recover(record.id) : state
+      )
+    },
+  }
+}