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

package/src/knowledge/participatory/guided-contribution.mjs

@@ -0,0 +1,44 @@
+// Additive presentation/composition over the host's existing received APIs.
+// This module opens no store, changes no editor, dispatches nothing and writes no source.
+export function createGuidedContribution({ adapter, caller, same } = {}) {
+  for (const name of ['isJoin', 'prepareContribution', 'prepareSelection'])
+    if (typeof adapter?.[name] !== 'function') throw Error('Received contribution adapter required');
+  for (const name of ['noteEligible', 'noteCanWrite', 'dispositionFromChoice'])
+    if (typeof caller?.[name] !== 'function') throw Error('Received native contribution caller required');
+  if (typeof same !== 'function') throw Error('Existing equality required');
+  function prepareChoice({ joined, editorState, contributionId, choiceId, originalWords, interpretation = null,
+    outcome, participantChoice = false } = {}) {
+    if (!adapter.isJoin(joined)) throw Error('Current source-bound finding required');
+    if (participantChoice !== true) throw Error('Choose how to keep these words first.');
+    if (!contributionId?.startsWith('kh-note-')) throw Error('Use the existing host contribution identity.');
+    const plan = adapter.prepareContribution(joined, { id: contributionId, originalWords, interpretation, outcome });
+    const eligibility = caller.noteCanWrite('note', plan.record);
+    if (!eligibility.allowed) throw Error(eligibility.reason);
+    if (!caller.noteEligible(editorState, plan.record)) throw Error('Save and verify the current passage first.');
+    const record = caller.dispositionFromChoice({ id: choiceId, contribution: plan.record,
+      findingReference: plan.context.findingReference, outcome, participantChoice, interpretation });
+    // Delegate all disposition rules/readback to the actual native caller.
+    return { plan, record, state: 'chosen-not-retained', assistantRequest: false, sourceApplication: false };
+  }
+  function exampleRevision({ joined, contribution, proposalId, changeId, decisionId } = {}) {
+    if (!adapter.isJoin(joined) || joined.document.binding.sourceId !== 'devday:checklist' ||
+      joined.document.binding.fieldId !== 'kg.relations.supports' || joined.savedPassage.anchor.quote !== '[]' ||
+      !same(joined.finding.direction && {
+        from: joined.finding.direction.fromConceptRef, predicate: joined.finding.direction.predicate,
+        to: joined.finding.direction.toConceptRef
+      }, { from: 'checklist', predicate: 'supports', to: 'workshop' }))
+      throw Error('This proposed change belongs only to the current invented workshop declaration.');
+    const anchor = joined.savedPassage.anchor;
+    const proposal = { binding: contribution.binding, id: proposalId, revision: 1,
+      sourceBase: contribution.sourceBase, draftRevision: contribution.draftRevision,
+      contributionId: contribution.id, contributionRevision: contribution.revision,
+      changes: [{ id: changeId, startByte: anchor.startByte, endByte: anchor.endByte,
+        original: anchor.quote, replacement: '["devday:workshop"]', dependsOn: [] }] };
+    // This is participant-visible example wording, not an assistant response.
+    const selection = adapter.prepareSelection(joined, { contribution,
+      proposal: { ...proposal, changeStates: { [changeId]: 'pending' } }, changeIds: [changeId], decisionId });
+    return { proposal, selection, provenance: 'invented-example-proposal', state: 'preview-only',
+      assistantRequest: false, draftApplication: false, sourceApplication: false };
+  }
+  return Object.freeze({ prepareChoice, exampleRevision });
+}

package/src/knowledge/participatory/index.mjs

@@ -0,0 +1,2 @@
+export { createGuidedContribution } from './guided-contribution.mjs';
+export { guidance, guidanceFor, createGuidanceCue } from './guidance.mjs';

package/src/knowledge/participatory/installed-workshop.mjs

