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

package/src/graph-workspace/model.mjs

@@ -0,0 +1,109 @@
+// Workspace model: the shared read model behind every graph-workspace room.
+//
+// Input is an Atelier knowledge graph (`mnstry.atelier-knowledge-graph@v1`) that a
+// host has already limited to what the reader may see, plus an optional knowledge
+// plan. Output is plain data the browser rooms can draw. This module reads no files,
+// grants nothing and infers no relation:
+// - zones come only from the owner's folder structure (a zone rule),
+// - concept membership comes only from a record's own `concept:<id>` tag,
+// - edges keep their declared direction and fall into three classes.
+
+const SCHEMA = 'mnstry.atelier-knowledge-graph@v1'
+export const EDGE_CLASSES = Object.freeze(['link', 'containment', 'relation'])
+
+/** `related` is a written link, `belongs_to` is folder containment, anything else is a declared relation. */
+export function edgeClass(type) {
+  if (type === 'related') return 'link'
+  if (type === 'belongs_to') return 'containment'
+  return 'relation'
+}
+
+const humanize = folder => folder.replace(/^[_\d-]+/, '').replace(/[-_]+/g, ' ').replace(/^\w/, c => c.toUpperCase()) || 'Other'
+
+export function validateZoneRule(rule = {}) {
+  const prefix = rule.prefix ?? ''
+  const depth = rule.depth ?? 1
+  if (typeof prefix !== 'string' || prefix.includes('..') || prefix.startsWith('/')) throw new TypeError('Zone rule prefix must be a relative path prefix')
+  if (!Number.isInteger(depth) || depth < 1 || depth > 4) throw new TypeError('Zone rule depth must be an integer from 1 to 4')
+  const labels = rule.labels ?? {}
+  if (typeof labels !== 'object' || Array.isArray(labels) || Object.values(labels).some(v => typeof v !== 'string' || v.length > 80)) throw new TypeError('Zone rule labels must map folders to short names')
+  return { prefix, depth, labels: Object.assign(Object.create(null), labels), rootLabel: typeof rule.rootLabel === 'string' ? rule.rootLabel.slice(0, 80) : 'Workspace root' }
+}
+
+/** The zone of records outside the folder rule. No folder id can be '/'. */
+export const ROOT_ZONE = '/'
+
+/** The owner-configured zone of a record path. Records outside the prefix share one root zone. */
+export function zoneOf(path, rule) {
+  const r = validateZoneRule(rule)
+  if (typeof path !== 'string' || !path.startsWith(r.prefix)) return { id: ROOT_ZONE, label: r.rootLabel }
+  const parts = path.slice(r.prefix.length).split('/')
+  if (parts.length <= r.depth) return { id: ROOT_ZONE, label: r.rootLabel }
+  const folder = parts.slice(0, r.depth).join('/')
+  return { id: folder, label: Object.hasOwn(r.labels, folder) ? r.labels[folder] : humanize(folder.split('/').at(-1)) }
+}
+
+export function buildWorkspaceModel({ graph, plan = null, zoneRule = {}, summaryLength = 280 }) {
+  if (graph?.schema !== SCHEMA || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) throw new TypeError('An Atelier knowledge graph v1 is required')
+  const rule = validateZoneRule(zoneRule)
+  const seenIds = new Set()
+  const nodes = graph.nodes.map(n => {
+    if (typeof n.id !== 'string' || !n.id || seenIds.has(n.id)) throw new TypeError('Knowledge graph node ids must be unique non-empty strings')
+    seenIds.add(n.id)
+    const zone = zoneOf(n.path ?? '', rule)
+    const tags = Array.isArray(n.tags) ? n.tags.filter(t => typeof t === 'string') : []
+    return {
+      id: n.id, title: typeof n.title === 'string' && n.title ? n.title : n.id,
+      summary: typeof n.summary === 'string' ? n.summary.split('\n')[0].slice(0, summaryLength) : '',
+      type: n.type ?? 'document', status: n.status ?? null, audience: n.audience ?? null, path: n.path ?? null,
+      tags: tags.filter(t => !t.startsWith('concept:')).slice(0, 8),
+      concepts: tags.filter(t => t.startsWith('concept:')).map(t => t.slice(8)),
+      zone: zone.id, zoneLabel: zone.label, degree: 0, relationDegree: 0,
+    }
+  })
+  const byId = new Map(nodes.map(n => [n.id, n]))
+  const edges = []
+  const seen = new Set()
+  let outside = 0
+  for (const e of graph.edges) {
+    if (!byId.has(e.source) || !byId.has(e.target)) { outside++; continue }
+    if (e.source === e.target) continue
+    const key = `${e.source}\u0000${e.target}\u0000${e.type}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const kind = edgeClass(e.type)
+    edges.push({ id: 'e' + edges.length, source: e.source, target: e.target, type: e.type, kind, declared: e.declared !== false })
+    for (const id of [e.source, e.target]) { const n = byId.get(id); n.degree++; if (kind === 'relation') n.relationDegree++ }
+  }
+  const counts = new Map()
+  for (const n of nodes) counts.set(n.zone, { id: n.zone, label: n.zoneLabel, count: (counts.get(n.zone)?.count ?? 0) + 1 })
+  const zones = [...counts.values()].sort((a, b) => b.count - a.count || (a.id < b.id ? -1 : 1)).map((z, index) => ({ ...z, index }))
+  return {
+    schema: 'atelier.graph-workspace-model@v1',
+    coverage: { records: nodes.length, links: edges.length, linksOutsideReadableSet: outside, byClass: Object.fromEntries(EDGE_CLASSES.map(k => [k, edges.filter(e => e.kind === k).length])) },
+    nodes, edges, zones,
+    plan: plan ? planModel(plan, nodes) : null,
+  }
+}
+
+function planModel(plan, nodes) {
+  const concepts = Array.isArray(plan.concepts) ? plan.concepts.filter(c => typeof c?.id === 'string') : []
+  const ids = new Set(concepts.map(c => c.id))
+  return {
+    purpose: typeof plan.purpose === 'string' ? plan.purpose : null,
+    concepts: concepts.map(c => ({
+      id: c.id, title: typeof c.title === 'string' ? c.title : c.id.replace(/-/g, ' ').replace(/^\w/, x => x.toUpperCase()),
+      definition: c.definition ?? '', identityRule: c.identityRule ?? '',
+      declaredBy: nodes.filter(n => n.concepts.includes(c.id)).map(n => n.id),
+    })),
+    relations: (plan.relations ?? []).filter(r => ids.has(r.from) && ids.has(r.to)).map(r => ({ id: r.id, predicate: r.predicate, from: r.from, to: r.to, meaning: r.meaning ?? '' })),
+    questions: (plan.questions ?? []).map(q => ({ id: q.id, question: q.question ?? q.title ?? q.id, concepts: (q.concepts ?? []).filter(id => ids.has(id)), relations: q.relations ?? [] })),
+  }
+}
+
+/** Neighbour ids of a record, in either direction, without duplicates. */
+export function neighbours(model, id) {
+  const out = new Set()
+  for (const e of model.edges) { if (e.source === id) out.add(e.target); else if (e.target === id) out.add(e.source) }
+  return [...out]
+}

package/src/graph-workspace/recipes.mjs

@@ -0,0 +1,88 @@
+// Work recipes, layered: Atelier ships defaults, a cohort coach adds or adjusts,
+// and the owner has the final say. A recipe is data that chooses the room, the lens
+// and the one primary action. Every resolved field records which layer set it.
+
+export const ROOMS = Object.freeze(['constellation', 'workbench', 'review'])
+export const LENSES = Object.freeze([null, 'question', 'concept', 'zone'])
+export const SUBJECTS = Object.freeze([null, 'record', 'concept', 'relation'])
+export const LAYERS = Object.freeze(['atelier', 'coach', 'owner'])
+/** The single emphasised action of a recipe. The default shell implements each one. */
+export const PRIMARY_ACTIONS = Object.freeze(['search', 'open-evidence', 'next-step', 'walk', 'review', 'pick'])
+
+/** The primary actions the default shell honours for a recipe's room, lens and subject. */
+export function primaryActionsFor({ room, lens = null, subject = null }) {
+  if (room === 'review') return ['review']
+  if (room === 'workbench') return subject === 'record' ? ['walk'] : ['next-step']
+  if (lens === 'zone') return ['pick', 'search']
+  if (lens) return ['open-evidence', 'pick', 'search']
+  return ['search']
+}
+
+export const DEFAULT_RECIPES = Object.freeze([
+  { id: 'explore', label: 'Explore', room: 'constellation', lens: null, subject: null, primary: 'search', description: 'Wander the whole graph. Zones on, search ready.' },
+  { id: 'question', label: 'Answer a question', room: 'constellation', lens: 'question', subject: null, primary: 'open-evidence', description: 'Light the records that declare a question’s concepts.' },
+  { id: 'refine', label: 'Refine a concept', room: 'workbench', lens: null, subject: 'concept', primary: 'next-step', description: 'One concept, one step at a time.' },
+  { id: 'inspect', label: 'Inspect a record', room: 'workbench', lens: null, subject: 'record', primary: 'walk', description: 'A record and its closest links, with room to read.' },
+].map(Object.freeze))
+
+const FIELDS = ['label', 'room', 'lens', 'subject', 'primary', 'description']
+const text = (v, max) => typeof v === 'string' && v.trim().length > 0 && v.length <= max
+
+export function validateRecipe(recipe, { partial = false } = {}) {
+  const problems = []
+  if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) return ['recipe must be an object']
+  if (!/^[a-z][a-z0-9-]{0,47}$/.test(recipe.id ?? '')) problems.push('id must be a short lowercase slug')
+  for (const key of Object.keys(recipe)) if (!['id', 'hidden', ...FIELDS].includes(key)) problems.push(`unknown field ${key}`)
+  const need = !partial
+  if ((need || 'label' in recipe) && !text(recipe.label, 60)) problems.push('label must be 1–60 characters')
+  if ((need || 'description' in recipe) && !text(recipe.description, 200)) problems.push('description must be 1–200 characters')
+  if ((need || 'room' in recipe) && !ROOMS.includes(recipe.room)) problems.push(`room must be one of ${ROOMS.join(', ')}`)
+  if ('lens' in recipe && !LENSES.includes(recipe.lens)) problems.push('unknown lens')
+  if ('subject' in recipe && !SUBJECTS.includes(recipe.subject)) problems.push('unknown subject')
+  if ((need || 'primary' in recipe) && !PRIMARY_ACTIONS.includes(recipe.primary)) problems.push(`primary must be one of ${PRIMARY_ACTIONS.join(', ')}`)
+  if ('hidden' in recipe && typeof recipe.hidden !== 'boolean') problems.push('hidden must be true or false')
+  return problems
+}
+
+/**
+ * Compose recipe layers. Each layer is a list; an entry with an existing id adjusts
+ * it (partial), a new id adds a complete recipe, and `hidden: true` removes it from
+ * what the owner sees. Later layers win. Throws on any invalid entry.
+ */
+export function composeRecipes({ atelier = DEFAULT_RECIPES, coach = [], owner = [] } = {}) {
+  const resolved = new Map()
+  const provenance = new Map()
+  for (const [layer, list] of [['atelier', atelier], ['coach', coach], ['owner', owner]]) {
+    if (!Array.isArray(list)) throw new TypeError(`${layer} recipes must be a list`)
+    for (const entry of list) {
+      const existing = resolved.get(entry?.id)
+      const problems = validateRecipe(entry, { partial: !!existing })
+      if (problems.length) throw new TypeError(`${layer} recipe ${entry?.id ?? '(no id)'}: ${problems.join('; ')}`)
+      const next = { lens: null, subject: null, hidden: false, ...(existing ?? {}), ...entry }
+      // Only combinations a shell can honour: lenses belong to the constellation,
+      // subjects to the workbench, and the review room takes neither.
+      if (next.room === 'workbench' && !next.subject) throw new TypeError(`${layer} recipe ${entry.id}: a workbench recipe needs a subject`)
+      if (next.room !== 'workbench' && next.subject) throw new TypeError(`${layer} recipe ${entry.id}: only a workbench recipe takes a subject`)
+      if (next.room !== 'constellation' && next.lens) throw new TypeError(`${layer} recipe ${entry.id}: only a constellation recipe takes a lens`)
+      const actions = primaryActionsFor(next)
+      if (!actions.includes(next.primary)) throw new TypeError(`${layer} recipe ${entry.id}: primary ${next.primary} is not available here; use ${actions.join(' or ')}`)
+      resolved.set(entry.id, next)
+      const fields = provenance.get(entry.id) ?? {}
+      for (const key of Object.keys(entry)) if (key !== 'id') fields[key] = layer
+      if (!existing) for (const key of FIELDS) fields[key] ??= layer
+      provenance.set(entry.id, fields)
+    }
+  }
+  const visible = [...resolved.values()].filter(r => !r.hidden)
+  return { recipes: visible.map(r => ({ ...r, setBy: { ...provenance.get(r.id) } })), hidden: [...resolved.values()].filter(r => r.hidden).map(r => r.id) }
+}
+
+/** Recipes a workspace can actually run: concept work needs a plan with concepts. */
+export function availableRecipes(recipes, model) {
+  const concepts = !!model.plan?.concepts.length, relations = !!model.plan?.relations.length, questions = !!model.plan?.questions.length
+  return recipes.filter(r =>
+    (r.subject !== 'concept' || concepts) && (r.subject !== 'relation' || relations) &&
+    (r.lens !== 'question' || questions) && (r.lens !== 'concept' || concepts) &&
+    (r.room !== 'review' || concepts) && (r.subject !== 'record' || model.nodes.length > 0) &&
+    (r.lens !== 'zone' || model.zones?.length > 0))
+}

package/src/graph-workspace/scale.mjs

@@ -0,0 +1,95 @@
+// Scale primitives for workspaces with tens of thousands of records.
+//
+// A constellation draws every readable record while that stays legible and fast.
+// Beyond a budget, the whole is shown as zones (with honest counts and directed
+// bundles between them) and a person opens one zone at a time. Nothing here hides
+// a record silently: every bounded result states what it left out.
+
+export const DEFAULT_BUDGET = Object.freeze({ records: 12000, links: 60000 })
+
+/** Decide how the whole should be drawn for this model and budget. */
+export function planConstellation(model, budget = DEFAULT_BUDGET) {
+  const records = model.nodes.length, links = model.edges.length
+  if (records <= budget.records && links <= budget.links) return { mode: 'records', records, links }
+  return { mode: 'zones', records, links, reason: records > budget.records ? 'records-over-budget' : 'links-over-budget', budget: { ...budget } }
+}
+
+/** Zone-level summary of the whole: counts by type and directed bundles by edge class. */
+export function aggregateZones(model) {
+  const zoneOfId = new Map(model.nodes.map(n => [n.id, n.zone]))
+  const zones = model.zones.map(z => ({ id: z.id, label: z.label, index: z.index, count: z.count, types: Object.create(null), declaredRelations: 0 }))
+  const byId = new Map(zones.map(z => [z.id, z]))
+  for (const n of model.nodes) { const z = byId.get(n.zone); z.types[n.type] = (z.types[n.type] ?? 0) + 1 }
+  const bundles = new Map()
+  let internal = 0
+  for (const e of model.edges) {
+    const a = zoneOfId.get(e.source), b = zoneOfId.get(e.target)
+    if (a === b) { internal++; if (e.kind === 'relation') byId.get(a).declaredRelations++; continue }
+    const key = a + '\u0000' + b
+    const bundle = bundles.get(key) ?? { from: a, to: b, total: 0, link: 0, containment: 0, relation: 0 }
+    bundle.total++; bundle[e.kind]++
+    bundles.set(key, bundle)
+  }
+  return {
+    schema: 'atelier.graph-workspace-zones@v1',
+    coverage: { records: model.nodes.length, zones: zones.length, linksInsideZones: internal, linksBetweenZones: model.edges.length - internal, linksOutsideReadableSet: model.coverage.linksOutsideReadableSet },
+    zones,
+    bundles: [...bundles.values()].sort((x, y) => y.total - x.total || (x.from + x.to < y.from + y.to ? -1 : 1)),
+  }
+}
+
+/** Records ranked by connection count, then title, for budgets and label priority. */
+export function rankRecords(model) {
+  return [...model.nodes].sort((a, b) => b.degree - a.degree || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0))
+}
+
+/**
+ * A bounded sub-model for one zone. Members are kept by rank up to `limit`.
+ * Every link touching the zone is accounted for exactly once:
+ *   drawn (both ends kept) + omittedInsideZone + toOtherZones + omittedToOtherZones = links touching the zone.
+ * Plan concept declarations are projected onto the kept records, with omissions counted.
+ */
+export function zoneSlice(model, zoneId, { limit = DEFAULT_BUDGET.records } = {}) {
+  const members = rankRecords(model).filter(n => n.zone === zoneId)
+  const kept = members.slice(0, limit)
+  const keep = new Set(kept.map(n => n.id))
+  const inZone = new Set(members.map(n => n.id))
+  const zoneOfId = new Map(model.nodes.map(n => [n.id, n.zone]))
+  const edges = []
+  const boundary = new Map()
+  let omittedInsideZone = 0, omittedToOtherZones = 0, touching = 0
+  for (const e of model.edges) {
+    const s = inZone.has(e.source), t = inZone.has(e.target)
+    if (!s && !t) continue
+    touching++
+    if (keep.has(e.source) && keep.has(e.target)) { edges.push(e); continue }
+    if (s && t) { omittedInsideZone++; continue }
+    const memberEnd = s ? e.source : e.target
+    if (!keep.has(memberEnd)) { omittedToOtherZones++; continue }
+    const other = zoneOfId.get(s ? e.target : e.source)
+    boundary.set(other, (boundary.get(other) ?? 0) + 1)
+  }
+  const toOtherZones = [...boundary.values()].reduce((a, b) => a + b, 0)
+  const byClass = { link: 0, containment: 0, relation: 0 }
+  for (const e of edges) byClass[e.kind]++
+  const plan = model.plan ? {
+    ...model.plan,
+    concepts: model.plan.concepts.map(c => {
+      const declaredBy = c.declaredBy.filter(id => keep.has(id))
+      return { ...c, declaredBy, omittedDeclarations: c.declaredBy.length - declaredBy.length }
+    }),
+  } : null
+  return {
+    ...model,
+    nodes: kept.map(n => ({ ...n })),
+    edges,
+    zones: model.zones.filter(z => z.id === zoneId).map(z => ({ ...z, count: kept.length })),
+    plan,
+    coverage: { records: kept.length, links: edges.length, byClass, linksOutsideReadableSet: model.coverage.linksOutsideReadableSet },
+    slice: {
+      zone: zoneId, membersInZone: members.length, omittedRecords: members.length - kept.length,
+      linksTouchingZone: touching, omittedLinksInsideZone: omittedInsideZone, omittedLinksToOtherZones: omittedToOtherZones, linksToOtherZonesCount: toOtherZones,
+      linksToOtherZones: [...boundary.entries()].map(([zone, count]) => ({ zone, count })).sort((a, b) => b.count - a.count),
+    },
+  }
+}

package/src/graph-workspace/theme.mjs

@@ -0,0 +1,156 @@
+// Graph-workspace themes: resolved token data, never stylesheets.
+// Atelier ships two neutral defaults, `night` (the default) and `paper`. A coach or
+// owner theme overrides values by name; the result is validated, including text
+// contrast, before any room applies it as CSS custom properties.
+
+const CSS_VARS = ['--canvas', '--surface', '--surface-2', '--surface-glass', '--ink', '--ink-2', '--ink-3', '--line', '--line-strong', '--accent', '--accent-ink', '--focus', '--warn', '--danger', '--ok', '--font-sans', '--font-display', '--radius', '--radius-lg', '--shadow', '--motion', '--ease']
+const GRAPH = ['canvas', 'edge', 'edgeStructural', 'dim', 'label', 'labelHalo', 'selection']
+
+const night = {
+  vars: {
+    '--canvas': '#0b0e14', '--surface': '#131823', '--surface-2': '#1a2030', '--surface-glass': 'rgba(19,24,35,0.82)',
+    '--ink': '#eef1f7', '--ink-2': '#b9c1d3', '--ink-3': '#8d97ad', '--line': 'rgba(238,241,247,0.12)', '--line-strong': 'rgba(238,241,247,0.26)',
+    '--accent': '#9cc4ff', '--accent-ink': '#08101d', '--focus': '#ffd479', '--warn': '#ffc46b', '--danger': '#ff9a8a', '--ok': '#8fe0b0',
+    '--font-sans': 'Inter, "SF Pro Text", -apple-system, system-ui, sans-serif', '--font-display': '"SF Pro Display", Inter, -apple-system, system-ui, sans-serif',
+    '--radius': '10px', '--radius-lg': '16px', '--shadow': '0 12px 40px rgba(0,0,0,0.45)', '--motion': '240ms', '--ease': 'cubic-bezier(0.2, 0, 0, 1)',
+  },
+  graph: { canvas: '#0b0e14', edge: '#7d88a3', edgeStructural: '#c9d2e6', dim: '#283044', label: '#e6eaf2', labelHalo: '#0b0e14', selection: '#ffd479',
+    zones: ['#7aa7ff', '#5fd1b0', '#f2a65a', '#c792ea', '#ff8fa3', '#e6d36a', '#6fd3f2', '#a4e07a', '#f28fd2', '#b0b8c8'] },
+}
+const paper = {
+  vars: {
+    ...night.vars,
+    '--canvas': '#f5f3ee', '--surface': '#ffffff', '--surface-2': '#f0ede6', '--surface-glass': 'rgba(255,255,255,0.86)',
+    '--ink': '#1a1d24', '--ink-2': '#454b58', '--ink-3': '#5f6676', '--line': 'rgba(26,29,36,0.12)', '--line-strong': 'rgba(26,29,36,0.28)',
+    '--accent': '#2c55a8', '--accent-ink': '#ffffff', '--focus': '#a05a00', '--warn': '#8a4a00', '--danger': '#a32121', '--ok': '#1f6b3c', '--shadow': '0 12px 36px rgba(20,22,30,0.14)',
+  },
+  graph: { canvas: '#f5f3ee', edge: '#9aa1ae', edgeStructural: '#4a5162', dim: '#dcd8cf', label: '#1a1d24', labelHalo: '#f5f3ee', selection: '#a05a00',
+    zones: ['#2f62c9', '#0f7259', '#9a4f0c', '#7a45a8', '#b83255', '#6f5d00', '#0f6a85', '#3f6c14', '#a3337f', '#5d6577'] },
+}
+
+export const DEFAULT_THEME = Object.freeze({
+  schema: 'atelier.graph-workspace-theme@v1', id: 'atelier-night', version: '1', defaultScheme: 'dark',
+  schemes: Object.freeze({ dark: night, light: paper }),
+})
+
+// Every token has one type. Only colours, lengths, durations, an easing and font
+// family names are accepted, so no theme value can load a resource or inject CSS.
+const HEX = /^#[0-9a-f]{6}$/i
+const RGBA = /^rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*(?:0|1|0?\.\d{1,3})\s*\)$/i
+const COLOR = v => HEX.test(v)
+const SOFT_COLOR = v => HEX.test(v) || RGBA.test(v)
+const FONT = v => /^[A-Za-z0-9 "',.-]{1,160}$/.test(v) && !/["']{2}/.test(v)
+const LENGTH = v => /^\d{1,2}(?:\.\d{1,2})?px$/.test(v)
+const SHADOW = v => v === 'none' || v.split(/,(?![^()]*\))/).every(part => /^\s*(?:(?:0|-?\d{1,3}(?:\.\d{1,2})?px)\s+){2,4}(?:rgba\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*(?:0|1|0?\.\d{1,3})\s*\)|#[0-9a-f]{6})\s*$/i.test(part))
+const DURATION = v => /^\d{1,4}ms$/.test(v)
+const EASE = v => /^(?:ease|linear|ease-in|ease-out|ease-in-out|cubic-bezier\(\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*,\s*-?\d(?:\.\d{1,3})?\s*\))$/.test(v)
+export const TOKEN_TYPES = Object.freeze({
+  '--canvas': COLOR, '--surface': COLOR, '--surface-2': COLOR, '--surface-glass': SOFT_COLOR,
+  '--ink': COLOR, '--ink-2': COLOR, '--ink-3': COLOR, '--line': SOFT_COLOR, '--line-strong': SOFT_COLOR,
+  '--accent': COLOR, '--accent-ink': COLOR, '--focus': COLOR, '--warn': COLOR, '--danger': COLOR, '--ok': COLOR,
+  '--font-sans': FONT, '--font-display': FONT, '--radius': LENGTH, '--radius-lg': LENGTH, '--shadow': SHADOW, '--motion': DURATION, '--ease': EASE,
+})
+const LAYER_FIELDS = ['id', 'version', 'defaultScheme', 'schemes']
+const SCHEME_FIELDS = ['vars', 'graph']
+// Text and the surfaces it is drawn on in the rooms, with the minimum ratio for its size.
+const TEXT_PAIRS = [
+  ['--ink', '--canvas', 7], ['--ink', '--surface', 7], ['--ink', '--surface-2', 7],
+  ['--ink-2', '--canvas', 4.5], ['--ink-2', '--surface', 4.5], ['--ink-2', '--surface-2', 4.5],
+  ['--ink-3', '--canvas', 4.5], ['--ink-3', '--surface', 4.5], ['--ink-3', '--surface-2', 4.5],
+  ['--accent-ink', '--accent', 4.5], ['--accent', '--canvas', 4.5], ['--accent', '--surface', 4.5],
+  ['--warn', '--surface', 4.5], ['--danger', '--surface', 4.5], ['--ok', '--surface', 4.5],
+]
+// Text on the translucent chrome (pills, command bar, selection card), composited
+// over each backdrop it floats on.
+const GLASS_TEXT = [['--ink', 4.5], ['--ink-2', 4.5], ['--ink-3', 4.5]]
+const GLASS_BACKDROPS = ['--canvas', '--surface-2']
+function composite(over, under) {
+  const rgb = h => { const n = parseInt(h.slice(1, 7), 16); return [n >> 16, (n >> 8) & 255, n & 255] }
+  const m = RGBA.test(over) ? over.match(/[\d.]+/g).map(Number) : [...rgb(over), 1]
+  const [r, g, b, a] = [Math.min(255, m[0]), Math.min(255, m[1]), Math.min(255, m[2]), Math.min(1, m[3])]
+  const base = rgb(under)
+  return '#' + [r, g, b].map((v, i) => Math.round(v * a + base[i] * (1 - a)).toString(16).padStart(2, '0')).join('')
+}
+
+function layerProblems(layer, { partial }) {
+  const problems = []
+  if (!layer || typeof layer !== 'object' || Array.isArray(layer)) return ['theme layer must be an object']
+  for (const key of Object.keys(layer)) if (!LAYER_FIELDS.includes(key) && !(key === 'schema' && !partial)) problems.push(`unknown theme field ${key}`)
+  if ('id' in layer && !/^[a-z][a-z0-9-]{0,47}$/.test(layer.id ?? '')) problems.push('id must be a short lowercase slug')
+  if ('version' in layer && !/^[\w.-]{1,32}$/.test(layer.version ?? '')) problems.push('version must be a short label')
+  if ('defaultScheme' in layer && !['dark', 'light'].includes(layer.defaultScheme)) problems.push('defaultScheme must be dark or light')
+  if ('schemes' in layer) {
+    if (!layer.schemes || typeof layer.schemes !== 'object' || Array.isArray(layer.schemes)) problems.push('schemes must be an object')
+    else for (const [scheme, value] of Object.entries(layer.schemes)) {
+      if (!['dark', 'light'].includes(scheme)) { problems.push(`unknown scheme ${scheme}`); continue }
+      if (!value || typeof value !== 'object' || Array.isArray(value)) { problems.push(`${scheme}: must be an object`); continue }
+      for (const key of Object.keys(value)) if (!SCHEME_FIELDS.includes(key)) problems.push(`${scheme}: unknown field ${key}`)
+      for (const [k, v] of Object.entries(value.vars ?? {})) {
+        if (!Object.hasOwn(TOKEN_TYPES, k)) problems.push(`${scheme}: unknown token ${k}`)
+        else if (typeof v !== 'string' || !TOKEN_TYPES[k](v)) problems.push(`${scheme}: rejected ${k}`)
+      }
+      for (const [k, v] of Object.entries(value.graph ?? {})) {
+        if (k === 'zones') { if (!Array.isArray(v) || v.length < 4 || v.length > 16 || !v.every(z => typeof z === 'string' && HEX.test(z))) problems.push(`${scheme}: graph.zones needs 4–16 #rrggbb colours`) }
+        else if (!GRAPH.includes(k)) problems.push(`${scheme}: unknown graph key ${k}`)
+        else if (typeof v !== 'string' || !HEX.test(v)) problems.push(`${scheme}: graph.${k} must be #rrggbb`)
+      }
+    }
+  }
+  return problems
+}
+
+export function validateTheme(theme) {
+  const problems = []
+  if (theme?.schema !== 'atelier.graph-workspace-theme@v1') problems.push('schema must be atelier.graph-workspace-theme@v1')
+  problems.push(...layerProblems(theme, { partial: false }))
+  if (!['dark', 'light'].includes(theme?.defaultScheme)) problems.push('defaultScheme must be dark or light')
+  for (const scheme of ['dark', 'light']) {
+    const s = theme?.schemes?.[scheme]
+    if (!s) { problems.push(`missing ${scheme} scheme`); continue }
+    for (const k of Object.keys(TOKEN_TYPES)) if (!(k in (s.vars ?? {}))) problems.push(`${scheme}: missing ${k}`)
+    for (const k of GRAPH) if (!(k in (s.graph ?? {}))) problems.push(`${scheme}: missing graph.${k}`)
+    if (!Array.isArray(s.graph?.zones)) problems.push(`${scheme}: missing graph.zones`)
+  }
+  if (problems.length) return [...new Set(problems)]
+  for (const scheme of ['dark', 'light']) {
+    const { vars, graph } = theme.schemes[scheme]
+    if (vars['--canvas'].toLowerCase() !== graph.canvas.toLowerCase()) problems.push(`${scheme}: --canvas and graph.canvas must be the same colour`)
+    for (const [fg, bg, min] of TEXT_PAIRS) if (contrastRatio(vars[fg], vars[bg]) < min) problems.push(`${scheme}: ${fg} on ${bg} is below ${min}:1`)
+    for (const backdrop of GLASS_BACKDROPS) {
+      const glass = composite(vars['--surface-glass'], vars[backdrop])
+      for (const [fg, min] of GLASS_TEXT) if (contrastRatio(vars[fg], glass) < min) problems.push(`${scheme}: ${fg} on --surface-glass over ${backdrop} is below ${min}:1`)
+    }
+    if (contrastRatio(graph.label, graph.canvas) < 7) problems.push(`${scheme}: label contrast on the canvas is below 7:1`)
+    if (Math.min(...graph.zones.map(z => contrastRatio(z, graph.canvas))) < 3) problems.push(`${scheme}: a zone colour is below 3:1 on the canvas (zone names are large text)`)
+  }
+  return problems
+}
+
+/** Override a base theme by layer (coach, then owner). Each layer is validated before it is applied. */
+export function composeTheme(base = DEFAULT_THEME, ...layers) {
+  const baseProblems = validateTheme(base)
+  if (baseProblems.length) throw new TypeError('Base theme refused: ' + baseProblems.join('; '))
+  const out = structuredClone(base)
+  layers.filter(Boolean).forEach((layer, index) => {
+    const problems = layerProblems(layer, { partial: true })
+    if (problems.length) throw new TypeError(`Theme layer ${index + 1} refused: ${problems.join('; ')}`)
+    if (layer.id) out.id = layer.id
+    if (layer.version) out.version = layer.version
+    if (layer.defaultScheme) out.defaultScheme = layer.defaultScheme
+    for (const scheme of ['dark', 'light']) {
+      const s = layer.schemes?.[scheme]
+      if (!s) continue
+      Object.assign(out.schemes[scheme].vars, s.vars ?? {})
+      Object.assign(out.schemes[scheme].graph, s.graph ?? {})
+    }
+  })
+  const problems = validateTheme(out)
+  if (problems.length) throw new TypeError('Theme refused: ' + problems.join('; '))
+  return out
+}
+
+export function contrastRatio(a, b) {
+  const lum = h => { const n = parseInt(h.slice(1, 7), 16); return [n >> 16, (n >> 8) & 255, n & 255].map(v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }).reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0) }
+  const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p)
+  return (x + 0.05) / (y + 0.05)
+}

package/src/ingestion/optional/graphify/graphify_supplier.py

@@ -717,6 +717,11 @@ class GraphifySupplier:
                 settings = {"parallel": False, "max_workers": 1, **settings}
                 require(type(settings["parallel"]) is bool and type(settings["max_workers"]) is int
                         and 1 <= settings["max_workers"] <= 32, "BUDGET_UNBOUNDED", "Finite native structural worker bound required")
+                # Parallel extraction starts worker processes that import Graphify through the
+                # ordinary import system, outside the pinned source loader, so they may run a
+                # cached pyc this supplier never attested. Only in-process extraction is admitted.
+                require(settings["parallel"] is False, "NATIVE_WORKERS_UNATTESTED",
+                        "Parallel native extraction runs worker processes outside the attested loader")
             if op == "cache-check":
                 require(settings.get("prompt") is None or isinstance(settings["prompt"], str), "PROMPT_SCOPE", "Prompt must be explicit text")
                 if settings.get("prompt_file") is not None: