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

package/src/knowledge-health/workshop.mjs

@@ -0,0 +1,99 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { resolveProjectConfig } from '../project/config.mjs'
+import { openRegularFileNoFollow } from '../project/private-state.mjs'
+import { assessmentDigest } from './assessment.mjs'
+import { assessKnowledgeHealth } from './owner-join.mjs'
+import { createGuidedContribution } from '../knowledge/participatory/index.mjs'
+
+// A projection of the existing public workshop identities, not a new model.
+const relationId = 'checklist-workshop'
+const questionId = 'workshop-readiness'
+const sourceId = 'devday:checklist'
+const fieldId = 'kg.relations.supports'
+const exampleBinding = Object.freeze({ storeId: 'devday-workshop-example', sourceId,
+  artifactId: 'workshop-checklist', fieldId, actorBindingId: 'invented-workshop-owner' })
+
+function read(file) {
+  const fd = openRegularFileNoFollow(file)
+  try {
+    const size = fs.fstatSync(fd).size
+    if (size > 65536) throw Error('Workshop input exceeds its 65536-byte bound')
+    const bytes = Buffer.alloc(size + 1)
+    const count = fs.readSync(fd, bytes, 0, bytes.length, 0)
+    if (count !== size) throw Error('Workshop input changed during read')
+    return bytes.subarray(0, count)
+  } finally { fs.closeSync(fd) }
+}
+
+/** Copy the actual shipped public fixture into a NEW disposable workspace. */
+export function initializeKnowledgeHealthWorkshop(destination) {
+  const root = path.resolve(destination)
+  fs.mkdirSync(root, { recursive: false })
+  fs.cpSync(fileURLToPath(new URL('../../fixtures/knowledge-health/workshop/', import.meta.url)), root,
+    { recursive: true, force: false, errorOnExist: true })
+  fs.writeFileSync(path.join(root, '.gitignore'), '.atelier-local/\noutput/\n', { flag: 'wx' })
+  const git = spawnSync('git', ['init', '--quiet'], { cwd: root, encoding: 'utf8', timeout: 15000,
+    env: { PATH: process.env.PATH, GIT_CONFIG_NOSYSTEM: '1',
+      GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null' } })
+  if (git.status !== 0) throw Error('Git initialization failed for the new disposable workshop')
+  return root
+}
+
+/** Use the generic owner assessment against the participatory fixture itself.
+ * Expected evidence is read unchanged. This function writes no source or plan.
+ * A digest revision names source content; it is not an authoring-store head. */
+export function assessKnowledgeHealthWorkshop({ workspaceRoot, authoringBinding = exampleBinding,
+  sourceRevisions } = {}) {
+  const root = path.resolve(workspaceRoot)
+  if (authoringBinding.sourceId !== sourceId || authoringBinding.fieldId !== fieldId)
+    throw Error('The existing workshop source and field binding are required')
+  const project = resolveProjectConfig({ cwd: root, argv: ['--project', path.join(root, 'atelier.project.json')],
+    env: {}, writeLocalState: false })
+  const sourceBytes = read(path.join(root, 'records/checklist.md'))
+  const planBytes = read(path.join(root, 'knowledge-plan.json'))
+  const plan = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(planBytes))
+  if (!plan.relations?.some(r => r.id === relationId && r.from === 'checklist' && r.to === 'workshop' && r.predicate === 'supports')
+    || !plan.questions?.some(q => q.id === questionId && q.relations.includes(relationId)))
+    throw Error('The participatory workshop plan is required; the pilot fixture is separate')
+  const text = new TextDecoder('utf-8', { fatal: true }).decode(sourceBytes)
+  const matches = [...text.matchAll(/^    supports: (\[[^\r\n]*\])$/gm)]
+  if (matches.length !== 1) throw Error('One exact inline workshop supports declaration is required')
+  const match = matches[0], prefix = text.slice(0, match.index) + '    supports: '
+  const start = Buffer.byteLength(prefix), quote = match[1], digest = assessmentDigest(sourceBytes)
+  const revisions = sourceRevisions ?? ['checklist.md', 'workshop.md'].map(p => ({ repo: 'records', path: p,
+    revision: `content-sha256:${assessmentDigest(read(path.join(root, 'records', p)))}` }))
+  const revision = revisions.find(r => r.repo === 'records' && r.path === 'checklist.md')?.revision
+  if (!revision) throw Error('The workshop checklist source revision is required')
+  const binding = { source: { id: sourceId, repo: 'records', path: 'checklist.md', sha256: digest, revision },
+    field: { id: fieldId, pointer: '/kg/relations/supports', format: 'markdown-inline-array',
+      start, end: start + Buffer.byteLength(quote), quote }, authoring: structuredClone(authoringBinding) }
+  const observed = assessKnowledgeHealth({ project, relationId, questionId, sourceRevisions: revisions,
+    binding, currentSourceBytes: sourceBytes })
+  const graphRun = observed.retrievalEvaluation?.cases.find(c => c.id === questionId)?.runs.graph
+  return { ...observed, workshop: { sourceId, relationId, questionId, binding,
+    sourceSha256: digest, planSha256: assessmentDigest(planBytes),
+    expectedEvidence: structuredClone(plan.questions.find(q => q.id === questionId).expectedEvidence),
+    evaluationStaleSources: graphRun ? [...graphRun.stale] : null,
+    evaluationStatus: graphRun?.status ?? 'unavailable',
+    sourceRevisionKind: sourceRevisions ? 'owner-supplied' : 'content-digest',
+    sourceWritten: false, expectedEvidenceRefreshed: false, humanAcceptance: false } }
+}
+
+/** Compose the existing guided adapter and native caller with this observation.
+ * The host supplies actual native APIs and a current join. All writes and
+ * recovery remain in the existing native caller/store; none happen here. */
+export function prepareKnowledgeHealthWorkshopChoice({ observation, adapter, caller, same, ...input } = {}) {
+  const assessment = observation?.assessment, finding = assessment?.findings[0]
+  const joined = input.joined, reference = joined?.finding?.reference, evidence = assessment?.evidence
+  if (!finding || finding.source.id !== sourceId || evidence.relationId !== relationId
+    || evidence.questionId !== questionId || !reference
+    || reference.checkId !== finding.check.id || reference.checkVersion !== finding.check.version
+    || reference.planSha256 !== evidence.planSha256 || reference.readSetSha256 !== evidence.readSetSha256
+    || reference.comparisonSha256 !== evidence.comparisonSha256
+    || joined.document?.binding.sourceId !== sourceId || joined.document?.binding.fieldId !== fieldId)
+    throw Error('A current native join for this exact workshop observation is required')
+  return createGuidedContribution({ adapter, caller, same }).prepareChoice(input)
+}

package/src/learning/adapters.mjs

@@ -0,0 +1,68 @@
+import { learningDigest, validateLearningInput } from './store.mjs'
+import { boundedLearningValue } from './contracts.mjs'
+import { assertDocument } from '../capabilities/package.mjs'
+
+// Preserve exact version, binding and reported cause. Metadata never becomes a
+// fabricated user quote, a verified causal claim or an automatic lesson.
+export function capabilityEventToLearningInput({ event, scope, feedback = null }) {
+  boundedLearningValue({ event, scope, feedback })
+  assertDocument(event, 'event')
+  if (event.ext && Object.keys(event.ext).length) throw new Error('capability event extensions are not admitted')
+  let cause = event.cause
+  if (feedback !== null) {
+    const fields = ['event', 'subject', 'historyDigest', 'reportedCause', 'causeMapping', 'recorded', 'authority']
+    if (!feedback || Object.keys(feedback).sort().join() !== fields.sort().join() ||
+      learningDigest(feedback.event) !== learningDigest(event) || feedback.authority !== 'none' || feedback.recorded !== false ||
+      !['skill', 'host', 'tool', 'configuration', 'context', 'provider', 'unknown'].includes(feedback.reportedCause) ||
+      !/^sha256:[a-f0-9]{64}$/.test(feedback.historyDigest) ||
+      !feedback.subject || Object.keys(feedback.subject).sort().join() !== 'digest,id' ||
+      typeof feedback.subject.id !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(feedback.subject.digest)) throw new Error('invalid harness feedback provenance')
+    cause = feedback.reportedCause
+    const mapped = ['context', 'provider'].includes(cause) ? 'unknown' : cause
+    if (mapped !== event.cause || feedback.causeMapping !== (mapped === cause ? 'exact' : 'unsupported-steward-cause-preserved-in-wrapper')) throw new Error('feedback cause mapping mismatch')
+  }
+  const input = {
+    id: `capability:${event.id}`,
+    signal: event.kind === 'exercise' && event.outcome === 'passed' ? 'successful-run' : event.outcome === 'failed' && cause === 'tool' ? 'tool-failure' : 'exception',
+    text: `Caller-reported capability metadata: ${event.kind}; outcome: ${event.outcome}; reported cause: ${cause}; package: ${event.package}; release: ${event.releaseDigest}; binding: ${event.binding}; binding digest: ${event.bindingDigest}; session: ${event.session}. Original feedback text and causal verification are unavailable.`,
+    interpretation: 'tool', scope,
+    source: { ref: `capability-event:${event.id}`, digest: learningDigest(feedback ?? event), locator: event.evidenceDigest },
+  }
+  if (validateLearningInput('capture', input).length) throw new Error('capability event cannot fit learning contract')
+  return input
+}
+
+// Existing skill observations contain metadata, not the owner's actual words.
+// Preserve that limitation rather than manufacturing a transcript or lesson.
+export function skillObservationToLearningInput({ receipt, scope }) {
+  const observation = receipt?.observation
+  if (receipt?.schema !== 'mnstry.atelier-skill-observation-receipt@v1' || receipt.ok !== true
+    || typeof observation?.id !== 'string' || typeof observation.workflowKey !== 'string'
+    || typeof observation.signal !== 'string' || typeof observation.outcome !== 'string') {
+    throw new Error('valid skill observation receipt required')
+  }
+  const supported = { 'user-correction': 'user-correction', 'successful-run': 'successful-run', 'tool-failure': 'tool-failure' }
+  const input = {
+    id: `skill:${observation.id}`, signal: supported[observation.signal] ?? 'exception',
+    text: `Skill metadata: ${observation.signal}; outcome: ${observation.outcome}; workflow: ${observation.workflowKey}. Original feedback text is unavailable.`,
+    interpretation: 'tool', scope,
+    source: { ref: `skill-receipt:${observation.id}`, digest: learningDigest(receipt) },
+  }
+  if (validateLearningInput('capture', input).length) throw new Error('skill observation cannot fit learning contract')
+  return input
+}
+
+// A legacy proposal is evidence for a new proposal. Its old status/receipt can
+// never activate anything in this workspace. The caller selects exact local
+// evidence and scope; review remains a separate operation.
+export function legacyLessonToLearningInput({ legacy, id, scope, evidenceIds, artifact }) {
+  if (!legacy || typeof legacy.id !== 'string' || typeof legacy.claim !== 'string'
+    || !legacy.claim.trim()) throw new Error('legacy lesson claim required')
+  const input = { id, title: artifact?.name, principle: legacy.claim,
+    rationale: 'Imported proposal; its prior acceptance and activation are not authority in this workspace.',
+    exceptions: [], evidenceIds, scope, artifact,
+  }
+  if (validateLearningInput('propose', input).length) throw new Error('legacy proposal cannot fit learning contract')
+  return { input, provenance: { sourceId: legacy.id, sourceDigest: learningDigest(legacy),
+    authorityTransferred: false } }
+}

package/src/learning/assistance.mjs

@@ -0,0 +1,127 @@
+import { learningDigest, validateLearningInput } from './store.mjs'
+
+function requireSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot.workspaceId !== 'string'
+    || !Array.isArray(snapshot.observations) || !Array.isArray(snapshot.lessons)
+    || !Number.isSafeInteger(snapshot.revision)) throw new Error('invalid learning snapshot')
+}
+
+// Group metadata first. The plan never interprets a correction as accepted
+// guidance, and repeated observations are not independent corroboration.
+export function planLearningWork(snapshot) {
+  requireSnapshot(snapshot)
+  const groups = new Map()
+  const addressed = new Set(snapshot.lessons.flatMap(lesson => lesson.evidenceIds))
+  for (const observation of snapshot.observations) {
+    if (addressed.has(observation.id)) continue
+    const key = learningDigest(observation.scope)
+    if (!groups.has(key)) groups.set(key, { scope: observation.scope, observationIds: [], signals: new Set() })
+    const group = groups.get(key)
+    group.observationIds.push(observation.id)
+    group.signals.add(observation.signal)
+  }
+  return {
+    schema: 'atelier-learning-plan@v1', workspaceId: snapshot.workspaceId, revision: snapshot.revision,
+    groups: [...groups.values()].map(group => ({ scope: group.scope,
+      observationIds: group.observationIds,
+      route: group.signals.has('exception') ? 'focused-reasoning-or-human' : 'bounded-proposal',
+      reason: group.signals.has('exception') ? 'exception-needs-context' : 'unaddressed-observations',
+    })),
+    authority: { execution: false, acceptance: false, activation: false },
+  }
+}
+
+export function prepareLearningBatch({ snapshot, observationIds, maxInputBytes = 32 * 1024 }) {
+  requireSnapshot(snapshot)
+  if (!Array.isArray(observationIds) || !observationIds.length || observationIds.length > 32
+    || new Set(observationIds).size !== observationIds.length
+    || !Number.isSafeInteger(maxInputBytes) || maxInputBytes < 1 || maxInputBytes > 128 * 1024) {
+    throw new Error('invalid learning batch bounds')
+  }
+  const observations = observationIds.map(id => snapshot.observations.find(item => item.id === id))
+  if (observations.some(item => !item)) throw new Error('learning batch has unavailable evidence')
+  if (new Set(observations.map(item => learningDigest(item.scope))).size !== 1) throw new Error('learning batch must have one exact scope')
+  const payload = { schema: 'atelier-learning-batch@v1', workspaceId: snapshot.workspaceId,
+    revision: snapshot.revision, scope: observations[0].scope, observations: structuredClone(observations),
+    authority: { inputIsEvidence: true, acceptance: false, activation: false },
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(payload))
+  if (bytes > maxInputBytes) throw new Error('learning batch exceeds input byte limit')
+  return { payload, digest: learningDigest(payload), bytes }
+}
+
+// A host supplies qualified execution, exact-payload authorization and a durable
+// reservation implementation. No provider, network transport or credential is
+// embedded here. Callers receive inert proposals, never implicit store writes.
+export async function draftLearningProposals({ batch, adapter, authorization, budget,
+  maxOutputBytes = 32 * 1024, maxProposals = 8 }) {
+  // Retain the exact authorized bytes across asynchronous host calls.
+  try { batch = structuredClone(batch) }
+  catch { throw new Error('invalid learning batch') }
+  if (!batch?.payload || batch.digest !== learningDigest(batch.payload)
+    || batch.bytes !== Buffer.byteLength(JSON.stringify(batch.payload))
+    || batch.bytes > 128 * 1024 || batch.payload.schema !== 'atelier-learning-batch@v1'
+    || !Array.isArray(batch.payload.observations) || !batch.payload.observations.length
+    || batch.payload.observations.length > 32) throw new Error('invalid learning batch')
+  if (!adapter || typeof adapter.id !== 'string' || !adapter.id || typeof adapter.version !== 'string'
+    || !adapter.version || typeof adapter.draft !== 'function'
+    || adapter.qualification?.task !== 'lesson-proposal' || !adapter.qualification?.evidenceRef) {
+    throw new Error('qualified lesson proposal adapter required')
+  }
+  if (authorization?.workspaceId !== batch.payload.workspaceId || authorization?.payloadDigest !== batch.digest
+    || authorization?.adapterId !== adapter.id || authorization?.adapterVersion !== adapter.version
+    || authorization?.permitted !== true) throw new Error('exact host authorization required')
+  if (typeof budget?.reserve !== 'function' || typeof budget?.settle !== 'function') throw new Error('durable host budget required')
+  if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 128 * 1024
+    || !Number.isSafeInteger(maxProposals) || maxProposals < 1 || maxProposals > 16) throw new Error('invalid learning output bounds')
+  const key = learningDigest({ batch: batch.digest, adapter: adapter.id, version: adapter.version,
+    qualification: adapter.qualification, maxOutputBytes, maxProposals })
+  const adapterId = adapter.id, adapterVersion = adapter.version
+  const qualificationRef = adapter.qualification.evidenceRef
+  const draft = adapter.draft.bind(adapter)
+  const reservation = await budget.reserve({ key, calls: 1, inputBytes: batch.bytes, maxOutputBytes })
+  if (reservation?.status !== 'reserved' || typeof reservation.id !== 'string' || !reservation.id) {
+    throw new Error('learning budget unavailable or attempt already exists')
+  }
+  let response
+  try {
+    response = await draft(structuredClone(batch.payload), { maxOutputBytes, maxProposals })
+  } catch {
+    await budget.settle({ reservationId: reservation.id, key, outcome: 'unknown', usage: null })
+    throw new Error('learning adapter outcome unknown; reconcile before retry')
+  }
+  // Reconcile a returned attempt even if its proposed content fails validation.
+  const usage = measuredUsage(response?.usage)
+  await budget.settle({ reservationId: reservation.id, key, outcome: 'returned', usage })
+  let proposals
+  try {
+    const bytes = Buffer.byteLength(JSON.stringify(response?.proposals))
+    if (bytes > maxOutputBytes || !Array.isArray(response?.proposals)
+      || response.proposals.length > maxProposals) throw new Error()
+    const known = new Set(batch.payload.observations.map(item => item.id))
+    const ids = new Set()
+    proposals = response.proposals.map(proposal => {
+      if (validateLearningInput('propose', proposal).length || ids.has(proposal.id)
+        || learningDigest(proposal.scope) !== learningDigest(batch.payload.scope)
+        || proposal.evidenceIds.some(id => !known.has(id))) throw new Error()
+      ids.add(proposal.id)
+      return structuredClone(proposal)
+    })
+  } catch { throw new Error('learning adapter returned invalid proposals') }
+  return { schema: 'atelier-learning-drafts@v1', batchDigest: batch.digest, adapterId,
+    adapterVersion, qualificationRef,
+    reservationId: reservation.id, proposals, usage,
+    authority: { stored: false, acceptance: false, activation: false },
+  }
+}
+
+function measuredUsage(value) {
+  if (value == null) return null
+  if (typeof value !== 'object' || Array.isArray(value)) return null
+  const result = {}
+  for (const key of ['inputTokens', 'outputTokens', 'durationMs']) {
+    result[key] = Number.isSafeInteger(value[key]) && value[key] >= 0 ? value[key] : null
+  }
+  // No price estimate or quota-percentage conversion is invented here.
+  return result
+}

