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

package/src/graph-view/structured/browser.mjs

@@ -0,0 +1,262 @@
+import { structuredStyles } from './styles.mjs'
+import { refKey } from '../refs.mjs'
+import { assertGraphViewIntent } from '../intents.mjs'
+
+const sameRef = (a, b) => Boolean(a && b && a.repoId === b.repoId && a.localId === b.localId)
+const identity = ref => ({ repoId: ref.repoId, localId: ref.localId })
+const refText = ref => `${ref.repoId} / ${ref.localId}`
+const locatorText = locator => Object.entries(locator).map(([key, value]) => `${key}: ${typeof value === 'object' ? Object.entries(value).map(([name, number]) => `${name}=${number}`).join(', ') : value}`).join('; ')
+const mounts = new WeakSet()
+let nextMountId = 1
+
+// A presentation consumer, never an authorization boundary. The host must deliver
+// a validated reader-specific slice and remove it immediately on grant loss.
+export function mountStructuredGraphView(root, { view = null, selection = null, refreshStatus = null, onIntent, onPage } = {}) {
+  if (!root?.ownerDocument || mounts.has(root)) throw new TypeError('structured graph root unavailable')
+  if (typeof onIntent !== 'function') throw new TypeError('structured graph requires an intent host')
+  mounts.add(root)
+  const doc = root.ownerDocument
+  const prefix = `agv-${nextMountId++}`
+  let current = null, selected = null, currentRefreshStatus = null, query = '', disposed = false, epoch = 0, request = 0
+  let ui, roving = null
+  const make = (tag, text, attrs = {}) => {
+    const element = doc.createElement(tag)
+    if (text !== null) element.textContent = text
+    for (const [name, value] of Object.entries(attrs)) element.setAttribute(name, String(value))
+    return element
+  }
+  const append = (parent, ...children) => { parent.append(...children); return parent }
+  const paragraph = (parent, text, className) => parent.append(make('p', text, className ? { class: className } : {}))
+  const heading = (parent, text) => parent.append(make('h3', text))
+  const fields = (parent, values) => {
+    const list = make('dl', null)
+    for (const [label, value] of values) append(list, make('dt', label), make('dd', value === undefined || value === null ? 'Not supplied' : String(value)))
+    parent.append(list)
+  }
+  const source = (parent, sourceRef, title = 'Exact source') => {
+    parent.append(make('h4', title))
+    if (!sourceRef) { paragraph(parent, 'Source pin not supplied.'); return }
+    fields(parent, [['Repository', sourceRef.repoId], ['Path', sourceRef.path], ['Revision', sourceRef.revision], ['Content digest', sourceRef.digest], ['Locator', sourceRef.locator ? locatorText(sourceRef.locator) : 'Whole source; no narrower locator supplied']])
+  }
+  const explicit = value => value === undefined || value === null ? 'Not supplied' : typeof value === 'string' ? value : JSON.stringify(value)
+  const button = (text, key, intent, pressed) => {
+    const control = make('button', text, { type: 'button', 'data-agv-key': key })
+    if (typeof pressed === 'boolean') control.setAttribute('aria-pressed', String(pressed))
+    control.addEventListener('click', () => emit(intent))
+    return control
+  }
+  const emit = async intent => {
+    if (disposed || !current) return
+    const digest = current.projectionDigest, revision = epoch, id = ++request
+    ui.status.textContent = 'Selection request sent. Awaiting host.'
+    try {
+      await onIntent(assertGraphViewIntent(current, { ...intent, projectionDigest: digest }))
+      if (!disposed && epoch === revision && id === request) ui.status.textContent = 'Request delivered.'
+    } catch {
+      if (!disposed && epoch === revision && id === request) ui.status.textContent = 'Request failed. Try again.'
+    }
+  }
+  const nodeFor = ref => current.nodes.find(node => sameRef(node.ref, ref))
+  const edgeFor = edgeId => current.edges.find(edge => edge.edgeId === edgeId)
+  const evidenceFor = id => current.evidence.find(item => item.evidenceId === id)
+  const evidencePin = (parent, evidenceId, title) => {
+    const item = evidenceFor(evidenceId)
+    if (!item) throw new TypeError('evidence pin unavailable')
+    source(parent, item.sourceRef, title)
+    fields(parent, [['Evidence identity', item.evidenceId], ['Support verification', item.verification]])
+    parent.append(button('Inspect evidence', `open:${title}:${evidenceId}`, { type: 'openEvidence', evidenceId }))
+  }
+  const labelFor = ref => nodeFor(ref)?.title ?? refText(ref)
+  const nodeButton = (ref, suffix) => button(labelFor(ref), `ref:${refKey(ref)}:${suffix}`, { type: 'select', ref: identity(ref) }, sameRef(selected?.ref, ref))
+  const shell = () => {
+    root.replaceChildren()
+    const style = make('style', structuredStyles)
+    ui = { host: make('div', null, { class: 'agv' }) }
+    append(root, style, ui.host)
+    append(ui.host, make('h2', 'Knowledge explorer'), make('a', 'Skip to evidence inspector', { class: 'agv-skip', href: `#${prefix}-inspector` }))
+    paragraph(ui.host, 'Search records, follow directed relationships, and inspect the exact evidence.')
+    ui.status = make('p', '', { class: 'agv-status', role: 'status', 'aria-live': 'polite', 'aria-atomic': 'true' })
+    ui.host.append(ui.status)
+    ui.content = make('div', null)
+    ui.host.append(ui.content)
+  }
+  const inspect = panel => {
+    if (!selected) { paragraph(panel, 'Choose a question, record, relationship, or evidence item.'); return }
+    if (selected.questionId) {
+      const question = current.questions.find(q => q.questionId === selected.questionId)
+      if (!question) return
+      panel.append(make('h4', question.title))
+      fields(panel, [['Decision', question.decision], ['Coverage', question.coverage], ['Omissions', question.omissionState]])
+      for (const gap of question.gaps ?? []) paragraph(panel, explicit(gap), 'agv-note')
+      if (question.coverage === 'abstain') paragraph(panel, 'The sources do not establish an answer.', 'agv-note')
+      if (question.nodeRefs?.length) { panel.append(make('h4', 'Related records')); for (const ref of question.nodeRefs) panel.append(nodeButton(ref, 'question')) }
+      for (const [label, refs] of [['Supporting evidence', question.evidenceRefs], ['Contradicting evidence', question.contradictingRefs]]) {
+        panel.append(make('h4', label))
+        if (!refs?.length) paragraph(panel, 'None supplied in this view.')
+        else for (const evidenceId of refs) panel.append(button(`Inspect ${evidenceFor(evidenceId)?.sourceRef.path ?? 'evidence'}`, `evidence:${evidenceId}`, { type: 'openEvidence', evidenceId }))
+      }
+    } else if (selected.edgeId) {
+      const edge = edgeFor(selected.edgeId)
+      if (!edge) return
+      panel.append(make('h4', `${labelFor(edge.source)} → ${edge.predicate} → ${labelFor(edge.target)}`))
+      fields(panel, [['Relationship identity', edge.edgeId], ['Direction', `${refText(edge.source)} → ${refText(edge.target)}`], ['Predicate', edge.predicate], ['Family', edge.family], ['Acceptance', edge.acceptanceState], ['Assurance', edge.assurance], ['Review receipts', edge.reviewRefs?.join(', ') || 'None supplied in this view'], ['Staleness', edge.staleness ?? (currentRefreshStatus?.stale ? 'Displayed source view is stale; edge currency not supplied' : 'Not supplied; do not assume current')], ['Verification checked at', edge.verification?.checkedAt], ['Record digest', edge.recordDigest], ['Policy digest', edge.policyDigest], ['Qualifications', edge.qualifications?.join('; ') || 'None supplied in this view']])
+      evidencePin(panel, edge.sourceRef, 'Relationship origin')
+      panel.append(make('h4', 'Support'))
+      if (!edge.supportRefs?.length) paragraph(panel, 'No support pins supplied.')
+      for (const id of edge.supportRefs ?? []) evidencePin(panel, id, 'Supporting source')
+      append(panel, nodeButton(edge.source, 'from'), nodeButton(edge.target, 'to'))
+    } else if (selected.evidenceId) {
+      const evidence = current.evidence.find(e => e.evidenceId === selected.evidenceId)
+      if (!evidence) return
+      panel.append(make('h4', evidence.title ?? evidence.evidenceId))
+      fields(panel, [['Evidence identity', evidence.evidenceId], ['Verification', explicit(evidence.verification)]])
+      source(panel, evidence.sourceRef)
+    } else if (selected.ref) {
+      const node = nodeFor(selected.ref)
+      if (!node) return
+      panel.append(make('h4', node.title))
+      if (node.summary) paragraph(panel, node.summary)
+      fields(panel, [['Record identity', refText(node.ref)], ['Source kind', node.sourceKind], ['Classification', node.classification], ['Lifecycle', node.lifecycle], ['Tags', node.tags?.join(', ') || 'None']])
+      source(panel, node.sourceRef)
+      const tools = make('div', null, { class: 'agv-tools' })
+      for (const [direction, label] of current.capabilities?.queries.includes('neighborhood') ? [['out', 'outgoing'], ['in', 'incoming'], ['both', 'both directions']] : []) tools.append(button(`Explore ${label}`, `expand:${direction}`, { type: 'expand', ref: identity(node.ref), direction }))
+      panel.append(tools)
+      const related = current.edges.filter(edge => sameRef(edge.source, node.ref) || sameRef(edge.target, node.ref))
+      panel.append(make('h4', 'Relationships in this view'))
+      if (!related.length) paragraph(panel, 'No relationships in this view.')
+      for (const edge of related) panel.append(button(`${labelFor(edge.source)} → ${edge.predicate} → ${labelFor(edge.target)}`, `inspect:${edge.edgeId}`, { type: 'select', edgeId: edge.edgeId }))
+    }
+  }
+  const render = ({ restore = true } = {}) => {
+    const active = root.contains(doc.activeElement) ? doc.activeElement : null
+    const focusKey = active?.getAttribute('data-agv-key')
+    const textRange = active?.tagName === 'INPUT' ? [active.selectionStart, active.selectionEnd] : null
+    ui.content.replaceChildren()
+    if (!current) { paragraph(ui.content, 'No graph view available.'); return }
+    const info = make('p', `Projection ${current.projectionDigest}`, { class: 'agv-ref' })
+    ui.content.append(info)
+    if (currentRefreshStatus?.stale) paragraph(ui.content, 'The displayed source view is stale. Rebuild the view before relying on it.', 'agv-note')
+    if (currentRefreshStatus?.failure) paragraph(ui.content, 'The view could not be refreshed. Inspect the source and retry through the host.', 'agv-note')
+    if (current.page?.truncated) {
+      const omitted = Object.entries(current.page.omitted ?? {}).filter(([, count]) => count > 0).map(([kind, count]) => `${count} ${kind}`).join(', ')
+      paragraph(ui.content, `This is a bounded view.${omitted ? ` Omitted from this view: ${omitted}.` : ''}`, 'agv-note')
+      if (current.page.nextCursor && typeof onPage === 'function') {
+        const more = make('button', 'Load next page', { type: 'button', 'data-agv-key': 'next-page' })
+        const pageRequest = Object.freeze({ projectionDigest: current.projectionDigest, cursor: current.page.nextCursor })
+        more.addEventListener('click', async () => {
+          if (disposed || !current || current.projectionDigest !== pageRequest.projectionDigest) return
+          const revision = epoch
+          try { await onPage(pageRequest) } catch { if (!disposed && epoch === revision) ui.status.textContent = 'Next page unavailable. Try again.' }
+        })
+        ui.content.append(more)
+      } else paragraph(ui.content, 'Ask the host for a broader view to inspect omitted results.')
+    }
+    const questions = make('section', null, { 'aria-label': 'Questions' })
+    heading(questions, 'Questions')
+    const qlist = make('ul', null, { class: 'agv-questions' })
+    for (const q of current.questions) qlist.append(append(make('li', null), button(`${q.title} · ${q.coverage}`, `question:${q.questionId}`, { type: 'setQuestion', questionId: q.questionId }, selected?.questionId === q.questionId)))
+    if (!current.questions.length) paragraph(questions, 'No questions in this view.')
+    questions.append(qlist); ui.content.append(questions)
+    const grid = make('div', null, { class: 'agv-grid' })
+    const records = make('section', null, { 'aria-label': 'Records' })
+    heading(records, 'Records')
+    const inputId = `${prefix}-search`, label = make('label', 'Search this view', { for: inputId })
+    const input = make('input', null, { id: inputId, type: 'search', 'data-agv-key': 'search', 'aria-describedby': `${prefix}-search-hint` })
+    input.value = query
+    const search = () => { query = input.value; const matches = render(); ui.status.textContent = `${matches} records in this view match.` }
+    input.addEventListener('input', event => { if (!event.isComposing) search() })
+    input.addEventListener('compositionend', search)
+    append(records, label, input, make('p', 'Search is limited to the records delivered in this view. Arrow keys move focus through the record list; Enter or Space selects.', { id: `${prefix}-search-hint` }))
+    const normalized = query.trim().toLocaleLowerCase()
+    const visible = current.nodes.filter(node => [node.title, node.summary, node.ref.repoId, node.ref.localId, ...(node.tags ?? [])].join(' ').toLocaleLowerCase().includes(normalized))
+    const count = make('p', `${visible.length} records in this view match.`)
+    records.append(count)
+    const list = make('ul', null, { class: 'agv-records', 'aria-label': 'Record search results' })
+    const buttons = []
+    if (!visible.some(node => refKey(node.ref) === roving)) roving = visible[0] ? refKey(visible[0].ref) : null
+    for (const node of visible) {
+      const control = nodeButton(node.ref, 'list')
+      control.tabIndex = refKey(node.ref) === roving ? 0 : -1
+      control.addEventListener('focus', () => { roving = refKey(node.ref); for (const b of buttons) b.tabIndex = b === control ? 0 : -1 })
+      control.append(make('small', `${node.sourceKind} · ${refText(node.ref)}`))
+      buttons.push(control); list.append(append(make('li', null), control))
+    }
+    list.addEventListener('keydown', event => {
+      const index = buttons.indexOf(doc.activeElement)
+      if (index < 0 || !['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return
+      event.preventDefault()
+      const next = event.key === 'Home' ? 0 : event.key === 'End' ? buttons.length - 1 : Math.max(0, Math.min(buttons.length - 1, index + (event.key === 'ArrowDown' ? 1 : -1)))
+      buttons[next]?.focus()
+    })
+    records.append(list)
+    if (!visible.length) paragraph(records, 'No matching records in this view.')
+    const panel = make('aside', null, { id: `${prefix}-inspector`, tabindex: '-1', 'aria-label': 'Evidence inspector' })
+    heading(panel, 'Evidence inspector'); inspect(panel)
+    append(grid, records, panel); ui.content.append(grid)
+    const relationships = make('section', null, { 'aria-label': 'Directed relationships' })
+    heading(relationships, 'Directed relationships')
+    const scroll = make('div', null, { class: 'agv-table', tabindex: '0', role: 'region', 'aria-label': 'Directed relationship table, scroll horizontally if needed' })
+    const table = make('table', null), head = make('thead', null), tr = make('tr', null), body = make('tbody', null)
+    table.append(make('caption', 'Direction runs from source, through predicate, to target.'))
+    for (const name of ['Source', 'Predicate', 'Target', 'Review and support']) tr.append(make('th', name, { scope: 'col' }))
+    head.append(tr); table.append(head)
+    for (const edge of current.edges) {
+      const row = make('tr', null)
+      append(row, append(make('td', null), nodeButton(edge.source, `table-source:${edge.edgeId}`)), append(make('td', null), button(edge.predicate, `edge:${edge.edgeId}`, { type: 'select', edgeId: edge.edgeId }, selected?.edgeId === edge.edgeId)), append(make('td', null), nodeButton(edge.target, `table-target:${edge.edgeId}`)), make('td', `${edge.assurance} · ${edge.acceptanceState} · ${edge.supportRefs?.length ?? 0} support pins · ${edge.reviewRefs?.length ?? 0} review receipts`))
+      body.append(row)
+    }
+    table.append(body); scroll.append(table); relationships.append(scroll)
+    if (!current.edges.length) paragraph(relationships, 'No directed relationships in this view.')
+    ui.content.append(relationships)
+    const diagnostics = make('section', null, { 'aria-label': 'Diagnostics' })
+    heading(diagnostics, 'Diagnostics')
+    for (const item of current.diagnostics ?? []) {
+      paragraph(diagnostics, `${item.severity}: ${item.code}. ${item.action}`, 'agv-note')
+      for (const ref of item.nodeRefs) diagnostics.append(nodeButton(ref, `diagnostic:${item.diagnosticId}`))
+      for (const evidenceId of item.evidenceRefs) diagnostics.append(button('Inspect diagnostic evidence', `diagnostic:${item.diagnosticId}:${evidenceId}`, { type: 'openEvidence', evidenceId }))
+    }
+    if (!current.diagnostics?.length) paragraph(diagnostics, 'No diagnostics supplied in this view.')
+    ui.content.append(diagnostics)
+    if (restore && focusKey) {
+      const replacement = [...root.querySelectorAll('[data-agv-key]')].find(element => element.getAttribute('data-agv-key') === focusKey)
+      if (replacement) { replacement.focus({ preventScroll: true }); if (textRange) replacement.setSelectionRange(...textRange) }
+      else panel.focus({ preventScroll: true })
+    }
+    return visible.length
+  }
+  const update = ({ view: nextView = null, selection: nextSelection = null, refreshStatus: nextRefreshStatus } = {}) => {
+    if (disposed) throw new TypeError('structured graph disposed')
+    ++epoch; ++request
+    const previousDigest = current?.projectionDigest, previousRefreshStatus = currentRefreshStatus
+    currentRefreshStatus = null
+    // Clear the prior bytes before accepting a replacement; never keep a stale
+    // authorized snapshot after the host withdraws or rejects delivery.
+    current = null; selected = null
+    if (nextView === null) { query = ''; roving = null; render(); ui.status.textContent = 'Graph view cleared.'; return }
+    try {
+      if (nextView.schema !== 'atelier.graph-view@v1' || !/^sha256:[a-f0-9]{64}$/.test(nextView.projectionDigest ?? '') || !Array.isArray(nextView.nodes) || !Array.isArray(nextView.edges) || !Array.isArray(nextView.questions) || !Array.isArray(nextView.evidence) || nextView.nodes.length > 500 || nextView.edges.length > 2000 || nextView.evidence.length > 4000 || nextView.questions.length > 100) throw new TypeError()
+      current = structuredClone(nextView)
+      currentRefreshStatus = nextRefreshStatus === undefined ? (previousDigest === current.projectionDigest ? previousRefreshStatus : null) : nextRefreshStatus === null ? null : { stale: nextRefreshStatus.stale === true, failure: Boolean(nextRefreshStatus.failure) }
+      if (nextSelection?.projectionDigest === current.projectionDigest) {
+        const keys = ['ref', 'edgeId', 'evidenceId', 'questionId'].filter(key => nextSelection[key] !== undefined)
+        const available = keys.length === 1 && (keys[0] === 'ref' ? nodeFor(nextSelection.ref) :
+          keys[0] === 'edgeId' ? edgeFor(nextSelection.edgeId) :
+            keys[0] === 'evidenceId' ? current.evidence.find(e => e.evidenceId === nextSelection.evidenceId) :
+              current.questions.find(q => q.questionId === nextSelection.questionId))
+        if (available) selected = structuredClone(nextSelection)
+      }
+      render()
+      ui.status.textContent = selected ? 'Selection updated.' : 'Graph view ready.'
+    } catch {
+      current = null; selected = null; currentRefreshStatus = null; query = ''; roving = null
+      render(); ui.status.textContent = 'Graph view unavailable.'
+      throw new TypeError('invalid structured graph view')
+    }
+  }
+  shell()
+  try { update({ view, selection, refreshStatus }) } catch (error) { mounts.delete(root); root.replaceChildren(); throw error }
+  return Object.freeze({ update, clear: () => update({ view: null }), destroy: () => {
+    if (disposed) return
+    disposed = true; ++epoch; ++request; current = null; selected = null; currentRefreshStatus = null; query = ''; root.replaceChildren(); mounts.delete(root)
+  } })
+}

package/src/graph-view/structured/styles.mjs

@@ -0,0 +1,8 @@
+// Scope every rule to the mounted view; no global host styles or animation.
+export const structuredStyles = `
+.agv{color:#172b2a;background:#f6f8f5;font:1rem/1.55 system-ui,sans-serif;padding:clamp(.75rem,2vw,2rem);border:1px solid #657672;border-radius:.75rem;container-type:inline-size}
+.agv *{box-sizing:border-box;min-width:0}.agv h2,.agv h3,.agv p{margin:0 0 .75rem}.agv h2{font-size:1.65rem;line-height:1.2}.agv h3{font-size:1.15rem}.agv h4{margin:1rem 0 .5rem}.agv button,.agv input,.agv select{font:inherit;color:inherit;background:#fff;border:1px solid #657672;border-radius:.35rem;min-height:2.75rem;padding:.5rem .75rem;max-width:100%}.agv button{cursor:pointer;text-align:start;overflow-wrap:anywhere}.agv button:disabled{cursor:default}.agv button[aria-pressed=true]{background:#d5e9e1;border:2px solid #154e40;font-weight:700}.agv :focus-visible{outline:3px solid #7029aa;outline-offset:3px}.agv label{display:block;font-weight:650;margin-bottom:.35rem}.agv input{width:100%}.agv section,.agv aside{background:#fff;padding:1rem;border:1px solid #b0bdb8;border-radius:.5rem;margin-block:1rem}.agv .agv-grid{display:grid;gap:1rem;grid-template-columns:minmax(0,1fr) minmax(0,1fr)}.agv .agv-grid section{margin:0}.agv ul{padding-inline-start:1.3rem}.agv .agv-records,.agv .agv-questions{list-style:none;padding:0;display:grid;gap:.5rem}.agv .agv-records button,.agv .agv-questions button{width:100%}.agv small{display:block;color:#405951}.agv .agv-tools{display:flex;flex-wrap:wrap;gap:.5rem;margin-block:.75rem}.agv .agv-table{overflow:auto;max-width:100%;border:1px solid #b0bdb8}.agv table{border-collapse:collapse;width:100%;min-width:32rem}.agv caption{text-align:start;font-weight:650;padding:.5rem}.agv th,.agv td{text-align:start;vertical-align:top;border-bottom:1px solid #b0bdb8;padding:.65rem;overflow-wrap:anywhere}.agv th{background:#edf3ef}.agv dt{font-weight:650}.agv dd{margin:0 0 .65rem;overflow-wrap:anywhere}.agv .agv-note{border-inline-start:4px solid #6b5132;padding-inline-start:.75rem}.agv .agv-status{min-height:1.55em}.agv .agv-ref{font-family:ui-monospace,monospace;font-size:.85em;overflow-wrap:anywhere}.agv .agv-skip{display:inline-block;padding:.5rem;min-height:2.75rem;color:inherit}.agv .agv-badge{font-weight:650}.agv [hidden]{display:none!important}
+@container (max-width:48rem){.agv .agv-grid{grid-template-columns:minmax(0,1fr)}}
+@media (prefers-reduced-motion:reduce){.agv,.agv *{animation:none!important;transition:none!important;scroll-behavior:auto!important}}
+@media (forced-colors:active){.agv,.agv section,.agv aside,.agv input,.agv button,.agv select{background:Canvas;color:CanvasText;border-color:CanvasText}.agv button[aria-pressed=true]{border:3px double Highlight}.agv small{color:CanvasText}.agv :focus-visible{outline-color:Highlight}}
+`

package/src/graph-workspace/authoring.mjs

@@ -0,0 +1,185 @@
+// Focused authoring for concepts and plan relations: one step at a time, with
+// structural guidance and a draft store behind an injected storage port.
+//
+// Guidance here is structural (empty, too short, name-only identity, example equals
+// near miss). It is not the Node ontology guide and says nothing about truth.
+// "ready-for-human-review" means complete and grounded in readable records; a person
+// decides. The store writes only to the storage it is given: browser storage for a
+// local draft, or a host port that records drafts durably for review.
+
+const article = word => (/^[aeiou]/i.test(word) ? 'an ' : 'a ') + word.toLowerCase()
+
+export function conceptSteps(concept) {
+  return [
+    { id: 'definition', label: 'Meaning', prompt: `What makes something ${article(concept.title)}?`, help: 'One sentence. Say what it is distinct from.' },
+    { id: 'identityRule', label: 'Same one?', prompt: 'How do you recognise the same one twice?', help: 'Similar names alone do not establish identity.' },
+    { id: 'example', label: 'Example', prompt: 'One concrete example from your own work.', help: 'A real case you could point to.' },
+    { id: 'nearMiss', label: 'Near miss', prompt: 'A close example that must stay separate.', help: 'The case people most often confuse with it.' },
+    { id: 'evidence', label: 'Evidence', prompt: 'Which records ground this distinction?', help: 'Cite records you have looked at. Citing does not make them members.', kind: 'evidence' },
+    { id: 'disconfirming', label: 'Prove wrong', prompt: 'What observation would show this distinction does not hold?', help: 'Name it now so you would notice it later.' },
+  ]
+}
+
+export function relationSteps(relation, titleOf = id => id) {
+  const verb = relation.predicate.replaceAll('_', ' ')
+  return [
+    { id: 'meaning', label: 'Meaning', prompt: `What does “${verb}” claim here?`, help: 'Say what the relation lets you check, not that it proves anything.' },
+    { id: 'forward', label: 'Forward', prompt: `Read it from ${titleOf(relation.from)} to ${titleOf(relation.to)}.`, help: `Start with “${titleOf(relation.from)}…”` },
+    { id: 'reverse', label: 'Reverse', prompt: `Read it from ${titleOf(relation.to)} back to ${titleOf(relation.from)}.`, help: 'The same claim from the other end. It creates no inverse relation.' },
+    { id: 'evidence', label: 'Evidence', prompt: 'Which records show this relation at work?', help: 'Cite records you have looked at. Citing does not create the relation.', kind: 'evidence' },
+    { id: 'disconfirming', label: 'Prove wrong', prompt: 'What would show this relation does not hold?', help: 'One observation is enough.' },
+  ]
+}
+
+const nameOnly = t => /\b(name|title|label|called)\b/i.test(t) && !/\b(not|alone|never|only by|unless)\b/i.test(t)
+const fields = list => Object.fromEntries(list.map(k => [k, []]))
+const summarize = f => { const all = Object.values(f).flat(); return { fields: f, errors: all.filter(m => m.tone === 'error').length, warnings: all.filter(m => m.tone === 'warn').length } }
+
+export function guideConcept(concept, draft, readableIds = null) {
+  const f = fields(['definition', 'identityRule', 'example', 'nearMiss', 'evidence', 'disconfirming'])
+  const def = (draft.definition ?? '').trim()
+  if (!def) f.definition.push({ tone: 'error', text: 'Say what this is in one sentence.' })
+  else {
+    if (def.toLowerCase() === concept.title.toLowerCase()) f.definition.push({ tone: 'error', text: 'A definition should not just repeat the name.' })
+    if (def.length < 24) f.definition.push({ tone: 'warn', text: 'Add a boundary: what is it distinct from?' })
+    else if (!/\b(distinct|not|rather than|unlike|only|separate|excluding)\b/i.test(def)) f.definition.push({ tone: 'info', text: 'Naming what it is distinct from helps the next person apply it.' })
+  }
+  const rule = (draft.identityRule ?? '').trim()
+  if (!rule) f.identityRule.push({ tone: 'error', text: 'State how two records are recognised as the same one.' })
+  else if (nameOnly(rule)) f.identityRule.push({ tone: 'warn', text: 'Names alone do not establish identity. Say which event, place or id makes two the same.' })
+  if (!(draft.example ?? '').trim()) f.example.push({ tone: 'error', text: 'Add one concrete example.' })
+  const near = (draft.nearMiss ?? '').trim()
+  if (!near) f.nearMiss.push({ tone: 'error', text: 'Add a close example that must stay separate.' })
+  else if (near.toLowerCase() === (draft.example ?? '').trim().toLowerCase()) f.nearMiss.push({ tone: 'error', text: 'The near miss must differ from the example.' })
+  guideEvidence(f, draft, readableIds)
+  if (!(draft.disconfirming ?? '').trim()) f.disconfirming.push({ tone: 'error', text: 'Name one observation that would prove it wrong.' })
+  return summarize(f)
+}
+
+// Readiness promises completeness and grounding in readable records, so these block it.
+function guideEvidence(f, draft, readableIds) {
+  const evidence = draft.evidence ?? []
+  if (!evidence.length) f.evidence.push({ tone: 'error', text: 'Cite at least one record you have looked at.' })
+  if (readableIds) for (const b of evidence) if (!readableIds.has(b.id)) f.evidence.push({ tone: 'error', text: 'One cited record is not readable here. It cannot support a proposal made from this view.' })
+}
+
+export function guideRelation(draft, readableIds = null) {
+  const f = fields(['meaning', 'forward', 'reverse', 'evidence', 'disconfirming'])
+  const meaning = (draft.meaning ?? '').trim()
+  if (!meaning) f.meaning.push({ tone: 'error', text: 'Explain what this relation claims.' })
+  else if (/\b(proves?|guarantees?|always)\b/i.test(meaning)) f.meaning.push({ tone: 'warn', text: 'Avoid claiming proof; say what it lets you check.' })
+  if (!(draft.forward ?? '').trim()) f.forward.push({ tone: 'error', text: 'Write the forward reading.' })
+  const reverse = (draft.reverse ?? '').trim()
+  if (!reverse) f.reverse.push({ tone: 'error', text: 'Write the reverse reading.' })
+  else if (reverse.toLowerCase() === (draft.forward ?? '').trim().toLowerCase()) f.reverse.push({ tone: 'warn', text: 'Start the reverse reading from the other end.' })
+  guideEvidence(f, draft, readableIds)
+  if (!(draft.disconfirming ?? '').trim()) f.disconfirming.push({ tone: 'error', text: 'Name what would show it does not hold.' })
+  return summarize(f)
+}
+
+/** answered · plan (unchanged plan wording) · attention · deferred · open */
+export function stepState(value, guide = [], deferred = false, original) {
+  if (deferred) return 'deferred'
+  if (original !== undefined && typeof value === 'string' && value === original && value.trim()) return 'plan'
+  const answered = Array.isArray(value) ? value.length > 0 : !!value?.trim?.()
+  if (!answered) return 'open'
+  return guide.some(m => m.tone === 'error') ? 'attention' : 'answered'
+}
+
+/** Storage port shape: { getItem(key) → string|null, setItem(key, string), removeItem(key) }. */
+export function memoryStorage() {
+  const map = new Map()
+  return { getItem: k => map.get(k) ?? null, setItem: (k, v) => { map.set(k, String(v)) }, removeItem: k => { map.delete(k) } }
+}
+
+// Identifier-indexed state uses null-prototype records and own-property lookup,
+// so an id such as "constructor" or "__proto__" is just another key.
+const dict = () => Object.create(null)
+const own = (o, k) => Object.hasOwn(o, k) ? o[k] : undefined
+const str = v => typeof v === 'string' && v.length <= 20000
+const ID = v => typeof v === 'string' && v.length > 0 && v.length <= 512
+const restoreEvidence = list => Array.isArray(list) ? list.filter(b => b && ID(b.id)).slice(0, 200).map(b => ({ id: b.id, title: str(b.title) ? b.title : b.id, citedAt: str(b.citedAt) ? b.citedAt : null })) : []
+function restoreData(raw) {
+  const out = { concepts: dict(), relations: dict(), deferred: dict(), savedAt: null }
+  if (!raw || typeof raw !== 'object') return out
+  for (const [id, c] of Object.entries(raw.concepts ?? {})) {
+    if (!ID(id) || !c || typeof c !== 'object') continue
+    const d = { definition: '', identityRule: '', example: '', nearMiss: '', disconfirming: '', evidence: [] }
+    for (const k of ['definition', 'identityRule', 'example', 'nearMiss', 'disconfirming']) if (str(c[k])) d[k] = c[k]
+    d.evidence = restoreEvidence(c.evidence)
+    out.concepts[id] = d
+  }
+  for (const [id, r] of Object.entries(raw.relations ?? {})) {
+    if (!ID(id) || !r || typeof r !== 'object') continue
+    const d = { meaning: '', forward: '', reverse: '', disconfirming: '', evidence: [] }
+    for (const k of ['meaning', 'forward', 'reverse', 'disconfirming']) if (str(r[k])) d[k] = r[k]
+    d.evidence = restoreEvidence(r.evidence)
+    out.relations[id] = d
+  }
+  for (const [k, v] of Object.entries(raw.deferred ?? {})) if (ID(k) && v === true) out.deferred[k] = true
+  if (str(raw.savedAt)) out.savedAt = raw.savedAt
+  return out
+}
+
+/**
+ * Drafts behind a storage port. `identity` binds saved drafts to one workspace
+ * (and reader scope, where a host has one); a saved draft with another identity is
+ * never shown. `persistence` names where drafts live: 'tab', 'browser' or 'host'.
+ */
+export function createDraftStore({ storage = memoryStorage(), key, identity, persistence = 'tab', delayMs = 600, now = () => new Date().toISOString() }) {
+  if (typeof key !== 'string' || !key) throw new TypeError('A draft key is required')
+  if (!identity || typeof identity !== 'object' || typeof identity.workspace !== 'string' || !identity.workspace) throw new TypeError('A draft identity with a workspace id is required')
+  if (!['tab', 'browser', 'host'].includes(persistence)) throw new TypeError('persistence must be tab, browser or host')
+  const identityKey = JSON.stringify(Object.keys(identity).sort().map(k => [k, identity[k]]))
+  let data = restoreData(null)
+  let status = 'empty'
+  try {
+    const raw = storage.getItem(key)
+    if (raw) {
+      const envelope = JSON.parse(raw)
+      if (envelope?.schema === 'atelier.graph-workspace-draft@v1' && envelope.identity === identityKey) { data = restoreData(envelope.data); status = 'restored' }
+      else status = 'empty'
+    }
+  } catch { status = 'unavailable' }
+  let timer = null
+  const listeners = new Set()
+  const emit = () => listeners.forEach(fn => fn(status))
+  function flush() {
+    clearTimeout(timer); timer = null
+    try { data.savedAt = now(); storage.setItem(key, JSON.stringify({ schema: 'atelier.graph-workspace-draft@v1', identity: identityKey, data })); status = 'saved' } catch { status = 'unavailable' }
+    emit()
+  }
+  return {
+    get data() { return data },
+    get status() { return status },
+    persistence,
+    onStatus(fn) { listeners.add(fn); return () => listeners.delete(fn) },
+    concept(c) { if (!own(data.concepts, c.id)) data.concepts[c.id] = { definition: c.definition ?? '', identityRule: c.identityRule ?? '', example: '', nearMiss: '', disconfirming: '', evidence: [] }; return data.concepts[c.id] },
+    relation(r) { if (!own(data.relations, r.id)) data.relations[r.id] = { meaning: r.meaning ?? '', forward: '', reverse: '', disconfirming: '', evidence: [] }; return data.relations[r.id] },
+    conceptDraft(id) { return own(data.concepts, id) },
+    relationDraft(id) { return own(data.relations, id) },
+    defer(kind, id, step, value) { const k = `${kind}:${id}:${step}`; if (value) data.deferred[k] = true; else delete data.deferred[k]; this.changed() },
+    deferred(kind, id, step) { return own(data.deferred, `${kind}:${id}:${step}`) === true },
+    changed() { status = 'saving'; emit(); clearTimeout(timer); if (delayMs <= 0) flush(); else timer = setTimeout(flush, delayMs) },
+    flush,
+    discard() { clearTimeout(timer); try { storage.removeItem(key) } catch { /* ignore */ } data = restoreData(null); status = 'empty'; emit() },
+  }
+}
+
+/** ready-for-human-review requires every step complete, evidence cited and every citation readable here. */
+export function readiness(plan, store, readableIds) {
+  if (!(readableIds instanceof Set)) throw new TypeError('readiness needs the set of readable record ids')
+  const items = []
+  for (const c of plan?.concepts ?? []) {
+    const d = store.conceptDraft ? store.conceptDraft(c.id) : (Object.hasOwn(store.data.concepts, c.id) ? store.data.concepts[c.id] : undefined)
+    if (!d) continue
+    if (d.definition !== (c.definition ?? '') || d.identityRule !== (c.identityRule ?? '') || d.example || d.nearMiss || d.disconfirming || d.evidence?.length) items.push({ kind: 'concept', id: c.id, title: c.title, guide: guideConcept(c, d, readableIds) })
+  }
+  for (const r of plan?.relations ?? []) {
+    const d = store.relationDraft ? store.relationDraft(r.id) : (Object.hasOwn(store.data.relations, r.id) ? store.data.relations[r.id] : undefined)
+    if (!d) continue
+    if (d.meaning !== (r.meaning ?? '') || d.forward || d.reverse || d.disconfirming || d.evidence?.length) items.push({ kind: 'relation', id: r.id, title: r.id, guide: guideRelation(d, readableIds) })
+  }
+  const errors = items.reduce((n, i) => n + i.guide.errors, 0)
+  return { status: !items.length ? 'nothing-drafted' : errors ? 'needs-attention' : 'ready-for-human-review', items, errors }
+}