@@ -0,0 +1,108 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createCoauthorStore } from '@mnstry/atelier/coauthor/store';
+import { contentDigest } from '@mnstry/atelier/coauthor';
+import { buildCanonicalGraph } from '@mnstry/atelier/graph';
+import { resolveProjectConfig } from '@mnstry/atelier/project';
+import { initializeKnowledgeHealthWorkshop, assessKnowledgeHealthWorkshop } from '../../knowledge-health/workshop.mjs';
+
+// Public invented example over installed Foundation APIs. The source owner's
+// example edit is confined to a newly created disposable workspace. This is
+// not a Workbench host, editor, store, graph rule or publication controller.
+const words = '  Fixture participant: the checklist can support our discussion.\nIt cannot make our decision. 🪴  ';
+const interpretation = 'Fixture interpretation: record the checklist as supporting evidence; readiness remains undecided.';
+const outcomes = ['note', 'disagreement', 'perspective-only', 'pause', 'revision'];
+export function initializeWorkshop(destination) {
+  return initializeKnowledgeHealthWorkshop(destination);
+}
+
+function project(root) {
+  return resolveProjectConfig({ cwd: root, argv: ['--project', path.join(root, 'atelier.project.json')],
+    env: {}, writeLocalState: false });
+}
+// Run the received generic assessment against the SAME participatory fixture.
+// Structural current evidence and frozen expected-evidence evaluation stay separate.
+export async function assessInstalledWorkshop(root) {
+  return { status: 'observed', result: assessKnowledgeHealthWorkshop({ workspaceRoot: root }) };
+}
+
+export async function rehearseInstalledWorkshop(destination, { outcome = 'revision' } = {}) {
+  assert.ok(outcomes.includes(outcome), 'Choose an explicit supported example outcome.');
+  const root = initializeWorkshop(destination), sourceFile = path.join(root, 'records/checklist.md');
+  const source = fs.readFileSync(sourceFile, 'utf8'), baselinePlan = fs.readFileSync(path.join(root, 'knowledge-plan.json'));
+  const before = buildCanonicalGraph(project(root));
+  assert.equal(before.ok, true); assert.equal(before.nodes.length, 2); assert.equal(before.edges.length, 0);
+  const beforeAssessment = await assessInstalledWorkshop(root);
+  const store = createCoauthorStore({ workspaceRoot: root }), id = 'invented-workshop-' + outcome;
+  // Consumer-owned fields keep original words, interpretation and choice apart.
+  // These are ordinary coauthor draft fields. They are not native typed finding
+  // disposition envelopes; that package join remains separately required.
+  const fields = ['original-words', 'proposed-interpretation', 'example-choice'].map(fieldId => ({ id: fieldId,
+    source: { ref: 'records/checklist.md', digest: contentDigest(source) } }));
+  let state = store.start({ id, fields }), eventOrdinal = 0;
+  const send = (type, input = {}) => {
+    const event = { id: `example-event-${++eventOrdinal}`, type, expectedRevision: state.revision, ...input };
+    state = store.dispatch(id, event); return { state, event };
+  };
+  send('answer', { text: words });
+  const paused = send('pause').state;
+  assert.equal(paused.phase, 'paused'); assert.deepEqual(store.recover(id), paused);
+  send('resume');
+  const firstSave = send('save');
+  assert.equal(state.phase, 'saved'); assert.equal(state.saved[0].text, words);
+  assert.deepEqual(store.dispatch(id, firstSave.event), state); // No duplicate effect.
+  send('advance'); send('answer', { text: 'Fixture interpretation awaiting review.' });
+  send('propose', { text: interpretation });
+  assert.equal(state.phase, 'confirmation');
+  assert.throws(() => store.dispatch(id, { id: 'unconfirmed-save', type: 'save', expectedRevision: state.revision }), /refused/);
+  send('confirm'); send('save'); send('advance');
+  send('answer', { text: outcome }); send('save');
+  const reopened = createCoauthorStore({ workspaceRoot: root }).read(id);
+  assert.deepEqual(reopened, state);
+  assert.deepEqual(reopened.saved.map(x => x.text), [words, interpretation, outcome]);
+  assert.equal(fs.readFileSync(sourceFile, 'utf8'), source);
+  const preview = source.replace('    supports: []\n', '    supports: ["devday:workshop"]\n');
+  assert.notEqual(preview, source);
+  let after = before, afterAssessment = beforeAssessment, ownerCorrection = false;
+  if (outcome === 'revision') {
+    // Ordinary source-owner editing route in this fresh disposable example.
+    // No generic source writer is exported; no other workspace is accepted.
+    assert.equal(fs.realpathSync(path.dirname(sourceFile)), path.join(fs.realpathSync(root), 'records'));
+    assert.equal(fs.readFileSync(sourceFile, 'utf8'), source);
+    fs.writeFileSync(sourceFile, preview);
+    assert.equal(fs.readFileSync(sourceFile, 'utf8'), preview);
+    ownerCorrection = true;
+    after = buildCanonicalGraph(project(root));
+    assert.equal(after.ok, true);
+    assert.ok(after.edges.some(e => e.source === 'devday:checklist' && e.type === 'supports' && e.target === 'devday:workshop'));
+    assert.deepEqual(store.read(id), reopened); // Old words remain historical.
+    assert.throws(() => store.dispatch(id, { id: 'write-after-source-drift', type: 'advance', expectedRevision: reopened.revision }), /source changed/);
+    afterAssessment = await assessInstalledWorkshop(root);
+  }
+  assert.deepEqual(fs.readFileSync(path.join(root, 'knowledge-plan.json')), baselinePlan);
+  const packageInfo = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../../package.json', import.meta.resolve('@mnstry/atelier/coauthor/store')))));
+  return {
+    packageVersion: packageInfo.version, outcome, publicInventedOnly: true, participantChoice: 'fixture',
+    beforeGraph: { ok: before.ok, nodes: before.nodes.length, edges: before.edges.length }, beforeAssessment,
+    originalWords: words, interpretation, storedChoice: outcome,
+    savedValues: reopened.saved.map(x => ({ fieldId: x.fieldId, text: x.text, receipt: x.receipt })),
+    preview: { original: '[]', replacement: '["devday:workshop"]', sourceChangedAtPreview: false },
+    ownerCorrection, sourceReadbackSha256: contentDigest(fs.readFileSync(sourceFile, 'utf8')),
+    reopenedSame: true, pauseRecoveryPreserved: true, unconfirmedInterpretationSaveRefused: true,
+    duplicateSaveNoAdditionalEffect: true, sourceDriftWriteRefused: ownerCorrection,
+    afterGraph: { ok: after.ok, nodes: after.nodes.length, edges: after.edges.length }, afterAssessment,
+    baselinePlanPreserved: true,
+    gaps: ['Public native typed finding contribution/caller/disposition closure and host',
+      'Native guided authoring entry and measured keyboard/focus/undo/recovery', 'Real-source and participant acceptance'],
+    fullKnowledgeHealthJourneyQualified: false, humanAcceptance: false,
+  };
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const destination = process.argv[2], outcome = process.argv[3] ?? 'revision';
+  if (!destination) throw Error('Usage: node installed-workshop.mjs NEW_DISPOSABLE_DIRECTORY [note|disagreement|perspective-only|pause|revision]');
+  console.log(JSON.stringify(await rehearseInstalledWorkshop(destination, { outcome }), null, 2));
+}

package/src/knowledge/plan.mjs

@@ -0,0 +1,67 @@
+import fs from 'node:fs'
+import { createHash } from 'node:crypto'
+import { validateJsonSchema } from '../export/atelier-export-contract.mjs'
+
+const schema = JSON.parse(fs.readFileSync(new URL('../../templates/knowledge-workspace/knowledge-plan.schema.json', import.meta.url), 'utf8'))
+export const digest = (bytes) => createHash('sha256').update(bytes).digest('hex')
+export const contextEligible = node => node.extension === 'md' && node.classification !== 'unclassified' && node.status === 'active'
+
+export function validateKnowledgePlan(plan) {
+  const errors = validateJsonSchema(schema, plan)
+  if (errors.length) return errors
+  const unique = (values, label) => {
+    if (new Set(values).size !== values.length) errors.push(`duplicate ${label}`)
+  }
+  unique(plan.concepts.map(x => x.id), 'concept id')
+  unique(plan.concepts.map(x => x.tag), 'concept tag')
+  unique(plan.relations.map(x => x.id), 'relation id')
+  unique(plan.relations.map(x => JSON.stringify([x.predicate, x.from, x.to])), 'native relation mapping; use an assertion record for distinct meanings')
+  unique(plan.questions.map(x => x.id), 'question id')
+  const concepts = new Set(plan.concepts.map(x => x.id))
+  const relations = new Set(plan.relations.map(x => x.id))
+  for (const relation of plan.relations) {
+    if (!concepts.has(relation.from) || !concepts.has(relation.to)) errors.push(`relation ${relation.id} references an unknown concept`)
+  }
+  for (const question of plan.questions) {
+    if (question.concepts.some(x => !concepts.has(x))) errors.push(`question ${question.id} references an unknown concept`)
+    if (question.relations.some(x => !relations.has(x))) errors.push(`question ${question.id} references an unknown relation`)
+    unique(question.expectedEvidence.map(x => x.id), `evidence id for ${question.id}`)
+    if ((question.expect === 'abstain') !== (question.expectedEvidence.length === 0)) errors.push(`question ${question.id} needs evidence for evidence, and none for abstain`)
+  }
+  return errors
+}
+
+export function inspectKnowledgePlan(plan, graph) {
+  const errors = validateKnowledgePlan(plan)
+  if (errors.length) return { ok: false, errors, warnings: [] }
+  errors.push(...graph.errors)
+  const warnings = []
+  const knownTags = new Set(plan.concepts.map(c => c.tag))
+  for (const node of graph.nodes) {
+    if (node.tags.some(tag => tag.startsWith('concept:') && !knownTags.has(tag))) warnings.push(`record ${node.id} uses a concept tag absent from the plan`)
+  }
+  const members = new Map(plan.concepts.map(c => [c.id, graph.nodes.filter(n => n.tags.includes(c.tag))]))
+  const concepts = plan.concepts.map(c => {
+    const usedBy = plan.questions.filter(q => q.concepts.includes(c.id)).map(q => q.id)
+    if (!usedBy.length) warnings.push(`concept ${c.id} supports no question; remove it or explain its useful work`)
+    if (!members.get(c.id).length) warnings.push(`concept ${c.id} has no source records`)
+    const eligibleRecords = members.get(c.id).filter(contextEligible).length
+    if (!eligibleRecords) warnings.push(`concept ${c.id} has no context-eligible source records`)
+    return { id: c.id, records: members.get(c.id).length, eligibleRecords, questions: usedBy }
+  })
+  const relations = plan.relations.map(r => {
+    const from = new Set(members.get(r.from).map(n => n.id))
+    const to = new Set(members.get(r.to).map(n => n.id))
+    const matches = graph.edges.filter(e => e.declared && e.type === r.predicate && from.has(e.source) && to.has(e.target))
+    const eligibleFrom = new Set(members.get(r.from).filter(contextEligible).map(n => n.id))
+    const eligibleTo = new Set(members.get(r.to).filter(contextEligible).map(n => n.id))
+    const eligibleMatchingEdges = matches.filter(e => eligibleFrom.has(e.source) && eligibleTo.has(e.target)).length
+    if (!matches.length) warnings.push(`relation ${r.id} has no declared edge in the required direction`)
+    if (!eligibleMatchingEdges) warnings.push(`relation ${r.id} has no context-eligible declared edge in the required direction`)
+    if (!plan.questions.some(q => q.relations.includes(r.id))) warnings.push(`relation ${r.id} supports no question`)
+    return { id: r.id, matchingEdges: matches.length, eligibleMatchingEdges }
+  })
+  return { ok: errors.length === 0, status: errors.length ? 'invalid' : warnings.length ? 'needs-attention' : 'structurally-valid', errors, warnings, concepts, relations,
+    unclassifiedRecords: graph.nodes.filter(n => n.classification === 'unclassified').length,
+    assurance: 'Structure and coverage only; definitions, source rights, meaning, and usefulness require human review.' }
+}

