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

package/src/commands/ingest.mjs

@@ -0,0 +1,39 @@
+import { createIngestionStore } from '../ingestion/store.mjs'
+import { reportCommandFailure } from '../cli/command-failure.mjs'
+
+const commands = ['plan', 'run', 'status', 'query']
+const usage = `Usage: atelier ingest plan|run|status|query
+Read one UTF-8 JSON object from stdin, maximum 256 KiB:
+{workspaceId,input}. Run inside the intended Git workspace with untracked,
+ignored .atelier-local/ state. Plans bind explicit sources, scope and budgets.
+Run processes bounded local text, CSV and JSON. Status retains every selected
+source's disposition. Query returns source-bound lexical evidence with coverage;
+no operation accepts semantic claims, calls a provider or enrolls raw files into
+the graph. Output is private JSON. See docs/ingestion.md.`
+
+try {
+  const command = process.argv[2]
+  if (command === '--help' || command === 'help') console.log(usage)
+  else {
+    if (!commands.includes(command) || process.argv.length !== 3) throw new Error(usage)
+    const chunks = []
+    let bytes = 0
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length
+      if (bytes > 256 * 1024) throw new Error('ingestion request exceeds byte limit')
+      chunks.push(chunk)
+    }
+    let body
+    try { body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) }
+    catch { throw new Error('ingestion request must be UTF-8 JSON') }
+    if (!body || typeof body !== 'object' || Array.isArray(body)
+      || Object.keys(body).length !== 2 || !Object.hasOwn(body, 'workspaceId') || !Object.hasOwn(body, 'input')) {
+      throw new Error('invalid ingestion request fields')
+    }
+    const store = createIngestionStore({ workspaceRoot: process.cwd(), workspaceId: body.workspaceId })
+    console.log(JSON.stringify(await store[command](body.input), null, 2))
+  }
+} catch (error) {
+  // Parser exceptions above are replaced before they can echo source text.
+  reportCommandFailure(error)
+}

package/src/commands/init.mjs

