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

package/src/graph-refresh/controller.mjs

@@ -0,0 +1,324 @@
+import { canonicalize } from '../attestation/jcs.mjs'
+import { compareGraphSnapshots } from './compare.mjs'
+
+const clone = value => value === null ? null : JSON.parse(canonicalize(value))
+const validBinding = (binding, now) => binding && typeof binding.key === 'string' && binding.key.length > 0 &&
+  Number.isSafeInteger(binding.expiresAtMs) && binding.expiresAtMs > now
+const qualifiedKey = ref => ref && typeof ref.repoId === 'string' && ref.repoId &&
+  typeof ref.localId === 'string' && ref.localId ? canonicalize([ref.repoId, ref.localId]) : null
+
+// One foreground host owns this controller. Binding and revalidate are trusted
+// host ports, never browser-supplied grants. Builds compute in isolation; only
+// the synchronous commit below may replace the published projection.
+export function createGraphRefresh({
+  build, validate, revalidate, stage = () => ({ commit() {}, discard() {} }),
+  clear = () => {}, onCleanup = () => {}, debounceMs = 40, historyLimit = 3, now = Date.now,
+} = {}) {
+  for (const port of [build, validate, revalidate, stage, clear, onCleanup]) {
+    if (typeof port !== 'function') throw new TypeError('Graph refresh requires host ports')
+  }
+  if (!Number.isSafeInteger(debounceMs) || debounceMs < 0 || debounceMs > 60_000 ||
+      !Number.isSafeInteger(historyLimit) || historyLimit < 0 || historyLimit > 20) {
+    throw new TypeError('Invalid graph refresh bounds')
+  }
+  let running = false
+  let generation = 0
+  let binding = null
+  let current = null
+  let history = []
+  let selectedRef = null
+  let phase = 'stopped'
+  let failure = null
+  let pending = false
+  let timer = null
+  let expiryTimer = null
+  let job = null
+  let active = null
+  const listeners = new Set()
+  // Host resource custody, separate from reader state. At most one unresolved
+  // transaction exists: a failure blocks further builds/staging until resolved.
+  const cleanupTasks = new Map()
+  let cleanupSequence = 0
+
+  function cleanupOutcome(entry, state) {
+    const outcome = Object.freeze({ cleanupId: entry.cleanupId, state, code: state === 'failed' ? 'stage-cleanup-failed' : null })
+    try { onCleanup(outcome)?.catch?.(() => {}) } catch { /* retained status remains available to the host */ }
+  }
+
+  function discard(entry) {
+    if (entry.inFlight) return entry.inFlight
+    entry.state = 'cleaning'
+    // Defer invocation so even a synchronous rejection settles after custody
+    // and the shared in-flight promise have been installed.
+    entry.inFlight = Promise.resolve().then(() => entry.transaction.discard()).then(() => {
+      cleanupTasks.delete(entry.cleanupId)
+      cleanupOutcome(entry, 'resolved')
+      return true
+    }, () => {
+      entry.state = 'failed'
+      cleanupOutcome(entry, 'failed')
+      return false
+    }).finally(() => { entry.inFlight = null })
+    return entry.inFlight
+  }
+
+  function status() {
+    expire()
+    return { phase, generation, stale: current !== null && current.generation !== generation, failure }
+  }
+
+  function emit(type) {
+    const event = { type, phase, generation, stale: current !== null && current.generation !== generation, failure }
+    // Events contain no private refs, diagnostics or former projection digests.
+    for (const listener of [...listeners]) {
+      try { listener(Object.freeze({ ...event })) } catch { /* one consumer cannot block another's invalidation */ }
+    }
+  }
+
+  function purge(nextPhase) {
+    generation += 1
+    active?.abort()
+    clearTimeout(timer)
+    clearTimeout(expiryTimer)
+    timer = expiryTimer = null
+    pending = false
+    binding = null
+    current = selectedRef = null
+    history = []
+    phase = nextPhase
+    failure = null
+    try {
+      const result = clear()
+      if (result && typeof result.then === 'function') {
+        result.catch?.(() => {})
+        throw new Error('cache clear must be synchronous')
+      }
+    } catch { failure = 'cache-clear-failed' }
+    emit('clear')
+  }
+
+  function expire() {
+    if (binding && !validBinding(binding, now())) purge(running ? 'denied' : 'stopped')
+  }
+
+  function armExpiry() {
+    clearTimeout(expiryTimer)
+    if (!binding) return
+    // Re-arm long grants; node timers use a signed 32-bit delay.
+    expiryTimer = setTimeout(() => { expire(); if (binding) armExpiry() }, Math.min(2_147_483_647, Math.max(1, binding.expiresAtMs - now())))
+    expiryTimer.unref?.()
+  }
+
+  function eligible(expectedGeneration, expectedBinding) {
+    expire()
+    return running && generation === expectedGeneration && binding === expectedBinding && validBinding(binding, now())
+  }
+
+  async function permitted(expectedBinding, projection) {
+    try { return (await revalidate(expectedBinding, clone(projection))) === true } catch { return false }
+  }
+
+  async function runBuild() {
+    const expectedGeneration = generation
+    const expectedBinding = binding
+    const controller = new AbortController()
+    active = controller
+    let transaction = null
+    let committed = false
+    try {
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      if (cleanupTasks.size) {
+        phase = 'failed'
+        failure = 'stage-cleanup-pending'
+        emit('state')
+        return
+      }
+      phase = 'building'
+      failure = null
+      emit('state')
+      if (!(await permitted(expectedBinding, null))) {
+        if (eligible(expectedGeneration, expectedBinding)) purge('denied')
+        return
+      }
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      const built = await build({ generation: expectedGeneration, binding: expectedBinding, signal: controller.signal })
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      const projection = clone(built)
+      if ((await validate(projection)) !== true) throw new Error('unsupported')
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      if (!(await permitted(expectedBinding, projection))) {
+        if (eligible(expectedGeneration, expectedBinding)) purge('denied')
+        return
+      }
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      transaction = await stage({ projection: clone(projection), generation: expectedGeneration, signal: controller.signal })
+      if (!transaction || typeof transaction.commit !== 'function' || typeof transaction.discard !== 'function') {
+        throw new Error('stage-failed')
+      }
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      if (!(await permitted(expectedBinding, projection))) {
+        if (eligible(expectedGeneration, expectedBinding)) purge('denied')
+        return
+      }
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      // No await between the final fence, host commit, and pointer replacement.
+      // Commit is a synchronous atomic host operation; asynchronous writes are
+      // unsupported because they cannot be fenced by this controller.
+      const result = transaction.commit()
+      if (result && typeof result.then === 'function') {
+        result.catch?.(() => {})
+        throw new Error('commit-must-be-synchronous')
+      }
+      if (!eligible(expectedGeneration, expectedBinding)) return
+      committed = true
+      if (current && current.projection.projectionDigest !== projection.projectionDigest) {
+        history = [current, ...history.filter(entry => entry.projection.projectionDigest !== current.projection.projectionDigest)].slice(0, historyLimit)
+      }
+      current = { projection, generation: expectedGeneration }
+      if (selectedRef && !projection.nodes.some(node => qualifiedKey(node.ref) === qualifiedKey(selectedRef))) selectedRef = null
+      phase = 'current'
+      failure = null
+      emit('publish')
+    } catch (error) {
+      if (eligible(expectedGeneration, expectedBinding)) {
+        phase = error?.message === 'unsupported' ? 'unsupported' : 'failed'
+        // Arbitrary build errors may contain paths or private source content.
+        failure = phase === 'unsupported' ? 'projection-unsupported' : 'build-or-save-failed'
+        emit('state')
+      }
+    } finally {
+      if (!committed && transaction && typeof transaction.discard === 'function') {
+        const entry = { cleanupId: `cleanup-${++cleanupSequence}`, transaction, state: 'cleaning', inFlight: null, retryInFlight: null }
+        cleanupTasks.set(entry.cleanupId, entry)
+        if (!(await discard(entry)) && eligible(expectedGeneration, expectedBinding)) {
+          phase = 'failed'; failure = 'stage-cleanup-failed'; emit('state')
+        }
+      }
+      if (active === controller) active = null
+    }
+  }
+
+  function launch() {
+    clearTimeout(timer)
+    timer = null
+    expire()
+    if (!running || !binding || job || !pending) return
+    pending = false
+    // One build/stage at a time: an abort-ignoring builder cannot create an
+    // unbounded queue of writers. Its return is still fenced by generation.
+    job = runBuild().finally(() => {
+      job = null
+      if (pending && running && binding) schedule()
+    })
+  }
+
+  function schedule() {
+    if (!timer) timer = setTimeout(launch, debounceMs)
+  }
+
+  function invalidate() {
+    expire()
+    if (!running || !binding) return
+    generation += 1
+    active?.abort()
+    pending = true
+    failure = null
+    phase = current ? 'stale' : 'pending'
+    emit('invalidate')
+    // A fixed coalescing window avoids starvation under continuous edits.
+    schedule()
+  }
+
+  async function read(digest = null) {
+    expire()
+    const expectedBinding = binding
+    if (!running || !expectedBinding) return { ...status(), projection: null, selectedRef: null, historical: false }
+    const entry = digest === null ? current : [current, ...history].find(item => item?.projection.projectionDigest === digest)
+    if (!entry) return { ...status(), projection: null, selectedRef: null, historical: false }
+    const allowed = await permitted(expectedBinding, entry.projection)
+    expire()
+    if (binding !== expectedBinding || !running) return { ...status(), projection: null, selectedRef: null, historical: false }
+    if (!allowed) {
+      purge('denied')
+      return { ...status(), projection: null, selectedRef: null, historical: false }
+    }
+    // A source-only edit may happen while access is checked: label that view
+    // stale. Access changes and stop purge the captured entry altogether.
+    return { ...status(), stale: entry.generation !== generation, projection: clone(entry.projection), selectedRef: entry === current ? clone(selectedRef) : null, historical: entry !== current }
+  }
+
+  return {
+    start() {
+      if (running) return
+      running = true
+      phase = binding ? 'pending' : 'denied'
+      invalidate()
+    },
+    stop() {
+      running = false
+      purge('stopped')
+    },
+    // Call only with a trusted host binding whose key binds principal, exact
+    // repository set, grant revision/expiry, policy and filter. Every call
+    // clears history, selection, and caches before accepting a replacement.
+    setAccess(nextBinding) {
+      purge(running ? 'denied' : 'stopped')
+      if (failure || !validBinding(nextBinding, now())) return
+      binding = Object.freeze({ ...nextBinding })
+      armExpiry()
+      if (running) invalidate()
+    },
+    invalidateAccess() { purge(running ? 'denied' : 'stopped') },
+    invalidate,
+    read,
+    status,
+    // Trusted host-only resource APIs. Never serialize these into a reader
+    // response; they carry no projection, binding, path, or raw exception.
+    cleanupStatus() { return [...cleanupTasks.values()].map(entry => ({ cleanupId: entry.cleanupId, state: entry.state })) },
+    async retryCleanup(cleanupId) {
+      const entry = cleanupTasks.get(cleanupId)
+      if (!entry) return false
+      // Share the complete host retry, including its failure result and the
+      // single rebuild request. A failed shared attempt needs a new host call.
+      if (!entry.retryInFlight) {
+        entry.retryInFlight = (async () => {
+          const resolved = await discard(entry)
+          if (resolved && running && binding && cleanupTasks.size === 0) invalidate()
+          return resolved
+        })().finally(() => { entry.retryInFlight = null })
+      }
+      return entry.retryInFlight
+    },
+    async select(ref, digest) {
+      const result = await read()
+      if (!result.projection || result.generation !== generation || result.stale || digest !== current?.projection.projectionDigest ||
+          digest !== result.projection.projectionDigest ||
+          !qualifiedKey(ref) || !result.projection.nodes.some(node => qualifiedKey(node.ref) === qualifiedKey(ref))) return false
+      selectedRef = clone(ref)
+      return true
+    },
+    async compare(beforeDigest, afterDigest) {
+      const expectedBinding = binding
+      const expectedGeneration = generation
+      const before = await read(beforeDigest)
+      const after = await read(afterDigest)
+      if (!expectedBinding || binding !== expectedBinding || expectedGeneration !== generation || !before.projection || !after.projection) return null
+      return compareGraphSnapshots(before.projection, after.projection)
+    },
+    subscribe(listener) {
+      if (typeof listener !== 'function') throw new TypeError('Refresh listener must be a function')
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    async flush() {
+      clearTimeout(timer)
+      timer = null
+      while (job || (running && pending)) {
+        if (!job) launch()
+        if (job) await job
+        else break
+      }
+      return status()
+    },
+  }
+}

package/src/graph-refresh/index.mjs

@@ -0,0 +1,3 @@
+export { createGraphRefresh } from './controller.mjs'
+export { createLocalGraphRefresh } from './local.mjs'
+export { compareGraphSnapshots } from './compare.mjs'

package/src/graph-refresh/local.mjs

@@ -0,0 +1,78 @@
+import { createFsWatcherFactory } from '../runtime/obsidian/watchers.mjs'
+import { createGraphRefresh } from './controller.mjs'
+
+// Attach to the existing sidecar's start/close, never to a second listener or
+// daemon. Watch events are hints. Periodic rebuilds reconcile dropped events;
+// the canonical builder/file cache remains the source of incremental reuse.
+export function createLocalGraphRefresh({ roots, watcherFactory, reconcileMs = 30_000, ...ports } = {}) {
+  if (!Array.isArray(roots) || roots.length === 0 || roots.some(root => !root ||
+      typeof root.id !== 'string' || !root.id || typeof root.path !== 'string' || !root.path) ||
+      new Set(roots.map(root => root.id)).size !== roots.length ||
+      !Number.isSafeInteger(reconcileMs) || reconcileMs < 10 || reconcileMs > 2_147_483_647) {
+    throw new TypeError('Invalid local graph refresh roots or interval')
+  }
+  const controller = createGraphRefresh(ports)
+  let authorizedRoots = roots.map(root => ({ ...root }))
+  let watcher = null
+  let interval = null
+  let watchState = 'stopped'
+  let started = false
+  let resourceEpoch = 0
+
+  function stopResources() {
+    resourceEpoch += 1
+    clearInterval(interval)
+    interval = null
+    try { watcher?.close() } catch { /* stopped state still purges delivery */ }
+    watcher = null
+    watchState = 'stopped'
+  }
+
+  function startResources() {
+    if (!started || watcher || interval || ['denied', 'stopped'].includes(controller.status().phase)) return
+    watchState = 'watching'
+    const epoch = resourceEpoch
+    const onUnavailable = () => { if (started && epoch === resourceEpoch) watchState = 'unavailable' }
+    const watch = watcherFactory ?? createFsWatcherFactory({ onUnavailable })
+    try {
+      watcher = watch({ roots: authorizedRoots, onEvent() { if (started && epoch === resourceEpoch) controller.invalidate() }, onUnavailable })
+      if (!watcher || typeof watcher.close !== 'function') throw new Error('watcher unavailable')
+    } catch { watchState = 'unavailable' }
+    interval = setInterval(() => {
+      // Reconciliation must not repeatedly cancel a healthy long build.
+      if (!['building', 'pending', 'stale'].includes(controller.status().phase)) controller.invalidate()
+    }, reconcileMs)
+    interval.unref?.()
+  }
+
+  controller.subscribe(event => { if (event.type === 'clear') stopResources() })
+  return {
+    ...controller,
+    start() {
+      if (started) return
+      started = true
+      controller.start()
+      startResources()
+    },
+    stop() {
+      started = false
+      stopResources()
+      controller.stop()
+    },
+    setAccess(nextBinding, nextRoots = roots) {
+      // Roots are supplied by the trusted host for this exact decision. They
+      // do not establish permission. Closing old watchers prevents an event
+      // from a formerly permitted root invalidating a different reader view.
+      controller.invalidateAccess()
+      if (!Array.isArray(nextRoots) || !nextRoots.length || nextRoots.some(root => !root ||
+          typeof root.id !== 'string' || !root.id || typeof root.path !== 'string' || !root.path) ||
+          new Set(nextRoots.map(root => root.id)).size !== nextRoots.length) {
+        throw new TypeError('Invalid authorized refresh roots')
+      }
+      authorizedRoots = nextRoots.map(root => ({ ...root }))
+      controller.setAccess(nextBinding)
+      startResources()
+    },
+    status() { return { ...controller.status(), watchState } },
+  }
+}

package/src/graph-view/babylon/babylon-scene-port.mjs

@@ -0,0 +1,64 @@
+import { referenceKey } from './semantic-picking.mjs'
+
+// Inject the exact locally supplied Babylon symbols and engine. No browser globals,
+// engine construction, camera attachControl, subscriptions or scheduler live here.
+export function createBabylonPortFactory(B, engine, { onSceneCreated = () => {} } = {}) {
+  return (profile, bind) => {
+    const scene = new B.Scene(engine)
+    try {
+      scene.useRightHandedSystem = true
+      scene.clearColor = new B.Color4(0.098, 0.102, 0.098, 1)
+      const camera = new B.ArcRotateCamera('view-camera', Math.PI / 2, 1.41, 10, B.Vector3.Zero(), scene)
+      camera.lowerRadiusLimit = 4
+      camera.upperRadiusLimit = 55
+      const light = new B.HemisphericLight('view-light', new B.Vector3(0, 1, 0), scene)
+      light.intensity = 1.5
+      const nodes = new Map()
+      const pickable = new Set()
+      for (const [index, node] of profile.nodes.entries()) {
+        // The mesh name is intentionally unrelated to domain identity.
+        const mesh = B.MeshBuilder.CreateSphere(`node-glyph-${index}`, { diameter: 0.5, segments: 12 }, scene)
+        mesh.position.copyFromFloats(...node.position)
+        const material = new B.StandardMaterial(`glyph-material-${index}`, scene)
+        material.diffuseColor = new B.Color3(0.65, 0.70, 0.72)
+        material.specularColor = new B.Color3(0.2, 0.2, 0.15)
+        mesh.material = material
+        nodes.set(referenceKey(node.ref), mesh)
+        pickable.add(mesh)
+        bind(mesh, node)
+      }
+      profile.edges.forEach((edge, index) => {
+        const line = B.MeshBuilder.CreateLines(`relation-${index}`, {
+          points: [nodes.get(referenceKey(edge.from)).position, nodes.get(referenceKey(edge.to)).position],
+        }, scene)
+        line.isPickable = false
+        line.color = new B.Color3(0.45, 0.48, 0.44)
+      })
+      onSceneCreated({ scene, camera }) // Local host/qualifier seam; never a semantic event.
+      return {
+        render() { scene.render() },
+        pick(x, y) {
+          const hit = scene.pick(x, y, mesh => pickable.has(mesh))
+          return hit?.hit ? hit.pickedMesh : null
+        },
+        focus(position) { camera.setTarget(B.Vector3.FromArray(position)) },
+        select(ref) {
+          const key = ref ? referenceKey(ref) : null
+          for (const [nodeKey, mesh] of nodes) {
+            const selected = key === nodeKey
+            mesh.scaling.setAll(selected ? 1.3 : 1)
+            mesh.material.emissiveColor = selected ? new B.Color3(0.44, 0.35, 0.17) : B.Color3.Black()
+          }
+        },
+        dispose() {
+          nodes.clear()
+          pickable.clear()
+          scene.dispose()
+        },
+      }
+    } catch (error) {
+      scene.dispose()
+      throw error
+    }
+  }
+}

package/src/graph-view/babylon/index.mjs

@@ -0,0 +1,2 @@
+export { createGraphNavigator, layoutGraph } from './navigator.mjs'
+export { mountGraphCanvas } from './web-host.mjs'