package/src/knowledge/projection.mjs

@@ -0,0 +1,43 @@
+import { inspectKnowledge } from './ledger.mjs'
+import { harnessDigest, harnessRef, restrictiveAudience } from '../harnesses/contracts.mjs'
+import { reconcileKnowledge } from '../harnesses/exchange.mjs'
+export function knowledgeGraphProposal(records, { namespace, activationId, dependencySnapshots = [] }) {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(namespace ?? '')) throw new Error('invalid graph namespace')
+  const state = inspectKnowledge(records), byId = new Map(records.map(r => [r.id, r]))
+  const activation = byId.get(activationId)
+  const reconciliation = reconcileKnowledge(records, { dependencySnapshots })
+  if (activation?.kind !== 'activation' || reconciliation.reconsider.some(r => r.id === activationId)) throw new Error('graph proposal requires a current activation record and input snapshots')
+  const accepted = new Set(state.accepted), selected = new Map(), claims = []
+  function include(id) {
+    if (selected.has(id)) return
+    if (!accepted.has(id)) throw new Error('graph dependency lacks current acceptance')
+    const r = byId.get(id); selected.set(id, r)
+    if (r.kind === 'relation') { include(r.data.subject.id); include(r.data.object.id) }
+    else for (const pin of r.data.basedOn) include(pin.contribution.id)
+  }
+  for (const pin of activation.data.reviews) include(byId.get(pin.id).data.target.id)
+  const node = id => `${namespace}:knowledge-${state.establishment.id}-${id}`
+  function edge(subject, predicate, object, supportingRecords = []) {
+    const claim = { schema: 'atelier-claim@v1', claimId: `claim:knowledge-${harnessDigest([node(subject), predicate, node(object)]).slice(7)}`, subject: node(subject), predicate, object: node(object), provider: 'script', status: 'proposed', promoted: false, evidence: [harnessDigest(byId.get(subject)), harnessDigest(byId.get(object))] }
+    const existing = claims.find(c => c.claimId === claim.claimId)
+    if (!existing) claims.push(claim)
+    const selectedClaim = existing ?? claim
+    selectedClaim.evidence = [...new Set([...selectedClaim.evidence, ...supportingRecords.map(harnessDigest)])]
+    return selectedClaim.claimId
+  }
+  const files = []
+  for (const record of selected.values()) {
+    const d = record.data, domain = byId.get(d.domain.id)
+    const review = records.findLast(r => r.kind === 'review' && r.data.target.id === record.id)
+    let title = d.title, audience = record.kind === 'contribution' ? restrictiveAudience(d.audience, domain.data.audience) : domain.data.audience, evidence = { contribution: record }
+    if (record.kind === 'relation') {
+      const claimId = edge(d.subject.id, domain.data.vocabulary.relations.find(r => r.id === d.predicate).graphPredicate, d.object.id, [record, review])
+      title = `Relation: ${d.predicate}`; audience = domain.data.audience
+      evidence = { relation: record, claimId }
+    } else for (const pin of d.basedOn) edge(pin.contribution.id, 'evidences', record.id)
+    const text = JSON.stringify({ ...evidence, domain, record: harnessRef(record), review, evaluations: review.data.evaluations.map(pin => byId.get(pin.id)), activation: harnessRef(activation), semanticTruthVerified: false }, null, 2)
+    const fence = '`'.repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map(m => m[0].length + 1)))
+    files.push({ path: `${record.id}.md`, content: ['---', `title: ${JSON.stringify(title)}`, 'kg:', `  id: ${JSON.stringify(node(record.id))}`, '  type: "document"', '  status: "draft"', `  audience: ${JSON.stringify(audience)}`, '  relations: {}', '---', '', 'Proposed knowledge source. Review the destination and admission before applying.', '', `${fence}text`, text, fence, ''].join('\n') })
+  }
+  return { schema: 'atelier-knowledge-graph-proposal@v1', historyDigest: state.head, activation: harnessRef(activation), purpose: activation.data.purpose, questions: activation.data.questions, files, claims, reconsider: reconciliation.reconsider, canonicalMutation: false, authority: 'none' }
+}