@@ -101,6 +101,9 @@ if (template === 'external-project') {
   if (fs.existsSync(target)) throw new Error('external-project target must not exist; refusing overwrite or redirected destination')
   copyDir(path.join(packageRoot, 'templates/external-project-workspace'), target)
   console.log(`created external-project adapter at ${target}`)
+} else if (template === 'knowledge-workspace') {
+  copyDir(path.join(packageRoot, 'templates/knowledge-workspace'), target)
+  console.log(`created knowledge workspace at ${target}`)
 } else if (template === 'sample-workspace') {
   copyDir(path.join(packageRoot, 'fixtures/projects/sample-workspace'), target)
   console.log(`created sample Atelier workspace at ${target}`)
@@ -131,7 +134,7 @@ if (template === 'external-project') {
 } else if (template) {
   // Unknown template names fail closed: a typo must not silently produce a
   // blank scaffold that lacks the boundary policy the caller asked for.
-  console.error(`Unknown template: ${template}. Valid templates: private-domain, shared-project, sample-workspace, distribution, external-project.`)
+  console.error(`Unknown template: ${template}. Valid templates: private-domain, shared-project, sample-workspace, distribution, external-project, knowledge-workspace.`)
   process.exit(1)
 } else {
   fs.mkdirSync(target, { recursive: true })

package/src/commands/inquiry.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+import * as inquiry from '../inquiry/index.mjs'
+import { jsonAt } from '../capabilities/files.mjs'
+import { reportCommandFailure } from '../cli/command-failure.mjs'
+
+const USAGE = `Usage: atelier inquiry <command> [options]
+validate --record FILE                 Validate a single record's shape only.
+inspect --history FILE                 Replay an exported ledger, checking all references.
+append --record FILE --confirm DIGEST  Append to ignored repository campaign history.
+status --campaign ID                   Show assessments and reconsideration needs.
+handoff --campaign ID --request ID     Emit a portable research request and full prompt.
+graph --campaign ID --namespace ID     Emit draft sources and relation proposals as JSON.
+feedback --campaign ID --record ID     Prepare a version-bound Skill Steward observation.
+export --campaign ID                   Export the complete local ledger, including captures.
+example                               Print synthetic records for a complete local journey.
+lenses                                List optional conceptual inquiry methods.
+
+--workspace DIR defaults to the current repository. Output is JSON.
+The initial history digest is ${inquiry.EMPTY_INQUIRY_HEAD}.
+Append requires a Git root with ignored .atelier-local/ state on POSIX.
+Output may contain private source content; choose its destination deliberately.
+No command runs research providers, grants authority, or promotes graph changes.
+Exit codes: 0 success, 1 refusal, 2 usage error.`
+const commands = { validate: ['record'], inspect: ['history'], append: ['record', 'confirm'], status: ['campaign'], handoff: ['campaign', 'request'], graph: ['campaign', 'namespace'], feedback: ['campaign', 'record'], export: ['campaign'], example: [], lenses: [] }
+const argv = process.argv.slice(2), command = argv.shift(), options = {}
+function usage(message) { console.error(`${message}\n\n${USAGE}`); process.exit(2) }
+if (['help', '--help', '-h'].includes(command) || argv.includes('--help')) { console.log(USAGE); process.exit(0) }
+if (!Object.hasOwn(commands, command ?? '')) usage('unknown inquiry command')
+for (let i = 0; i < argv.length; i++) {
+  const key = argv[i].startsWith('--') ? argv[i].slice(2) : ''
+  if (![...commands[command], 'workspace'].includes(key) || Object.hasOwn(options, key)) usage('unknown or duplicate inquiry option')
+  const value = argv[++i]
+  if (!value || value.startsWith('--')) usage('inquiry option requires a value')
+  options[key] = value
+}
+const requireOption = key => { if (!options[key]) usage(`--${key} is required`); return options[key] }
+const read = file => { const p = path.resolve(file); return jsonAt(fs.realpathSync(path.dirname(p)), path.basename(p)) }
+try {
+  let result
+  const workspaceRoot = options.workspace ?? process.cwd()
+  if (command === 'validate') { const errors = inquiry.validateInquiryDocument(read(requireOption('record'))); result = { valid: errors.length === 0, errors, assurance: 'shape-only' }; if (errors.length) process.exitCode = 1 }
+  else if (command === 'inspect') {
+    const ledger = read(requireOption('history'))
+    const errors = inquiry.validateInquiryDocument(ledger, 'ledger')
+    if (errors.length) throw new Error('invalid inquiry ledger')
+    result = inquiry.inspectInquiry(ledger.records)
+    if (result.head !== ledger.head) throw new Error('inquiry history digest mismatch')
+  }
+  else if (command === 'append') result = inquiry.appendInquiry({ workspaceRoot, record: read(requireOption('record')), confirm: requireOption('confirm') })
+  else if (command === 'example') result = JSON.parse(fs.readFileSync(new URL('../../fixtures/inquiry/workshop.json', import.meta.url), 'utf8'))
+  else if (command === 'lenses') result = inquiry.INQUIRY_LENSES
+  else {
+    const state = inquiry.readInquiry({ workspaceRoot, campaign: requireOption('campaign') })
+    if (command === 'status') result = state
+    if (command === 'handoff') result = inquiry.researchHandoff(state.records, requireOption('request'))
+    if (command === 'graph') result = inquiry.inquiryGraphProposal(state.records, { namespace: requireOption('namespace') })
+    if (command === 'feedback') result = inquiry.inquiryStewardObservation(state.records, requireOption('record'))
+    if (command === 'export') {
+      if (!state.campaign) throw new Error('inquiry campaign does not exist')
+      result = { schema: 'atelier-inquiry-ledger@v1', records: state.records, head: state.head }
+    }
+  }
+  console.log(JSON.stringify(result, null, 2))
+} catch (error) { reportCommandFailure(error, 'stdout') }

package/src/commands/knowledge-semantic.mjs

@@ -0,0 +1,128 @@
+// `atelier knowledge semantic <operation>`: the public command surface over the
+// internal semantic operation runner (src/knowledge/semantic-operation.mjs).
+//
+// The runner checks only `begin`'s request and some nested values as closed
+// shapes; its other methods read their fields by name and ignore extras. This
+// adapter closes every request itself, before the runner is constructed, so a
+// refused request writes nothing. A valid request is passed on unchanged.
+//
+// Atelier calls no model here. The host supplies raw output, candidates and
+// usage; receiver records are caller assertions, not authentication.
+import { createSemanticOperation } from '../knowledge/semantic-operation.mjs'
+import { encodeKnowledgeOutput } from '../knowledge/context.mjs'
+import { parseArgs } from '../project/config.mjs'
+import { safeCommandMessage } from '../cli/command-failure.mjs'
+
+export const SEMANTIC_REQUEST_BYTES = 256 * 1024
+
+// Every request field has a declared kind, checked before the runner exists, so
+// a wrong kind is a typed refusal with nothing written. Formats (timestamps,
+// digests, identifiers) are the runner's to judge. Required fields are never
+// null; optional ones may be null only where the kind says so.
+const S = 'string', O = 'object', A = 'array'
+const spec = (method, types, optional = []) => Object.freeze({ method, types: Object.freeze(types),
+  required: Object.freeze(Object.keys(types).filter(field => !optional.includes(field))), optional: Object.freeze(optional) })
+export const SEMANTIC_COMMANDS = Object.freeze({
+  begin: spec('begin', { operationId: S, attemptId: S, at: S, term: S, plan: O, references: A, identityCandidates: A, extractor: O, confirm: S }),
+  status: spec('status', { operationId: S }),
+  reconcile: spec('reconcile', { operationId: S, at: S, by: S, reason: S, outcome: S, confirm: S }),
+  complete: spec('complete', { operationId: S, output: S, expectedOutputDigest: S, candidates: O, usage: O, at: S, confirm: S }),
+  proposals: spec('proposals', { operationId: S, query: S, limit: 'integer' }, ['limit']),
+  contribution: spec('prepareContribution', { operationId: S, id: S, kind: 'interpretation-kind', candidateId: S, source: O, sourceBinding: O, term: S, at: S, confirm: S,
+    supersedes: 'object-or-null', revisionReason: 'string-or-null' }, ['supersedes', 'revisionReason']),
+  relation: spec('prepareRelation', { assertion: O, at: S, confirm: S }),
+  record: spec('record', { record: O, confirm: S }),
+  cascade: spec('cascade', { withdrawalId: S, at: S, confirm: S }),
+  context: spec('context', { query: S }),
+  project: spec('project', { activationId: S, namespace: S }),
+})
+
+const USAGE = `use knowledge semantic ${Object.keys(SEMANTIC_COMMANDS).join('|')} with one JSON object on stdin; see knowledge --help`
+
+class SemanticRequestError extends Error {
+  constructor(code, message) { super(message); this.name = 'SemanticRequestError'; this.code = code }
+}
+
+const plainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const KINDS = Object.freeze({
+  string: value => typeof value === 'string',
+  object: plainObject,
+  array: Array.isArray,
+  integer: Number.isSafeInteger,
+  'object-or-null': value => value === null || plainObject(value),
+  'string-or-null': value => value === null || typeof value === 'string',
+  // The runner maps exactly these three kinds; any other, even an inherited
+  // property name, is refused here.
+  'interpretation-kind': value => value === 'entity' || value === 'assertion' || value === 'unknown',
+})
+const exactFields = (value, required, optional = []) => plainObject(value)
+  && Object.keys(value).every(key => required.includes(key) || optional.includes(key))
+  && required.every(key => Object.hasOwn(value, key))
+
+async function readRequest() {
+  const chunks = []
+  let bytes = 0
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length
+    if (bytes > SEMANTIC_REQUEST_BYTES) throw new SemanticRequestError('SEMANTIC_OPERATION_LIMIT', 'semantic request exceeds 256 KiB')
+    chunks.push(chunk)
+  }
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) }
+  catch { throw new SemanticRequestError('SEMANTIC_OPERATION_INVALID', 'semantic request must be UTF-8 JSON') }
+}
+
+// The closed envelope and the per-command field set, checked before any store is opened.
+export function selectSemanticRequest(command, body) {
+  const selected = SEMANTIC_COMMANDS[command]
+  if (!exactFields(body, ['workspaceId', 'run', 'request']) || typeof body.workspaceId !== 'string' || typeof body.run !== 'string')
+    throw new SemanticRequestError('SEMANTIC_OPERATION_INVALID', 'semantic request needs exactly workspaceId, run and request')
+  if (!exactFields(body.request, selected.required, selected.optional))
+    throw new SemanticRequestError('SEMANTIC_OPERATION_INVALID', `unknown or missing ${command} request field`)
+  for (const [field, value] of Object.entries(body.request))
+    if (!KINDS[selected.types[field]](value)) throw new SemanticRequestError('SEMANTIC_OPERATION_INVALID', `invalid ${command} request field type: ${field}`)
+  return selected
+}
+
+const TYPED = /^SEMANTIC_[A-Z_]+$/
+// The printed failure for an error, or null when it must go to the command
+// executor's redaction. Three cases:
+// - a SEMANTIC_* refusal keeps its own code;
+// - any error carrying the runner's recorded/captured detail keeps it, as
+//   SEMANTIC_OPERATION_INTERRUPTED when uncoded;
+// - Atelier's own other refusals (safe text, no host detail) become
+//   SEMANTIC_OPERATION_REFUSED.
+// Only an error with unsafe text and nothing saved is left to the executor.
+export function semanticFailure(error) {
+  const typed = typeof error?.code === 'string' && TYPED.test(error.code)
+  const saved = error?.recorded !== undefined || error?.captured !== undefined
+  const message = safeCommandMessage(error)
+  if (!typed && !saved && message === null) return null
+  const failure = { ok: false, code: typed ? error.code : saved ? 'SEMANTIC_OPERATION_INTERRUPTED' : 'SEMANTIC_OPERATION_REFUSED', error: message ?? '[internal-error]' }
+  if (error.recorded !== undefined) failure.recorded = error.recorded
+  if (error.captured !== undefined) failure.captured = error.captured
+  return failure
+}
+
+function reportSemanticFailure(error) {
+  const failure = semanticFailure(error)
+  if (failure === null) throw error
+  console.error(JSON.stringify(failure))
+  process.exitCode = 1
+}
+
+export async function runKnowledgeSemantic(argv) {
+  try {
+    const args = parseArgs(argv)
+    const command = args._[0]
+    if (args._.length !== 1 || !Object.hasOwn(SEMANTIC_COMMANDS, command) || Object.keys(args).some(key => key !== '_'))
+      throw new SemanticRequestError('SEMANTIC_OPERATION_INVALID', USAGE)
+    const body = await readRequest()
+    const selected = selectSemanticRequest(command, body)
+    // The workspace is the current directory, as for ingest and learn: the
+    // runner reads the ingestion store that `atelier ingest` writes there.
+    const runner = createSemanticOperation({ workspaceRoot: process.cwd(), workspaceId: body.workspaceId, run: body.run })
+    process.stdout.write(encodeKnowledgeOutput(runner[selected.method](body.request)))
+  } catch (error) {
+    reportSemanticFailure(error)
+  }
+}