package/src/learning/contracts.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { canonicalize } from '../attestation/jcs.mjs';
+
+export const LEARNING_MAX_BYTES = 256 * 1024;
+export const LEARNING_MAX_EVENTS = 10000;
+export const LEARNING_MAX_JOURNAL_BYTES = 32 * 1024 * 1024;
+// Minimum ordinary-write headroom; the store also reserves a complete event
+// and one event slot for every active binding after each prospective write.
+export const LEARNING_WITHDRAWAL_RESERVE_BYTES = 1024 * 1024;
+export const LEARNING_WITHDRAWAL_RESERVE_EVENTS = 128;
+export const learningSchema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-learning.v1.schema.json', import.meta.url), 'utf8'));
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv); ajv.addSchema(learningSchema);
+const validators = new Map();
+const operations = new Set(['capture', 'propose', 'decide', 'activate', 'withdraw']);
+
+// Canonical JSON, not a signature or evidence of the identity of the caller.
+export function learningDigest(value) {
+  return `sha256:${createHash('sha256').update(canonicalize(value)).digest('hex')}`;
+}
+
+export function boundedLearningValue(value) {
+  const visited = new Set();
+  function walk(item, depth) {
+    if (depth > 24) throw new Error('learning value exceeds depth ceiling');
+    if (item === null || typeof item === 'boolean') return;
+    if (typeof item === 'string') {
+      if (item.includes('\u0000') || item.length > LEARNING_MAX_BYTES) throw new Error('invalid learning text');
+      return;
+    }
+    if (typeof item === 'number' && Number.isFinite(item)) return;
+    if (typeof item !== 'object' || visited.has(item)) throw new Error('learning value must be JSON');
+    if (!Array.isArray(item) && ![null, Object.prototype].includes(Object.getPrototypeOf(item))) throw new Error('learning value must be plain JSON');
+    visited.add(item);
+    const keys = Reflect.ownKeys(item);
+    if (keys.length > 1024) throw new Error('learning value exceeds member ceiling');
+    for (const key of keys) {
+      if (typeof key !== 'string') throw new Error('learning value must be plain JSON');
+      if (Array.isArray(item) && key === 'length') continue;
+      const descriptor = Object.getOwnPropertyDescriptor(item, key);
+      if (!descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) throw new Error('learning value must be plain JSON');
+      walk(descriptor.value, depth + 1);
+    }
+    if (Array.isArray(item) && Object.keys(item).length !== item.length) throw new Error('learning array must be dense');
+    visited.delete(item);
+  }
+  walk(value, 0);
+  if (Buffer.byteLength(canonicalize(value)) > LEARNING_MAX_BYTES) throw new Error('learning value exceeds byte ceiling');
+  return structuredClone(value);
+}
+
+export function validateLearningValue(definition, value) {
+  try { boundedLearningValue(value); } catch (error) { return [error.message]; }
+  if (!Object.hasOwn(learningSchema.$defs, definition)) return ['unknown learning definition'];
+  if (!validators.has(definition)) validators.set(definition, ajv.getSchema(`${learningSchema.$id}#/$defs/${definition}`));
+  const validate = validators.get(definition);
+  return validate(value) ? [] : ['learning document does not match the contract'];
+}
+
+export function validateLearningInput(operation, input) {
+  return operations.has(operation) ? validateLearningValue(`${operation}Input`, input) : ['unknown learning operation'];
+}

