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

package/src/graph-view/babylon/web-host.mjs

@@ -0,0 +1,188 @@
+import { createBabylonPortFactory } from './babylon-scene-port.mjs'
+import { createGraphNavigator } from './navigator.mjs'
+
+const activeCanvases = new WeakMap()
+function unavailableHost(reason, dispose = () => {}) {
+  const unavailable = () => ({ status: 'unavailable' })
+  return Object.freeze({ status: 'unavailable', reason,
+    select: unavailable, selectEdge: unavailable, receiveSelection: unavailable,
+    focus: unavailable, expand: unavailable, openEvidence: unavailable, setQuestion: unavailable,
+    setLens: unavailable, update: unavailable, fit() {}, reset() {}, zoom() {}, pan() {},
+    snapshot: () => null, dispose, clear: dispose })
+}
+
+// The browser owns scheduling, input and engine lifetime; the reused port owns
+// scene geometry. Graphics availability never controls the companion document.
+export function mountGraphCanvas(canvas, { B, view, onIntent, onAvailability = () => {},
+  createEngine = element => new B.Engine(element, true, { preserveDrawingBuffer: false, stencil: true }),
+} = {}) {
+  if (!canvas?.ownerDocument?.defaultView) throw new TypeError('Browser canvas required')
+  if (activeCanvases.has(canvas)) return unavailableHost('canvas-in-use')
+  const lease = {}
+  activeCanvases.set(canvas, lease)
+  const document = canvas.ownerDocument, window = document.defaultView
+  const listeners = [], cameras = new Set()
+  let engine, navigator, camera, frame = null, down = null, disposed = false, lost = false
+  let motion = window.matchMedia?.('(prefers-reduced-motion: reduce)')
+  const listen = (target, event, handler, options) => {
+    target.addEventListener(event, handler, options)
+    listeners.push(() => target.removeEventListener(event, handler, options))
+  }
+  const available = state => { try { onAvailability(state) } catch { /* Consumer notification. */ } }
+  function clearBuffer() {
+    // Force reallocation: assigning the same width can retain composited pixels.
+    const width = canvas.width
+    canvas.width = width === 0 ? 1 : 0
+    canvas.width = width
+  }
+  function present(result) {
+    if (result.status === 'empty') clearBuffer()
+    fit()
+    return result
+  }
+  function dispose() {
+    if (disposed) return
+    disposed = true
+    if (frame !== null) window.cancelAnimationFrame(frame)
+    frame = null
+    down = null
+    listeners.splice(0).reverse().forEach(remove => remove())
+    try { navigator?.dispose() } finally {
+      for (const item of cameras) item.detachControl()
+      cameras.clear()
+      try { engine?.dispose() } finally {
+        engine = camera = navigator = null
+        if (activeCanvases.get(canvas) === lease) {
+          activeCanvases.delete(canvas)
+          // Reset the owned drawing buffer synchronously, including the last
+          // composited frame, before a narrower view may be delivered.
+          clearBuffer()
+        }
+      }
+    }
+  }
+  function applyMotion() {
+    if (!camera) return
+    camera.inertia = motion?.matches ? 0 : .85
+    camera.panningInertia = motion?.matches ? 0 : .85
+    if (motion?.matches) stopInertia()
+  }
+  function stopInertia() {
+    if (!camera) return
+    for (const name of ['inertialAlphaOffset', 'inertialBetaOffset', 'inertialRadiusOffset', 'inertialPanningX', 'inertialPanningY']) camera[name] = 0
+  }
+  function fit() {
+    if (!camera || !navigator) return
+    const positions = camera.getScene().meshes.filter(mesh => mesh.isPickable && mesh.isEnabled()).map(mesh => mesh.position)
+    if (!positions.length) return
+    const min = new B.Vector3(Infinity, Infinity, Infinity), max = new B.Vector3(-Infinity, -Infinity, -Infinity)
+    for (const point of positions) { min.minimizeInPlace(point); max.maximizeInPlace(point) }
+    camera.setTarget(min.add(max).scale(.5), false, false, true)
+    const aspect = Math.max(.1, engine.getRenderWidth() / Math.max(1, engine.getRenderHeight()))
+    const fov = Math.min(camera.fov, 2 * Math.atan(Math.tan(camera.fov / 2) * aspect))
+    camera.upperRadiusLimit = 400
+    camera.radius = Math.max(camera.lowerRadiusLimit, max.subtract(min).length() / (2 * Math.sin(fov / 2)) + 2)
+    stopInertia()
+  }
+  function loop() {
+    frame = null
+    if (disposed || lost || document.hidden) return
+    navigator.frame()
+    frame = window.requestAnimationFrame(loop)
+  }
+  function active() { return !disposed && !lost && !document.hidden }
+  try {
+    engine = createEngine(canvas)
+    const baseFactory = createBabylonPortFactory(B, engine, { onSceneCreated(created) {
+      camera = created.camera
+      cameras.add(camera)
+      camera.lowerBetaLimit = .15
+      camera.upperBetaLimit = Math.PI / 2 - .05
+      camera.panningDistanceLimit = 150
+      camera.attachControl(canvas, true)
+      applyMotion()
+    } })
+    navigator = createGraphNavigator({ onIntent, createPort(profile, bind) {
+      const port = baseFactory(profile, bind)
+      const ownCamera = camera
+      // Preserve the retained controller and geometry; apply CR-4's measured
+      // orbit-preserving focus behavior at this presentation port boundary.
+      return { ...port, focus(position) {
+        ownCamera.setTarget(B.Vector3.FromArray(position), false, false, true)
+        for (const name of ['inertialAlphaOffset', 'inertialBetaOffset', 'inertialRadiusOffset', 'inertialPanningX', 'inertialPanningY']) ownCamera[name] = 0
+      }, dispose() {
+        ownCamera.detachControl()
+        cameras.delete(ownCamera)
+        if (camera === ownCamera) camera = null
+        port.dispose()
+      } }
+    } })
+    const mounted = navigator.mount(view)
+    engine.resize()
+    present(mounted)
+    listen(canvas, 'pointerdown', event => {
+      if (event.button === 0 && active()) down = { id: event.pointerId, x: event.clientX, y: event.clientY, dragged: false }
+    })
+    listen(canvas, 'pointermove', event => {
+      if (down?.id === event.pointerId && Math.hypot(event.clientX - down.x, event.clientY - down.y) > 6) down.dragged = true
+    })
+    listen(canvas, 'pointerup', event => {
+      const start = down
+      down = null
+      if (!active() || !start || start.dragged || start.id !== event.pointerId || Math.hypot(event.clientX - start.x, event.clientY - start.y) > 6) return
+      const rect = canvas.getBoundingClientRect()
+      if (!rect.width || !rect.height) return
+      const scale = engine.getHardwareScalingLevel()
+      const x = (event.clientX - rect.left) * engine.getRenderWidth() * scale / rect.width
+      const y = (event.clientY - rect.top) * engine.getRenderHeight() * scale / rect.height
+      navigator.pickAt(x, y)
+    })
+    for (const event of ['pointercancel', 'pointerleave']) listen(canvas, event, () => { down = null })
+    listen(window, 'resize', () => { if (active()) engine.resize() })
+    listen(document, 'visibilitychange', () => {
+      if (disposed || lost) return
+      if (document.hidden) { navigator.pause(); if (frame !== null) window.cancelAnimationFrame(frame); frame = null }
+      else { engine.resize(); navigator.resume(); if (frame === null) frame = window.requestAnimationFrame(loop) }
+    })
+    listen(canvas, 'webglcontextlost', event => {
+      event.preventDefault()
+      lost = true
+      navigator.pause()
+      if (frame !== null) window.cancelAnimationFrame(frame)
+      frame = null
+      available({ status: 'unavailable', reason: 'graphics-context-lost' })
+    })
+    if (motion) listen(motion, 'change', applyMotion)
+    if (document.hidden) navigator.pause()
+    else frame = window.requestAnimationFrame(loop)
+    available({ status: mounted.status, reducedMotion: Boolean(motion?.matches) })
+    return Object.freeze({
+      get status() { return disposed || lost ? 'unavailable' : navigator.snapshot().sceneNodes ? 'ready' : 'empty' },
+      select(ref, options) { return active() ? navigator.select(ref, options) : { status: 'unavailable' } },
+      selectEdge(edgeId, options) { return active() ? navigator.selectEdge(edgeId, options) : { status: 'unavailable' } },
+      receiveSelection(selection) { return active() ? navigator.receiveSelection(selection) : { status: 'unavailable' } },
+      focus(ref) { return active() ? navigator.focus(ref) : { status: 'unavailable' } },
+      expand(ref, direction) { return active() ? navigator.expand(ref, direction) : { status: 'unavailable' } },
+      openEvidence(evidenceId) { return active() ? navigator.openEvidence(evidenceId) : { status: 'unavailable' } },
+      setQuestion(questionId) { return active() ? navigator.setQuestion(questionId) : { status: 'unavailable' } },
+      setLens(lens) { if (!active()) return { status: 'unavailable' }; return present(navigator.setLens(lens)) },
+      update(next) { if (!active()) return { status: 'unavailable' }; return present(navigator.update(next)) },
+      fit() { if (active()) fit() },
+      reset() {
+        if (!active()) return
+        const result = navigator.setLens('all')
+        if (camera) { camera.alpha = Math.PI / 2; camera.beta = .7 }
+        present(result)
+      },
+      zoom(factor) { if (active() && camera && Number.isFinite(factor) && factor > 0) { camera.radius = Math.max(camera.lowerRadiusLimit, Math.min(camera.upperRadiusLimit, camera.radius * factor)); stopInertia() } },
+      pan(dx, dz) { if (active() && camera && Number.isFinite(dx) && Number.isFinite(dz)) { const target = camera.target; camera.setTarget(new B.Vector3(Math.max(-150, Math.min(150, target.x + dx)), target.y, Math.max(-150, Math.min(150, target.z + dz))), false, false, true); stopInertia() } },
+      snapshot() { return navigator?.snapshot() ?? null },
+      dispose,
+      clear: dispose,
+    })
+  } catch (error) {
+    dispose()
+    available({ status: 'unavailable', reason: 'graphics-unavailable' })
+    return unavailableHost('graphics-unavailable', dispose)
+  }
+}