package/src/commands/knowledge.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { commandProject, parseArgs } from '../project/config.mjs'
+import { buildCanonicalGraph, createGraphFileCache } from '../graph/graph.mjs'
+import { inspectKnowledgePlan } from '../knowledge/plan.mjs'
+import {
+  createKnowledgeContext,
+  encodeKnowledgeOutput,
+  evaluateKnowledgeQuestions,
+} from '../knowledge/context.mjs'
+import {
+  knowledgeDashboard,
+  loadKnowledgeWorkspace,
+  readKnowledgePlan,
+} from '../knowledge/workspace.mjs'
+import { createKnowledgeSessions } from '../knowledge/sessions.mjs'
+import { runKnowledgeSemantic } from './knowledge-semantic.mjs'
+
+// semantic reports its own typed failures and leaves untyped ones to the
+// command executor, so it runs outside this command's message-only catch.
+if (process.argv[2] === 'semantic') await runKnowledgeSemantic(process.argv.slice(3))
+else try {
+  const argv = process.argv.slice(2)
+  const args = parseArgs(argv)
+  const command = args._[0]
+  if (
+    !['check', 'context', 'evaluate', 'dashboard', 'session'].includes(
+      command
+    ) ||
+    args._.length !== (command === 'session' ? 2 : 1)
+  )
+    throw new Error(
+      'use knowledge check, context, evaluate, dashboard, session, or semantic; see knowledge --help'
+    )
+  const allowed = new Set([
+    '_',
+    'project',
+    'project-config',
+    'repo-path',
+    'plan',
+    ...(command === 'context' ? ['question', 'mode', 'max-bytes'] : []),
+  ])
+  if (Object.keys(args).some((key) => !allowed.has(key)))
+    throw new Error('unknown knowledge option; see knowledge --help')
+  const project = commandProject({ argv })
+  if (command === 'session') {
+    const operation = args._[1]
+    if (!['start', 'read', 'event', 'recover', 'list'].includes(operation))
+      throw new Error('unknown knowledge session operation')
+    const sessions = createKnowledgeSessions(project, args.plan)
+    let result
+    if (operation === 'list') result = { ok: true, ...sessions.list() }
+    else {
+      const chunks = []
+      let count = 0
+      for await (const chunk of process.stdin) {
+        count += chunk.length
+        if (count > 1024 * 1024) throw new Error('request exceeds byte ceiling')
+        chunks.push(chunk)
+      }
+      const input = JSON.parse(
+        new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))
+      )
+      if (operation === 'read') {
+        if (!input || Object.keys(input).join(',') !== 'sessionId')
+          throw new Error('read requires only sessionId')
+        result = sessions.read(input.sessionId)
+      } else result = sessions[operation](input)
+    }
+    process.stdout.write(encodeKnowledgeOutput(result))
+  } else if (command === 'dashboard') {
+    process.stdout.write(
+      encodeKnowledgeOutput(
+        knowledgeDashboard(loadKnowledgeWorkspace(project, args.plan))
+      )
+    )
+  } else {
+    const { plan, sha256 } = readKnowledgePlan(project, args.plan)
+    const cache = createGraphFileCache()
+    const graph = buildCanonicalGraph(project, { fileCache: cache })
+    if (command === 'check') {
+      const result = inspectKnowledgePlan(plan, graph)
+      process.stdout.write(encodeKnowledgeOutput(result))
+      if (!result.ok) process.exitCode = 1
+    } else {
+      if (!graph.ok)
+        throw new Error(
+          'canonical graph is invalid; run atelier graph to inspect diagnostics'
+        )
+      const result =
+        command === 'evaluate'
+          ? evaluateKnowledgeQuestions({ project, plan, sha256, graph, cache })
+          : createKnowledgeContext({
+              project,
+              plan,
+              sha256,
+              graph,
+              cache,
+              question: args.question,
+              mode: args.mode || 'graph',
+              maxBytes:
+                args['max-bytes'] === undefined
+                  ? plan.budget.maxContextBytes
+                  : Number(args['max-bytes']),
+            })
+      process.stdout.write(encodeKnowledgeOutput(result))
+      if (
+        command === 'evaluate' &&
+        result.cases.some(
+          (c) =>
+            !c.runs.graph.expectedEvidencePresent || c.runs.graph.stale.length
+        )
+      )
+        process.exitCode = 1
+    }
+  }
+} catch (error) {
+  console.error(`knowledge: ${error.message}`)
+  process.exitCode = 1
+}