package/src/learning/store.mjs

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { canonicalize } from '../attestation/jcs.mjs';
+import { withPrivateLock, publishPrivateFile, createVerifiedFileSequence, isPendingPrivateWrite } from '../project/durable-state.mjs';
+import { ensureContainedPrivateDirectory, openRegularFileNoFollow } from '../project/private-state.mjs';
+import { learningDigest, boundedLearningValue, validateLearningValue, LEARNING_MAX_BYTES, LEARNING_MAX_EVENTS, LEARNING_MAX_JOURNAL_BYTES, LEARNING_WITHDRAWAL_RESERVE_BYTES, LEARNING_WITHDRAWAL_RESERVE_EVENTS } from './contracts.mjs';
+export { learningDigest, validateLearningInput, validateLearningValue } from './contracts.mjs';
+
+const prefix = 'mnstry.atelier-learning-';
+const schema = kind => `${prefix}${kind}@v1`;
+function refuse(code, message) { throw Object.assign(new Error(message), { code }); }
+function valid(definition, value) {
+  const errors = validateLearningValue(definition, value);
+  if (errors.length) refuse('LEARNING_INVALID', errors[0]);
+  return value;
+}
+function seal(value) { return { ...value, digest: learningDigest(value) }; }
+function unsealed(value) { const { digest, ...body } = value; return body; }
+function same(left, right) { return canonicalize(left) === canonicalize(right); }
+function latestDecision(state, lessonId) { return state.decisions.findLast(record => record.lessonId === lessonId); }
+function lessonFor(state, lessonId, digest) {
+  const lesson = state.lessons.find(record => record.id === lessonId);
+  if (!lesson) refuse('LEARNING_MISSING', 'lesson does not exist');
+  if (digest !== undefined && lesson.digest !== digest) refuse('LEARNING_STALE', 'lesson digest changed or does not match');
+  return lesson;
+}
+function activationState(state, id) { return state.activationStates.find(record => record.activationId === id); }
+function activeFor(state, lessonId, harnessId) {
+  return state.activations.filter(record => record.lessonId === lessonId &&
+    (harnessId === undefined || record.harnessId === harnessId) && activationState(state, record.id)?.status === 'active');
+}
+function initial(workspaceId) {
+  return { schema: schema('snapshot'), workspaceId, revision: 0, observations: [], lessons: [], decisions: [], activations: [], withdrawals: [], activationStates: [], events: [], headDigest: null, journalBytes: 0 };
+}
+function common(state, actor, createdAt, kind, id) {
+  return { schema: schema(kind), id, workspaceId: state.workspaceId, revision: state.revision + 1, actor, createdAt };
+}
+function generatedId(kind, requestId) { return `${kind}:${learningDigest(requestId).slice(7, 39)}`; }
+function makeRecord(state, request, actor, createdAt) {
+  const input = request.input, operation = request.operation;
+  if (request.expectedRevision !== state.revision) refuse('LEARNING_STALE', 'learning revision changed; reload before deciding');
+  if (['decide', 'activate', 'withdraw'].includes(operation) && actor.kind !== 'human') refuse('LEARNING_AUTHORITY', 'this operation requires an explicitly asserted local human actor');
+  if (operation === 'capture') {
+    if (state.observations.some(record => record.id === input.id)) refuse('LEARNING_DUPLICATE', 'observation identifier already exists');
+    if (input.lessonId && lessonFor(state, input.lessonId).scope.project !== input.scope.project) refuse('LEARNING_SCOPE', 'observation and lesson projects differ');
+    return seal({ ...common(state, actor, createdAt, 'observation', input.id), ...input });
+  }
+  if (operation === 'propose') {
+    if (state.lessons.some(record => record.id === input.id)) refuse('LEARNING_DUPLICATE', 'lesson identifier already exists');
+    const evidence = input.evidenceIds.map(id => {
+      const record = state.observations.find(item => item.id === id);
+      if (!record) refuse('LEARNING_MISSING', 'proposal evidence does not exist');
+      if (record.scope.project !== input.scope.project) refuse('LEARNING_SCOPE', 'proposal evidence cannot cross projects');
+      return { id: record.id, digest: record.digest };
+    });
+    if (input.supersedes) {
+      const prior = lessonFor(state, input.supersedes);
+      if (!same(prior.scope, input.scope) || prior.artifact.kind !== input.artifact.kind || prior.artifact.name !== input.artifact.name) refuse('LEARNING_SCOPE', 'replacement must retain the exact scope and artifact slot');
+    }
+    return seal({ ...common(state, actor, createdAt, 'lesson', input.id), ...input, artifact: seal(input.artifact), evidence });
+  }
+  if (operation === 'decide') {
+    lessonFor(state, input.lessonId, input.lessonDigest);
+    if (activeFor(state, input.lessonId).length) refuse('LEARNING_ACTIVE', 'withdraw active lesson before changing its decision');
+    return seal({ ...common(state, actor, createdAt, 'decision', generatedId('decision', request.requestId)), ...input });
+  }
+  if (operation === 'activate') {
+    const lesson = lessonFor(state, input.lessonId, input.lessonDigest);
+    const decision = latestDecision(state, lesson.id);
+    if (!decision || decision.id !== input.decisionId || decision.verdict !== 'accepted' || decision.lessonDigest !== lesson.digest) refuse('LEARNING_DECISION', 'activation requires the latest exact accepted decision');
+    if (state.activations.some(record => record.id === input.id)) refuse('LEARNING_DUPLICATE', 'activation identifier already exists');
+    if (activeFor(state, lesson.id, input.harnessId).length) refuse('LEARNING_ACTIVE', 'lesson is already active for this harness');
+    if (state.activations.some(record => record.lessonId === lesson.id && record.harnessId === input.harnessId && activationState(state, record.id)?.status === 'superseded')) refuse('LEARNING_SUPERSEDED', 'superseded lesson requires a new reviewed proposal');
+    if (lesson.supersedes) {
+      const prior = lessonFor(state, lesson.supersedes);
+      if (!same(prior.scope, lesson.scope)) refuse('LEARNING_SCOPE', 'replacement scope changed');
+    }
+    return seal({ ...common(state, actor, createdAt, 'activation', input.id), ...input, artifactDigest: lesson.artifact.digest });
+  }
+  const activation = state.activations.find(record => record.id === input.activationId);
+  if (!activation) refuse('LEARNING_MISSING', 'activation does not exist');
+  if (activationState(state, activation.id)?.status !== 'active') refuse('LEARNING_INACTIVE', 'activation is no longer active');
+  return seal({ ...common(state, actor, createdAt, 'withdrawal', generatedId('withdrawal', request.requestId)), ...input });
+}
+function applyEvent(event, state) {
+  const operation = event.request.operation, record = event.record;
+  const target = { capture: 'observations', propose: 'lessons', decide: 'decisions', activate: 'activations', withdraw: 'withdrawals' }[operation];
+  state[target].push(record);
+  if (operation === 'activate') {
+    const lesson = lessonFor(state, record.lessonId);
+    if (lesson.supersedes) {
+      for (const prior of activeFor(state, lesson.supersedes, record.harnessId)) {
+        Object.assign(activationState(state, prior.id), { status: 'superseded', eventId: event.id });
+      }
+    }
+    state.activationStates.push({ activationId: record.id, status: 'active', eventId: event.id });
+  }
+  if (operation === 'withdraw') Object.assign(activationState(state, record.activationId), { status: 'withdrawn', eventId: event.id });
+  state.events.push(event); state.revision = event.revision; state.headDigest = event.digest;
+  return state;
+}
+function publicSnapshot(state) {
+  const { events, headDigest, journalBytes, ...snapshot } = state;
+  return structuredClone({ ...snapshot, headDigest });
+}
+function boundedRead(file) {
+  const fd = openRegularFileNoFollow(file);
+  try {
+    if (fs.fstatSync(fd).size > LEARNING_MAX_BYTES * 3) refuse('LEARNING_LIMIT', 'learning journal byte ceiling exceeded');
+    const bytes = fs.readFileSync(fd);
+    if (bytes.length > LEARNING_MAX_BYTES * 3) refuse('LEARNING_LIMIT', 'learning journal byte ceiling exceeded');
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } finally { fs.closeSync(fd); }
+}
+
+function readWorkspaceIdentity(file) {
+  const text = boundedRead(file);
+  let document;
+  try { document = JSON.parse(text); } catch { refuse('LEARNING_HISTORY', 'learning workspace identity contains invalid JSON'); }
+  return valid('workspace', document);
+}
+
+// Local integrity and lifecycle, not remote authentication, semantic truth,
+// executable installation, or an authority to read provenance locations.
+export function createLearningStore({ workspaceRoot = process.cwd(), workspaceId } = {}) {
+  valid('id', workspaceId);
+  const root = fs.realpathSync(workspaceRoot);
+  function placement() {
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    try {
+      if (execFileSync('git', ['-C', root, 'ls-files', '-z', '--', '.atelier-local'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })) throw new Error('tracked');
+      execFileSync('git', ['-C', root, 'check-ignore', '--quiet', '.atelier-local/'], { env, stdio: 'ignore' });
+    } catch { refuse('LEARNING_PRIVATE', 'learning requires ignored, untracked .atelier-local/ in a Git workspace'); }
+  }
+  placement();
+  function directory(...parts) {
+    return ensureContainedPrivateDirectory({ workspaceRoot: root, directory: path.join(root, '.atelier-local', 'learning', ...parts), label: 'learning state' });
+  }
+  const stateDir = directory(), eventDir = directory('events');
+  const identityPath = path.join(stateDir, 'workspace.json');
+  const identity = { schema: schema('workspace'), workspaceId };
+  withPrivateLock(path.join(stateDir, 'operation.lock'), () => {
+    if (fs.existsSync(identityPath)) {
+      const stored = readWorkspaceIdentity(identityPath);
+      if (!same(stored, identity)) refuse('LEARNING_WORKSPACE', 'learning workspace identity differs');
+    } else {
+      if (fs.readdirSync(eventDir).filter(name => !isPendingPrivateWrite(name)).length) refuse('LEARNING_HISTORY', 'learning workspace identity is missing');
+      publishPrivateFile(identityPath, canonicalize(identity) + '\n');
+    }
+  });
+  const readSequence = createVerifiedFileSequence({
+    directory: eventDir,
+    initial: () => initial(workspaceId),
+    apply(text, state, index, name) {
+      if (name !== `${String(index).padStart(10, '0')}.json`) refuse('LEARNING_HISTORY', 'learning history is not contiguous');
+      if (Buffer.byteLength(text) > LEARNING_MAX_BYTES * 3) refuse('LEARNING_LIMIT', 'learning journal byte ceiling exceeded');
+      let event;
+      try { event = JSON.parse(text); } catch { refuse('LEARNING_HISTORY', 'learning history contains invalid JSON'); }
+      valid('event', event);
+      if (event.workspaceId !== workspaceId || event.revision !== index || event.previousDigest !== state.headDigest || event.id !== `event:${index}` || event.digest !== learningDigest(unsealed(event))) refuse('LEARNING_HISTORY', 'learning history integrity mismatch');
+      if (event.requestDigest !== learningDigest({ request: event.request, actor: event.actor })) refuse('LEARNING_HISTORY', 'learning request integrity mismatch');
+      if (state.events.some(item => item.request.requestId === event.request.requestId)) refuse('LEARNING_HISTORY', 'learning history repeats a request');
+      const expected = makeRecord(state, event.request, event.actor, event.createdAt);
+      if (!same(expected, event.record)) refuse('LEARNING_HISTORY', 'learning record integrity mismatch');
+      state.journalBytes += Buffer.byteLength(text);
+      return applyEvent(event, state);
+    },
+  });
+  function readState() {
+    placement(); directory(); directory('events');
+    if (!same(readWorkspaceIdentity(identityPath), identity)) refuse('LEARNING_WORKSPACE', 'learning workspace identity differs');
+    const entries = fs.readdirSync(eventDir).filter(name => !isPendingPrivateWrite(name));
+    if (entries.length > LEARNING_MAX_EVENTS) refuse('LEARNING_LIMIT', 'learning journal event ceiling exceeded');
+    let totalBytes = 0;
+    for (const name of entries) {
+      const stat = fs.lstatSync(path.join(eventDir, name));
+      if (stat.size > LEARNING_MAX_BYTES * 3) refuse('LEARNING_LIMIT', 'learning journal byte ceiling exceeded');
+      totalBytes += stat.size;
+      if (totalBytes > LEARNING_MAX_JOURNAL_BYTES) refuse('LEARNING_LIMIT', 'learning journal aggregate byte ceiling exceeded');
+    }
+    return readSequence();
+  }
+  readState();
+  function snapshot() { return publicSnapshot(readState()); }
+  function render({ lessonId, lessonDigest } = {}) {
+    valid('id', lessonId); valid('digest', lessonDigest);
+    const state = readState(), lesson = lessonFor(state, lessonId, lessonDigest);
+    return { schema: schema('render'), lessonId, lessonDigest, artifact: structuredClone(lesson.artifact), status: latestDecision(state, lessonId)?.verdict ?? 'proposed', executable: false };
+  }
+  function context({ scope, harnessId } = {}) {
+    valid('scope', scope); valid('id', harnessId);
+    if (scope.activity === '*') refuse('LEARNING_SCOPE', 'context requires a concrete activity');
+    const state = readState();
+    const candidates = state.activations.filter(activation => activation.harnessId === harnessId && activationState(state, activation.id)?.status === 'active').flatMap(activation => {
+      const lesson = lessonFor(state, activation.lessonId, activation.lessonDigest);
+      const decision = latestDecision(state, lesson.id);
+      if (!decision || decision.verdict !== 'accepted' || decision.id !== activation.decisionId || lesson.artifact.digest !== activation.artifactDigest) return [];
+      if (lesson.scope.project !== scope.project || (lesson.scope.activity !== '*' && lesson.scope.activity !== scope.activity)) return [];
+      return [{ id: lesson.id, lessonDigest: lesson.digest, scope: lesson.scope, artifact: lesson.artifact, activationId: activation.id, decisionId: decision.id, principle: lesson.principle, exceptions: lesson.exceptions, evidence: lesson.evidence.map(item => ({ ...item, source: state.observations.find(record => record.id === item.id).source })) }];
+    });
+    const groups = new Map();
+    for (const item of candidates) {
+      const slot = canonicalize([item.artifact.kind, item.artifact.name]);
+      if (!groups.has(slot)) groups.set(slot, []);
+      groups.get(slot).push(item);
+    }
+    const conflicts = [], withheld = new Set();
+    for (const group of groups.values()) {
+      if (new Set(group.map(item => item.artifact.digest)).size < 2) continue;
+      const lessonIds = group.map(item => item.id).sort();
+      for (const id of lessonIds) withheld.add(id);
+      conflicts.push({ kind: group[0].artifact.kind, name: group[0].artifact.name, lessonIds, reason: 'overlapping-artifact-slot' });
+    }
+    return { schema: schema('context'), workspaceId, revision: state.revision, scope: structuredClone(scope), harnessId, lessons: structuredClone(candidates.filter(item => !withheld.has(item.id))), conflicts, authority: { grantsToolPermissions: false, authenticated: false } };
+  }
+  function graph() {
+    const state = readState(), nodes = [], edges = [];
+    for (const [collection, type] of [['observations', 'observation'], ['lessons', 'lesson-proposal'], ['decisions', 'decision'], ['activations', 'activation'], ['withdrawals', 'withdrawal']]) {
+      for (const record of state[collection]) nodes.push({ id: `${type}:${record.id}`, type, record: structuredClone(record) });
+    }
+    const edge = (from, to, type) => edges.push({ from, to, type });
+    for (const record of state.observations) if (record.lessonId) edge(`observation:${record.id}`, `lesson-proposal:${record.lessonId}`, 'application-feedback');
+    for (const record of state.lessons) {
+      for (const evidence of record.evidence) edge(`lesson-proposal:${record.id}`, `observation:${evidence.id}`, 'supported-by');
+      if (record.supersedes) edge(`lesson-proposal:${record.id}`, `lesson-proposal:${record.supersedes}`, 'proposes-replacement');
+    }
+    for (const record of state.decisions) edge(`decision:${record.id}`, `lesson-proposal:${record.lessonId}`, record.verdict);
+    for (const record of state.activations) { edge(`activation:${record.id}`, `lesson-proposal:${record.lessonId}`, 'activates'); edge(`activation:${record.id}`, `decision:${record.decisionId}`, 'authorized-by-local-assertion'); }
+    for (const record of state.withdrawals) edge(`withdrawal:${record.id}`, `activation:${record.activationId}`, 'withdraws');
+    return { schema: schema('graph'), workspaceId, revision: state.revision, nodes, edges, activationStates: structuredClone(state.activationStates), authority: { visibility: 'private', canonicalGraphMutation: false, authenticated: false } };
+  }
+  return Object.freeze({
+    execute(request, { actor } = {}) {
+      request = boundedLearningValue(request); actor = boundedLearningValue(actor);
+      valid('request', request); valid('actor', actor);
+      return withPrivateLock(path.join(directory(), 'operation.lock'), () => {
+        const state = readState(), requestDigest = learningDigest({ request, actor });
+        const prior = state.events.find(event => event.request.requestId === request.requestId);
+        if (prior) {
+          if (prior.requestDigest !== requestDigest) refuse('LEARNING_REQUEST_REUSE', 'request identifier was reused with different input or actor');
+          return { schema: schema('result'), ok: true, duplicate: true, revision: prior.revision, eventId: prior.id, record: structuredClone(prior.record) };
+        }
+        const withdrawing = request.operation === 'withdraw';
+        const createdAt = new Date().toISOString(), record = makeRecord(state, request, actor, createdAt);
+        const event = seal({ schema: schema('event'), workspaceId, id: `event:${state.revision + 1}`, revision: state.revision + 1, previousDigest: state.headDigest, requestDigest, request, actor, createdAt, record });
+        valid('event', event);
+        const eventBytes = canonicalize(event) + '\n';
+        // readState returns a private clone, so prospective lifecycle changes
+        // cannot affect the verified committed projection when admission fails.
+        const prospective = applyEvent(event, state);
+        const remainingActive = prospective.activationStates.filter(binding => binding.status === 'active').length;
+        // Every committed event passes the canonical LEARNING_MAX_BYTES bound.
+        // Account for its final newline as well, so each remaining binding has
+        // room for any valid withdrawal, even after the last ordinary write.
+        const reserveBytes = Math.max(remainingActive * (LEARNING_MAX_BYTES + 1), withdrawing ? 0 : LEARNING_WITHDRAWAL_RESERVE_BYTES);
+        const reserveEvents = Math.max(remainingActive, withdrawing ? 0 : LEARNING_WITHDRAWAL_RESERVE_EVENTS);
+        if (prospective.revision + reserveEvents > LEARNING_MAX_EVENTS) refuse('LEARNING_LIMIT', 'learning journal event ceiling exceeded; withdrawal reservations retained');
+        if (prospective.journalBytes + Buffer.byteLength(eventBytes) + reserveBytes > LEARNING_MAX_JOURNAL_BYTES) refuse('LEARNING_LIMIT', 'learning journal aggregate byte ceiling exceeded; withdrawal reservations retained');
+        publishPrivateFile(path.join(eventDir, `${String(event.revision).padStart(10, '0')}.json`), eventBytes);
+        const committed = readState().events.at(-1);
+        if (committed.digest !== event.digest) refuse('LEARNING_HISTORY', 'learning journal readback mismatch');
+        return { schema: schema('result'), ok: true, duplicate: false, revision: event.revision, eventId: event.id, record: structuredClone(record) };
+      });
+    },
+    snapshot, render, context, graph,
+    export() {
+      const state = readState();
+      return seal({ schema: schema('export'), workspaceId, revision: state.revision, visibility: 'private', authority: { authenticated: false, importedActivation: false, automaticPublication: false }, history: state.events, snapshot: publicSnapshot(state) });
+    },
+  });
+}