package/src/graph-view/cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runGraphViewCommand } from './command.mjs'
+process.exitCode = await runGraphViewCommand(process.argv.slice(2))

package/src/graph-view/command.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs/promises'
+import { parseGraphView, refuse } from './contracts.mjs'
+
+// A consuming CLI binds its authenticated reader through this port. The
+// standalone validator reads fixture bytes only; a file is never an access grant.
+export async function runGraphViewCommand(argv, { reader, stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
+  try {
+    const flags = new Map()
+    for (let index = 0; index < argv.length; index += 2) {
+      const key = argv[index], value = argv[index + 1]
+      if (!['--validate', '--request', '--out'].includes(key) || !value || value.startsWith('--') || flags.has(key)) refuse('invalid_arguments')
+      flags.set(key, value)
+    }
+    let bytes
+    if (flags.has('--validate')) {
+      if (flags.has('--request') || flags.has('--out') || reader) refuse('invalid_arguments')
+      parseGraphView(await fs.readFile(flags.get('--validate'), 'utf8'))
+      stdout('graph-view fixture valid\n')
+      return 0
+    } else {
+      if (!reader || typeof reader.exportGraphView !== 'function') refuse('host_binding_required')
+      const request = flags.has('--request') ? JSON.parse(await fs.readFile(flags.get('--request'), 'utf8')) : {}
+      bytes = await reader.exportGraphView(request)
+    }
+    if (flags.has('--out')) await fs.writeFile(flags.get('--out'), bytes, { flag: 'wx', mode: 0o600 })
+    else stdout(bytes)
+    return 0
+  } catch (error) {
+    const known = ['invalid_arguments', 'host_binding_required', 'policy_refusal', 'stale_source', 'stale_cursor', 'unavailable', 'budget_exceeded', 'contract_mismatch', 'digest_mismatch']
+    const code = known.includes(error?.code) ? error.code : 'operation_failed'
+    stderr(`graph-view: ${code}\n`)
+    return 2
+  }
+}

package/src/graph-view/contracts.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs'
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { createHash } from 'node:crypto'
+import { refKey } from './refs.mjs'
+import { refuse } from './errors.mjs'
+export { refuse } from './errors.mjs'
+export { refKey } from './refs.mjs'
+
+export const GRAPH_VIEW_SCHEMA = 'atelier.graph-view@v1'
+export const MAX_VIEW_BYTES = 2 * 1024 * 1024
+const schema = JSON.parse(fs.readFileSync(new URL('../../contracts/atelier-graph-view.v1.schema.json', import.meta.url), 'utf8'))
+const ajv = new Ajv2020({ allErrors: false, strict: true })
+addFormats(ajv)
+ajv.addSchema(schema)
+const validators = new Map()
+export const canonicalJson = canonicalize
+export const digestJson = value => `sha256:${createHash('sha256').update(canonicalize(value)).digest('hex')}`
+export const compareText = (a, b) => a < b ? -1 : a > b ? 1 : 0
+export const sortedUnique = values => [...new Set(values)].sort(compareText)
+
+export function assertShape(name, value) {
+  const key = name ? `${schema.$id}#/$defs/${name}` : schema.$id
+  if (!validators.has(key)) validators.set(key, ajv.getSchema(key))
+  if (!validators.get(key)?.(value)) refuse('contract_mismatch')
+  return value
+}
+
+// Explicit schema properties are the only data boundary. No source body,
+// relation map, host binding, error detail, or arbitrary ext object passes.
+export function projectShape(name, value) {
+  const visit = (shape, input) => {
+    if (shape.$ref) return visit(schema.$defs[shape.$ref.split('/').at(-1)], input)
+    if (shape.type === 'object' && input && typeof input === 'object' && !Array.isArray(input)) {
+      const result = {}
+      for (const [key, child] of Object.entries(shape.properties ?? {})) {
+        if (Object.hasOwn(input, key)) result[key] = visit(child, input[key])
+      }
+      return result
+    }
+    if (shape.type === 'array' && Array.isArray(input)) return input.map(item => visit(shape.items, item))
+    return input
+  }
+  return assertShape(name, visit(schema.$defs[name], value))
+}
+
+export function assertRelativePath(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/') || /^[A-Za-z]:/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..') || /[\u0000-\u001f\u007f]/.test(value)) refuse('contract_mismatch')
+}
+
+export function serializeGraphView(view) {
+  assertShape(null, view)
+  const nodeIds = new Set(view.nodes.map(node => refKey(node.ref)))
+  const edgeIds = new Set(view.edges.map(edge => edge.edgeId))
+  const evidenceIds = new Set(view.evidence.map(item => item.evidenceId))
+  if (nodeIds.size !== view.nodes.length || edgeIds.size !== view.edges.length || evidenceIds.size !== view.evidence.length) refuse('contract_mismatch')
+  for (const edge of view.edges) {
+    if (!nodeIds.has(refKey(edge.source)) || !nodeIds.has(refKey(edge.target)) || edge.supportRefs.length === 0 || !edge.supportRefs.includes(edge.sourceRef) || edge.supportRefs.some(id => !evidenceIds.has(id))) refuse('contract_mismatch')
+  }
+  for (const item of [...view.questions, ...view.diagnostics]) {
+    if (item.nodeRefs.some(ref => !nodeIds.has(refKey(ref))) || [...item.evidenceRefs, ...(item.contradictingRefs ?? [])].some(id => !evidenceIds.has(id))) refuse('contract_mismatch')
+  }
+  for (const table of ['nodes', 'edges', 'evidence', 'questions', 'diagnostics']) if (view.page.returned[table] !== view[table].length) refuse('contract_mismatch')
+  if (view.page.truncated !== Object.values(view.page.omitted).some(value => value > 0)) refuse('contract_mismatch')
+  const { projectionDigest, ...payload } = view
+  if (digestJson(payload) !== projectionDigest) refuse('digest_mismatch')
+  const bytes = `${canonicalize(view)}\n`
+  if (Buffer.byteLength(bytes) > MAX_VIEW_BYTES) refuse('budget_exceeded')
+  return bytes
+}
+
+export function parseGraphView(bytes) {
+  if (typeof bytes !== 'string' || Buffer.byteLength(bytes) > MAX_VIEW_BYTES) refuse('budget_exceeded')
+  let view
+  try { view = JSON.parse(bytes) } catch { refuse('contract_mismatch') }
+  serializeGraphView(view)
+  return view
+}