package/src/commands/learn.mjs

@@ -0,0 +1,61 @@
+import { createLearningStore } from '../learning/store.mjs'
+import { planLearningWork } from '../learning/assistance.mjs'
+import { reportCommandFailure } from '../cli/command-failure.mjs'
+
+const commands = ['capture', 'propose', 'decide', 'activate', 'withdraw', 'list', 'context', 'render', 'graph', 'export', 'plan']
+const writes = new Set(commands.slice(0, 5))
+const usage = `Usage: atelier learn ${commands.join('|')}
+Read one JSON object from stdin, maximum 256 KiB. Run inside the intended Git
+workspace with untracked, ignored .atelier-local/ state.
+
+Every request includes workspaceId. Writes also include actor:{id,kind},
+requestId, expectedRevision and input. Actor is a local caller assertion, not
+authenticated identity. Reads use query only for context and render.
+
+Capture records evidence; propose creates an inert lesson. Decide binds an exact
+lesson digest. Activate makes approved content available to a named harness;
+it does not install files or grant tool permissions. Withdraw stops future use.
+List, context, render, graph, export and plan print private JSON to stdout.
+Export is an explicit private archive, never a send or publication operation.
+See docs/learning.md for complete examples.`
+
+function exactObject(value, allowed, required) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !allowed.includes(key))
+    || required.some(key => !Object.hasOwn(value, key))) throw new Error('invalid learning request fields')
+}
+
+const command = process.argv[2]
+if (command === '--help' || command === 'help') {
+  console.log(usage)
+} else {
+  try {
+    if (!commands.includes(command) || process.argv.length !== 3) throw new Error(usage)
+    const chunks = []
+    let bytes = 0
+    for await (const chunk of process.stdin) {
+      bytes += chunk.length
+      if (bytes > 256 * 1024) throw new Error('learning request exceeds byte limit')
+      chunks.push(chunk)
+    }
+    let body
+    try { body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))) }
+    catch { throw new Error('learning request must be UTF-8 JSON') }
+    const fields = writes.has(command)
+      ? ['workspaceId', 'actor', 'requestId', 'expectedRevision', 'input']
+      : ['workspaceId', ...(['context', 'render'].includes(command) ? ['query'] : [])]
+    exactObject(body, fields, fields)
+    const store = createLearningStore({ workspaceRoot: process.cwd(), workspaceId: body.workspaceId })
+    let result
+    if (writes.has(command)) {
+      result = store.execute({ requestId: body.requestId, expectedRevision: body.expectedRevision,
+        operation: command, input: body.input }, { actor: body.actor })
+    } else if (command === 'list') result = store.snapshot()
+    else if (command === 'plan') result = planLearningWork(store.snapshot())
+    else if (command === 'context' || command === 'render') result = store[command](body.query)
+    else result = store[command]()
+    console.log(JSON.stringify(result, null, 2))
+  } catch (error) {
+    reportCommandFailure(error)
+  }
+}