package/src/graph-view/errors.mjs

@@ -0,0 +1,5 @@
+export function refuse(code) {
+  const error = new Error(`graph-view: ${code}`)
+  error.code = code
+  throw error
+}

package/src/graph-view/index.mjs

@@ -0,0 +1,4 @@
+export { GRAPH_VIEW_SCHEMA, MAX_VIEW_BYTES, parseGraphView, serializeGraphView } from './contracts.mjs'
+export { createGraphViewReader } from './query.mjs'
+export { runGraphViewCommand } from './command.mjs'
+export { assertGraphViewIntent } from './intents.mjs'

package/src/graph-view/intents.mjs

@@ -0,0 +1,30 @@
+import { deepFreeze } from '../composition/wire.mjs'
+import { refKey } from './refs.mjs'
+import { refuse } from './errors.mjs'
+
+// Validation emits no action. A host must separately revalidate current grants
+// and source before accepting any stale-sensitive operation.
+export function assertGraphViewIntent(view, intent) {
+  if (!intent || intent.projectionDigest !== view.projectionDigest) refuse('stale_source')
+  const specifications = {
+    select: ['type', 'projectionDigest', ...(Object.hasOwn(intent, 'ref') ? ['ref'] : ['edgeId'])],
+    expand: ['type', 'projectionDigest', 'ref', 'direction'],
+    openEvidence: ['type', 'projectionDigest', 'evidenceId'],
+    setQuestion: ['type', 'projectionDigest', 'questionId'],
+    compareSnapshots: ['type', 'projectionDigest', 'a', 'b'],
+    proposeModelChange: ['type', 'projectionDigest', 'draftRef'],
+  }
+  const allowed = Object.hasOwn(specifications, intent.type) ? specifications[intent.type] : null
+  if (!allowed || Object.keys(intent).sort().join(',') !== allowed.sort().join(',')) refuse('contract_mismatch')
+  if (intent.ref) {
+    if (Object.keys(intent.ref).sort().join(',') !== 'localId,repoId' || !view.nodes.some(node => refKey(node.ref) === refKey(intent.ref))) refuse('unavailable')
+  }
+  if (intent.edgeId && !view.edges.some(edge => edge.edgeId === intent.edgeId)) refuse('unavailable')
+  if (intent.type === 'select' && !intent.ref && !intent.edgeId) refuse('contract_mismatch')
+  if (intent.type === 'expand' && (!intent.ref || !['in', 'out', 'both'].includes(intent.direction) || !view.capabilities.queries.includes('neighborhood'))) refuse('contract_mismatch')
+  if (intent.type === 'openEvidence' && !view.evidence.some(item => item.evidenceId === intent.evidenceId)) refuse('unavailable')
+  if (intent.type === 'setQuestion' && !view.questions.some(item => item.questionId === intent.questionId)) refuse('unavailable')
+  if (intent.type === 'compareSnapshots' && ![intent.a, intent.b].every(value => typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value))) refuse('contract_mismatch')
+  if (intent.type === 'proposeModelChange' && (!view.capabilities.proposalIntents.includes('proposeModelChange') || typeof intent.draftRef !== 'string' || !intent.draftRef || intent.draftRef.length > 512)) refuse('policy_refusal')
+  return deepFreeze(JSON.parse(JSON.stringify(intent)))
+}

package/src/graph-view/query.mjs

@@ -0,0 +1,213 @@
+import { VALID_RELATIONS } from '../graph/graph.mjs'
+import { GRAPH_VIEW_SCHEMA, assertShape, assertRelativePath, projectShape, digestJson, canonicalJson, refKey, compareText, sortedUnique, refuse, serializeGraphView } from './contracts.mjs'
+
+const TABLES = ['nodes', 'edges', 'evidence', 'questions', 'diagnostics']
+const keys = { nodes: item => refKey(item.ref), edges: item => item.edgeId, evidence: item => item.evidenceId, questions: item => item.questionId, diagnostics: item => item.diagnosticId }
+const shapes = { nodes: 'node', edges: 'edge', evidence: 'evidence', questions: 'question', diagnostics: 'diagnostic' }
+const sourceKey = pin => canonicalJson([pin.repoId, pin.path, pin.revision, pin.digest])
+const sortRefs = refs => refs.sort((a, b) => compareText(refKey(a), refKey(b)))
+const count = tables => Object.fromEntries(TABLES.map(key => [key, tables[key].length]))
+
+function indexUnique(items, key) {
+  const result = new Map()
+  for (const item of items) {
+    const id = key(item)
+    if (result.has(id)) refuse('contract_mismatch')
+    result.set(id, item)
+  }
+  return result
+}
+
+function normalize(raw) {
+  if (!raw || typeof raw.producerVersion !== 'string' || !raw.producerVersion || raw.producerVersion.length > 128) refuse('contract_mismatch')
+  if (!['complete', 'incomplete'].includes(raw.completeness)) refuse('contract_mismatch')
+  const graph = { producerVersion: raw.producerVersion, completeness: raw.completeness }
+  graph.sourceSnapshot = projectShape('sourceSnapshot', {
+    ...raw.sourceSnapshot,
+    repositories: raw.sourceSnapshot?.repositories?.map(repo => ({ ...repo, omittedFiles: 0 })),
+  })
+  const expiry = raw.accessContext?.expiresAt
+  graph.accessContext = projectShape('accessContext', { ...raw.accessContext, expiresAt: typeof expiry === 'number' && Number.isFinite(expiry) ? new Date(expiry).toISOString() : expiry })
+  graph.capabilities = projectShape('capabilities', { maxSlice: 500, maxDepth: 2, sourceReads: false, proposalIntents: [], queries: ['metadata-search', 'neighborhood', 'question', 'source-impact'], ...raw.capabilities })
+  graph.accessContext.authorizedRepoIds = sortedUnique(graph.accessContext.authorizedRepoIds)
+  graph.capabilities.queries = sortedUnique(graph.capabilities.queries)
+  graph.capabilities.proposalIntents = sortedUnique(graph.capabilities.proposalIntents)
+  const repositories = indexUnique(graph.sourceSnapshot.repositories, repo => repo.repoId)
+  if ([...repositories.keys()].some(id => !graph.accessContext.authorizedRepoIds.includes(id))) refuse('contract_mismatch')
+  for (const repo of repositories.values()) {
+    indexUnique(repo.files, file => file.path)
+    for (const file of repo.files) assertRelativePath(file.path)
+    repo.files.sort((a, b) => compareText(a.path, b.path))
+  }
+  graph.sourceSnapshot.repositories.sort((a, b) => compareText(a.repoId, b.repoId))
+  for (const table of TABLES) {
+    if (!Array.isArray(raw[table]) || raw[table].length > 20000) refuse('budget_exceeded')
+    graph[table] = raw[table].map(item => projectShape(shapes[table], table === 'diagnostics' && item.code === 'authorized-source-unavailable' ? { ...item, diagnosticId: digestJson({ code: item.code, repoId: item.repoId }) } : item))
+    indexUnique(graph[table], keys[table])
+    graph[table].sort((a, b) => compareText(keys[table](a), keys[table](b)))
+  }
+  const missingRepositories = graph.accessContext.authorizedRepoIds.filter(id => !repositories.has(id))
+  const unavailable = graph.diagnostics.filter(item => item.code === 'authorized-source-unavailable').map(item => item.repoId).sort(compareText)
+  if (canonicalJson(missingRepositories) !== canonicalJson(unavailable) || (missingRepositories.length > 0 && graph.completeness !== 'incomplete') || graph.diagnostics.some(item => item.repoId && !graph.accessContext.authorizedRepoIds.includes(item.repoId))) refuse('contract_mismatch')
+  for (const node of graph.nodes) node.tags = sortedUnique(node.tags)
+  if (raw.edges.some(edge => edge.eligible === false)) refuse('contract_mismatch')
+  for (const edge of graph.edges) {
+    if (edge.predicate !== 'links_to' && !VALID_RELATIONS.has(edge.predicate)) refuse('contract_mismatch')
+    edge.supportRefs = sortedUnique(edge.supportRefs)
+    edge.reviewRefs = sortedUnique(edge.reviewRefs)
+  }
+  for (const item of [...graph.questions, ...graph.diagnostics]) {
+    sortRefs(item.nodeRefs)
+    item.evidenceRefs = sortedUnique(item.evidenceRefs)
+    if (item.contradictingRefs) item.contradictingRefs = sortedUnique(item.contradictingRefs)
+    if (item.gaps) item.gaps = sortedUnique(item.gaps)
+  }
+  const nodes = new Map(graph.nodes.map(node => [refKey(node.ref), node]))
+  const evidence = new Map(graph.evidence.map(item => [item.evidenceId, item]))
+  const checkSource = (source, verified = true) => {
+    assertRelativePath(source.path)
+    if (source.locator?.rangeDigest && !source.locator.range) refuse('contract_mismatch')
+    for (const range of [source.locator?.range, source.locator?.targetRange].filter(Boolean)) {
+      if (range.end < range.start || (range.byteStart === undefined) !== (range.byteEnd === undefined) || (range.byteStart !== undefined && range.byteEnd < range.byteStart)) refuse('contract_mismatch')
+    }
+    const repo = repositories.get(source.repoId)
+    if (!repo) refuse('contract_mismatch')
+    if (verified && (source.revision !== repo.digest || !repo.files.some(file => file.path === source.path && file.rawDigest === source.digest))) refuse('contract_mismatch')
+  }
+  for (const node of graph.nodes) {
+    if (node.ref.repoId !== node.sourceRef.repoId) refuse('contract_mismatch')
+    checkSource(node.sourceRef)
+  }
+  for (const item of graph.evidence) checkSource(item.sourceRef, item.verification === 'verified-source')
+  for (const repo of repositories.values()) for (const field of ['config', 'plan']) if (repo.inputs[field]) {
+    if (repo.inputs[field].repoId !== repo.repoId) refuse('contract_mismatch')
+    checkSource(repo.inputs[field])
+  }
+  for (const edge of graph.edges) {
+    if (!nodes.has(refKey(edge.source)) || !nodes.has(refKey(edge.target)) || !evidence.has(edge.sourceRef) || !edge.supportRefs.includes(edge.sourceRef) || edge.supportRefs.length === 0 || edge.supportRefs.some(id => !evidence.has(id))) refuse('contract_mismatch')
+  }
+  for (const item of [...graph.questions, ...graph.diagnostics]) {
+    if (item.nodeRefs.some(ref => !nodes.has(refKey(ref))) || [...item.evidenceRefs, ...(item.contradictingRefs ?? [])].some(id => !evidence.has(id))) refuse('contract_mismatch')
+  }
+  return graph
+}
+
+function normalizedRequest(request, graph) {
+  assertShape('request', request)
+  if (request.limit && request.limit > graph.capabilities.maxSlice) refuse('budget_exceeded')
+  if ((request.depth ?? 0) > graph.capabilities.maxDepth) refuse('budget_exceeded')
+  if (request.search && !graph.capabilities.queries.includes('metadata-search') || request.questionId && !graph.capabilities.queries.includes('question') || request.focusRef && !graph.capabilities.queries.includes('neighborhood')) refuse('policy_refusal')
+  const query = {
+    questionId: request.questionId ?? null,
+    focusRef: request.focusRef ?? null,
+    relationFilter: sortedUnique(request.relationFilter ?? []),
+    direction: request.direction ?? 'both',
+    depth: request.depth ?? 0,
+    limit: request.limit ?? Math.min(100, graph.capabilities.maxSlice),
+    search: (request.search ?? '').normalize('NFC').trim().toLowerCase(),
+  }
+  if (query.depth > 0 && !query.focusRef) refuse('contract_mismatch')
+  return query
+}
+
+function slice(graph, query, request, snapshot) {
+  let candidates = graph.nodes
+  let question = null
+  if (query.questionId) {
+    question = graph.questions.find(item => item.questionId === query.questionId)
+    if (!question) refuse('unavailable')
+    const allowed = new Set(question.nodeRefs.map(refKey))
+    candidates = candidates.filter(node => allowed.has(refKey(node.ref)))
+  }
+  if (query.focusRef) {
+    const focus = refKey(query.focusRef)
+    if (!graph.nodes.some(node => refKey(node.ref) === focus)) refuse('unavailable')
+    const visited = new Set([focus])
+    let frontier = new Set([focus])
+    for (let depth = 0; depth < query.depth; depth += 1) {
+      const next = new Set()
+      for (const edge of graph.edges) {
+        if (query.relationFilter.length && !query.relationFilter.includes(edge.predicate)) continue
+        const from = refKey(edge.source), to = refKey(edge.target)
+        if (query.direction !== 'in' && frontier.has(from)) next.add(to)
+        if (query.direction !== 'out' && frontier.has(to)) next.add(from)
+      }
+      frontier = new Set([...next].filter(key => !visited.has(key)))
+      for (const key of frontier) visited.add(key)
+    }
+    candidates = candidates.filter(node => visited.has(refKey(node.ref)))
+  }
+  if (query.search) candidates = candidates.filter(node => [node.title, node.summary, ...node.tags].some(value => value.toLowerCase().includes(query.search)))
+  const queryDigest = digestJson({ snapshot, query })
+  let offset = 0
+  if (request.cursor) {
+    let cursor
+    try { cursor = JSON.parse(Buffer.from(request.cursor, 'base64url').toString('utf8')) } catch { refuse('stale_cursor') }
+    if (!cursor || Object.keys(cursor).sort().join(',') !== 'offset,queryDigest' || cursor.queryDigest !== queryDigest || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset >= candidates.length || cursor.offset % query.limit !== 0) refuse('stale_cursor')
+    offset = cursor.offset
+  }
+  const nodes = candidates.slice(offset, offset + query.limit)
+  const candidateRefs = new Set(candidates.map(node => refKey(node.ref)))
+  const visibleRefs = new Set(nodes.map(node => refKey(node.ref)))
+  const matchingEdges = graph.edges.filter(edge => candidateRefs.has(refKey(edge.source)) && candidateRefs.has(refKey(edge.target)) && (!query.relationFilter.length || query.relationFilter.includes(edge.predicate)))
+  const edges = matchingEdges.filter(edge => visibleRefs.has(refKey(edge.source)) && visibleRefs.has(refKey(edge.target))).slice(0, Math.min(2000, query.limit * 4))
+  const needed = new Set(edges.flatMap(edge => [edge.sourceRef, ...edge.supportRefs]))
+  const nodeSources = new Set(nodes.map(node => sourceKey(node.sourceRef)))
+  for (const item of graph.evidence) if (nodeSources.has(sourceKey(item.sourceRef))) needed.add(item.evidenceId)
+  const selectedQuestions = (question ? [question] : graph.questions.filter(item => (!query.focusRef && !query.search) || item.nodeRefs.some(ref => visibleRefs.has(refKey(ref))))).slice(0, 100)
+  for (const item of selectedQuestions) for (const id of [...item.evidenceRefs, ...item.contradictingRefs]) needed.add(id)
+  if (needed.size > 4000) refuse('budget_exceeded')
+  const evidence = graph.evidence.filter(item => needed.has(item.evidenceId))
+  const evidenceIds = new Set(evidence.map(item => item.evidenceId))
+  const questions = selectedQuestions.map(item => ({ ...item, nodeRefs: item.nodeRefs.filter(ref => visibleRefs.has(refKey(ref))), omissionState: item.nodeRefs.some(ref => !visibleRefs.has(refKey(ref))) ? 'bounded' : item.omissionState }))
+  const diagnostics = graph.diagnostics.filter(item => item.nodeRefs.every(ref => visibleRefs.has(refKey(ref))) && item.evidenceRefs.every(id => evidenceIds.has(id))).slice(0, query.limit)
+  const selected = { nodes, edges, evidence, questions, diagnostics }
+  const total = { nodes: candidates, edges: matchingEdges, evidence: graph.evidence, questions: question ? [question] : graph.questions, diagnostics: graph.diagnostics }
+  const returned = count(selected), totals = count(total)
+  const omitted = Object.fromEntries(TABLES.map(key => [key, totals[key] - returned[key]]))
+  const nextCursor = offset + nodes.length < candidates.length ? Buffer.from(canonicalJson({ offset: offset + nodes.length, queryDigest })).toString('base64url') : null
+  const sourcePins = [...nodes.map(node => node.sourceRef), ...evidence.map(item => item.sourceRef), ...graph.sourceSnapshot.repositories.flatMap(repo => [repo.inputs.config, repo.inputs.plan]).filter(Boolean)]
+  const sourceSnapshot = { ...graph.sourceSnapshot, repositories: graph.sourceSnapshot.repositories.map(repo => {
+    const selectedPaths = new Set(sourcePins.filter(pin => pin.repoId === repo.repoId).map(pin => pin.path))
+    const files = repo.files.filter(file => selectedPaths.has(file.path))
+    return { ...repo, files, omittedFiles: repo.files.length - files.length }
+  }) }
+  const payload = { schema: GRAPH_VIEW_SCHEMA, producerVersion: graph.producerVersion, snapshot, completeness: graph.completeness, sourceSnapshot, accessContext: graph.accessContext, ...selected, capabilities: graph.capabilities, query, page: { offset, limit: query.limit, returned, omitted, truncated: Object.values(omitted).some(value => value > 0), nextCursor } }
+  return { ...payload, projectionDigest: digestJson(payload) }
+}
+
+// Host-only ports close over authenticated context. No caller-supplied graph,
+// identity, scope, or grant enters the request. Nothing is cached here.
+export function createGraphViewReader({ loadAuthorizedGraph, revalidate, now = () => Date.now() }) {
+  if (typeof loadAuthorizedGraph !== 'function' || typeof revalidate !== 'function' || typeof now !== 'function') throw new TypeError('graph-view host ports required')
+  const run = async (request, operation) => {
+    assertShape('request', request)
+    let loaded
+    try { loaded = await loadAuthorizedGraph({ operation }) } catch { refuse('policy_refusal') }
+    if (!loaded?.binding || !loaded.graph) refuse('policy_refusal')
+    let view, bytes, pendingError
+    const expiresAt = typeof loaded.graph?.accessContext?.expiresAt === 'number' ? loaded.graph.accessContext.expiresAt : Date.parse(loaded.graph?.accessContext?.expiresAt)
+    try {
+      const graph = normalize(loaded.graph)
+      const snapshot = digestJson(graph)
+      if (request.snapshot && request.snapshot !== snapshot) refuse('stale_source')
+      const query = normalizedRequest(request, graph)
+      if (operation === 'export' && graph.capabilities.export !== true) refuse('policy_refusal')
+      view = slice(graph, query, request, snapshot)
+      bytes = serializeGraphView(view)
+    } catch (error) { pendingError = error }
+    let current = false
+    try { current = await revalidate(loaded.binding) } catch { refuse('policy_refusal') }
+    const deliveredAt = now()
+    if (current !== true || !Number.isFinite(expiresAt) || !Number.isFinite(deliveredAt) || deliveredAt >= expiresAt) refuse('policy_refusal')
+    if (pendingError) {
+      if (!['contract_mismatch', 'budget_exceeded', 'policy_refusal', 'stale_source', 'stale_cursor', 'unavailable'].includes(pendingError.code)) refuse('contract_mismatch')
+      throw pendingError
+    }
+    return { view, bytes }
+  }
+  return Object.freeze({
+    readGraphView: async (request = {}) => (await run(request, 'read')).view,
+    exportGraphView: async (request = {}) => (await run(request, 'export')).bytes,
+  })
+}

package/src/graph-view/refs.mjs

@@ -0,0 +1,2 @@
+// The qualified identity is supplied by the source owner; never title-derived.
+export const refKey = ref => JSON.stringify([ref.repoId, ref.localId])