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

package/src/graph-access/index.mjs

@@ -0,0 +1,253 @@
+// Graph adapter over host-owned access decisions. No authentication store.
+import { createHash } from 'node:crypto'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { deepFreeze } from '../composition/wire.mjs'
+
+const hash = value => createHash('sha256').update(canonicalize(value)).digest('hex')
+const sourceDigest = value => `sha256:${hash(value)}`
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0
+const digest = value => typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value)
+const revision = value => typeof value === 'string' && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value)
+const string = (value, max = 512) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f]/u.test(value)
+const equal = (a, b) => canonicalize(a) === canonicalize(b)
+const key = ref => canonicalize([ref.repoId, ref.localId])
+const ref = value => value && string(value.repoId) && string(value.localId)
+const path = value => string(value, 2048) && !value.includes('\\') && !value.startsWith('/') && !/^[A-Za-z]:/.test(value) && !value.split('/').some(p => ['', '.', '..'].includes(p))
+const list = (value, max = 10000) => Array.isArray(value) && value.length <= max
+const need = value => { if (!value) throw new GraphAccessRefusal() }
+const immutable = value => deepFreeze(structuredClone(value))
+const validScope = s => s && typeof s === 'object' && !Array.isArray(s) &&
+  Object.keys(s).sort().join(',') === 'base,exclude,include' && (s.base === '' || s.base === '.' || path(s.base)) &&
+  [s.include, s.exclude].every(v => v === null || string(v, 2048))
+
+export class GraphAccessRefusal extends Error {
+  constructor() { super('Graph access unavailable'); this.name = 'GraphAccessRefusal' }
+}
+
+function bounded(value) {
+  // The adapter accepts JSON data from a trusted loader, never browser bundles.
+  // Existing canonicalization refuses undefined, classes and nonfinite values.
+  const bytes = canonicalize(value)
+  need(Buffer.byteLength(bytes) <= 8 * 1024 * 1024)
+  return immutable(value)
+}
+
+/** Pin the complete normalized candidate using the existing JCS serializer. */
+export function digestAccessCandidate(value) { return sourceDigest(bounded(value)) }
+
+function validateDecision(input, operation, now) {
+  const d = bounded(input)
+  need(d.operation === operation && ['read', 'export'].includes(operation))
+  for (const k of ['principalRef', 'proofRef', 'grantRevision', 'policyRevision']) need(string(d[k]))
+  need(Number.isSafeInteger(d.expiresAt) && d.expiresAt > now)
+  need(list(d.repositories, 64))
+  const seen = new Set()
+  for (const r of d.repositories) {
+    need(string(r.repoId) && !seen.has(r.repoId) && string(r.ownerRef))
+    need(revision(r.head) && revision(r.tree) && digest(r.snapshotDigest) && digest(r.contributionDigest))
+    need(validScope(r.scope))
+    seen.add(r.repoId)
+  }
+  return d
+}
+
+function snapshotFor(c, approved) {
+  const s = c.snapshot
+  need(c.repository.repoId === approved.repoId && c.repository.ownerRef === approved.ownerRef)
+  need(s.repoId === approved.repoId && s.head === approved.head && s.tree === approved.tree && s.digest === approved.snapshotDigest)
+  need(validScope(s.scope) && equal(s.scope, approved.scope) && typeof s.dirty === 'boolean' && list(s.files))
+  const seen = new Set()
+  for (const f of s.files) {
+    need(path(f.path) && digest(f.rawDigest) && Number.isSafeInteger(f.byteLength) && f.byteLength >= 0 && !seen.has(f.path))
+    seen.add(f.path)
+  }
+  return { repoId: approved.repoId, head: s.head, tree: s.tree, dirty: s.dirty, scope: s.scope,
+    files: s.files.map(f => ({ path: f.path, rawDigest: f.rawDigest, byteLength: f.byteLength })).sort((a, b) => compare(a.path, b.path)), digest: s.digest }
+}
+
+function validLocator(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  if (!Object.keys(value).every(k => ['pointer', 'range', 'targetRange', 'rangeDigest'].includes(k))) return false
+  if (value.rangeDigest !== undefined && (!digest(value.rangeDigest) || !value.range || !Number.isSafeInteger(value.range.byteStart) || !Number.isSafeInteger(value.range.byteEnd))) return false
+  if (value.pointer !== undefined && (typeof value.pointer !== 'string' || value.pointer.length > 1024 || (value.pointer !== '' && !value.pointer.startsWith('/')))) return false
+  for (const k of ['range', 'targetRange']) {
+    const r = value[k]
+    if (r === undefined) continue
+    if (!r || !Object.keys(r).every(k => ['start', 'end', 'byteStart', 'byteEnd'].includes(k))) return false
+    if (![r.start, r.end].every(n => Number.isSafeInteger(n) && n >= 0) || r.end < r.start) return false
+    if ((r.byteStart === undefined) !== (r.byteEnd === undefined)) return false
+    if (r.byteStart !== undefined && (![r.byteStart, r.byteEnd].every(n => Number.isSafeInteger(n) && n >= 0) || r.byteEnd < r.byteStart)) return false
+  }
+  return Object.keys(value).length > 0
+}
+
+function source(value, snapshots) {
+  if (!value || !path(value.path) || !string(value.repoId) || !digest(value.revision) || !digest(value.digest)) return null
+  const s = snapshots.get(value.repoId)
+  const file = s?.files.find(f => f.path === value.path && f.rawDigest === value.digest)
+  if (!s || value.revision !== s.digest || !file) return null
+  if (value.locator !== undefined && !validLocator(value.locator)) return null
+  for (const range of [value.locator?.range, value.locator?.targetRange]) {
+    if (range && (range.end > file.byteLength || (range.byteEnd !== undefined && range.byteEnd > file.byteLength))) return null
+  }
+  return { repoId: value.repoId, path: value.path, revision: value.revision, digest: value.digest,
+    ...(value.locator === undefined ? {} : { locator: value.locator }) }
+}
+
+function projectedNode(n, repoId, snapshots) {
+  if (!ref(n.ref) || n.ref.repoId !== repoId || n.displayEligible === false) return null
+  const pin = source(n.sourceRef, snapshots)
+  if (!pin || pin.repoId !== repoId) return null
+  for (const k of ['sourceKind', 'title', 'classification', 'lifecycle']) if (!string(n[k], k === 'title' ? 1024 : 128)) return null
+  if (typeof n.summary !== 'string' || n.summary.length > 8192 || !list(n.tags, 64) || !n.tags.every(t => string(t, 256))) return null
+  return { ref: { repoId, localId: n.ref.localId }, sourceKind: n.sourceKind, title: n.title, summary: n.summary,
+    classification: n.classification, lifecycle: n.lifecycle, tags: [...new Set(n.tags)].sort(), sourceRef: pin, displayEligible: true }
+}
+
+/**
+ * Trusted host ports establish principal, grants, source ownership and freshness.
+ * A local host may do this only over its operator's deliberately permitted clones.
+ * Audience, readBoundary, Git authors and browser claims never supply these ports.
+ * The contribution is a normalized projection pinned by the decision's digest;
+ * verifyContribution must check the owning producer's exact bytes and scope,
+ * including any locator.rangeDigest over its exact raw byte slice.
+ */
+export function createGraphAccess(ports, { now = Date.now } = {}) {
+  for (const name of ['resolveAccess', 'loadContribution', 'verifyContribution', 'evaluateEdge', 'revalidate']) need(typeof ports?.[name] === 'function')
+  need(typeof now === 'function')
+  const handles = new WeakMap()
+  const time = () => { const n = now(); need(Number.isSafeInteger(n)); return n }
+  const live = (state, signal) => {
+    try { need(!signal?.aborted && !state.invalid && state.decision.expiresAt > time()) }
+    catch { state.invalid = true; state.graph = null; throw new GraphAccessRefusal() }
+  }
+  const fresh = async (state, signal) => {
+    try {
+      live(state, signal)
+      need(await ports.revalidate(state.decision, signal) === true)
+      live(state, signal)
+    } catch { state.invalid = true; state.graph = null; throw new GraphAccessRefusal() }
+  }
+  const stateFor = binding => { const s = handles.get(binding); need(s); return s }
+
+  return Object.freeze({
+    async loadAuthorizedGraph(context, { operation = 'read', signal } = {}) {
+      let state
+      try {
+        need(['read', 'export'].includes(operation) && !signal?.aborted)
+        const decision = validateDecision(await ports.resolveAccess(context, { operation, signal }), operation, time())
+        state = { decision, invalid: false }
+        await fresh(state, signal); live(state, signal)
+        const contributions = [], snapshots = new Map(), diagnostics = []
+        // Only the approved set is enumerated. A denied repo cannot affect loader
+        // calls, raw exceptions, counts, diagnostics, cache keys or search input.
+        for (const approved of [...decision.repositories].sort((a, b) => compare(a.repoId, b.repoId))) {
+          await fresh(state, signal); live(state, signal)
+          try {
+            const c = bounded(await ports.loadContribution(approved, { operation, signal }))
+            need(sourceDigest(c) === approved.contributionDigest)
+            need(await ports.verifyContribution(c, approved, { operation, signal }) === true)
+            const snapshot = snapshotFor(c, approved)
+            need(list(c.nodes) && list(c.edges) && list(c.evidence))
+            // Intrinsic records must belong to this exact verified contribution.
+            // A stale/invalid authorized record makes its source incomplete;
+            // do not silently call the remaining subset a complete snapshot.
+            const localSnapshots = new Map([[approved.repoId, snapshot]])
+            for (const n of c.nodes) need(n?.displayEligible === false || projectedNode(n, approved.repoId, localSnapshots))
+            for (const e of c.evidence) {
+              const pin = source(e?.sourceRef, localSnapshots)
+              need(string(e?.evidenceId) && pin?.repoId === approved.repoId)
+            }
+            snapshots.set(approved.repoId, snapshot)
+            contributions.push(c)
+          } catch {
+            diagnostics.push({ code: 'authorized-source-unavailable', severity: 'warning', repoId: approved.repoId,
+              nodeRefs: [], evidenceRefs: [], action: 'Refresh the authorized source.' })
+          }
+          await fresh(state, signal); live(state, signal)
+        }
+        const nodes = [], evidence = [], edges = [], nodeKeys = new Set(), evidenceIds = new Set(), edgeIds = new Set()
+        for (const c of contributions) {
+          for (const raw of c.nodes) {
+            const n = projectedNode(raw, c.repository.repoId, snapshots)
+            if (!n) continue
+            need(!nodeKeys.has(key(n.ref))); nodeKeys.add(key(n.ref)); nodes.push(n)
+          }
+          for (const raw of c.evidence) {
+            const pin = source(raw.sourceRef, snapshots)
+            if (!string(raw.evidenceId) || !pin || pin.repoId !== c.repository.repoId) continue
+            need(!evidenceIds.has(raw.evidenceId)); evidenceIds.add(raw.evidenceId)
+            evidence.push({ evidenceId: raw.evidenceId, sourceRef: pin, verification: 'verified-source' })
+          }
+        }
+        for (const c of contributions) for (const raw of c.edges) {
+          // Cross-repository topology disappears before the policy port runs.
+          if (!string(raw.edgeId) || !ref(raw.source) || !ref(raw.target) || !nodeKeys.has(key(raw.source)) || !nodeKeys.has(key(raw.target))) continue
+          const home = source(raw.sourceRef, snapshots)
+          if (!home || home.repoId !== c.repository.repoId || !list(raw.supportRefs, 64) || !raw.supportRefs.every(id => evidenceIds.has(id))) continue
+          if (new Set(raw.supportRefs).size !== raw.supportRefs.length) continue
+          await fresh(state, signal); live(state, signal)
+          // The edge owner verifies its immutable record, signatures and policy.
+          // A contribution's eligible/accepted flags have no authority.
+          const result = bounded(await ports.evaluateEdge(raw, decision, { signal }))
+          if (result.eligible !== true || result.edgeId !== raw.edgeId || !equal(result.source, raw.source) || !equal(result.target, raw.target) || !equal(result.supportRefs, raw.supportRefs)) continue
+          if (!string(result.predicate, 128) || !['hyperlink', 'source-declaration', 'reviewed-assertion'].includes(result.family)) continue
+          if (result.acceptanceState !== 'active' || result.supportRefs.length === 0 || !result.supportRefs.includes(result.sourceRef)) continue
+          if (!['navigation', 'source-declaration', 'reviewed-assertion'].includes(result.assurance) || !digest(result.recordDigest) || !digest(result.policyDigest)) continue
+          if (!list(result.qualifications, 64) || !result.qualifications.every(q => string(q, 2048))) continue
+          if (!list(result.reviewRefs, 64) || !result.reviewRefs.every(r => string(r, 2048))) continue
+          need(!edgeIds.has(result.edgeId)); edgeIds.add(result.edgeId)
+          edges.push({ edgeId: result.edgeId, source: { repoId: raw.source.repoId, localId: raw.source.localId },
+            target: { repoId: raw.target.repoId, localId: raw.target.localId }, predicate: result.predicate, family: result.family,
+            acceptanceState: 'active', supportRefs: [...result.supportRefs], sourceRef: result.sourceRef, eligible: true,
+            assurance: result.assurance, qualifications: [...result.qualifications], reviewRefs: [...result.reviewRefs],
+            recordDigest: result.recordDigest, policyDigest: result.policyDigest })
+        }
+        nodes.sort((a, b) => compare(key(a.ref), key(b.ref)))
+        edges.sort((a, b) => compare(a.edgeId, b.edgeId))
+        evidence.sort((a, b) => compare(a.evidenceId, b.evidenceId))
+        const sourceSnapshot = { repositories: [...snapshots.values()].map(s => {
+          const c = contributions.find(c => c.repository.repoId === s.repoId)
+          const input = name => {
+            const pin = source(c.inputs?.[name], snapshots)
+            return pin?.repoId === s.repoId ? pin : null
+          }
+          return { ...s, inputs: { config: input('config'), plan: input('plan') } }
+        }) }
+        // Source manifests may themselves mention denied targets. Only exact
+        // approved files/scope are admitted by the host; arbitrary diagnostics,
+        // relation arrays, search terms and source-wide summaries are not copied.
+        const graph = immutable({ producerVersion: 'atelier-graph-access/proposal-v1', sourceSnapshot,
+          accessContext: { proofRef: decision.proofRef, authorizedRepoIds: decision.repositories.map(r => r.repoId).sort(),
+            grantRevision: decision.grantRevision, policyRevision: decision.policyRevision, expiresAt: decision.expiresAt, filter: 'repository-grants' },
+          nodes, edges, evidence, questions: [], diagnostics,
+          completeness: diagnostics.length === 0 ? 'complete' : 'incomplete',
+          counts: { nodes: nodes.length, edges: edges.length, evidence: evidence.length },
+          capabilities: { read: true, export: operation === 'export' } })
+        const cacheKey = hash({ principalRef: decision.principalRef, proofRef: decision.proofRef, operation,
+          grantRevision: decision.grantRevision, policyRevision: decision.policyRevision, expiresAt: decision.expiresAt,
+          repositories: [...decision.repositories].sort((a, b) => compare(a.repoId, b.repoId)), graphDigest: hash(graph) })
+        const binding = Object.freeze({ cacheKey, expiresAt: decision.expiresAt })
+        state.graph = graph; state.operation = operation; handles.set(binding, state)
+        await fresh(state, signal); live(state, signal)
+        return Object.freeze({ graph, binding })
+      } catch { if (state) { state.invalid = true; state.graph = null }; throw new GraphAccessRefusal() }
+    },
+    async revalidate(binding, { signal } = {}) {
+      try { const state = stateFor(binding); await fresh(state, signal); live(state, signal); return true } catch { return false }
+    },
+    invalidate(binding) {
+      try { const state = stateFor(binding); state.invalid = true; state.graph = null; return true } catch { return false }
+    },
+    async guardArtifact(binding, graph, { operation = 'read', signal } = {}) {
+      try {
+        const state = stateFor(binding)
+        // Object identity prevents a copied/mixed artifact or caller label from
+        // becoming a reader-specific graph. Export needs a fresh export decision.
+        need(graph === state.graph && operation === state.operation)
+        await fresh(state, signal); live(state, signal)
+        return graph
+      } catch { throw new GraphAccessRefusal() }
+    },
+  })
+}

package/src/graph-access/multi-contribution-record-adapter.mjs

@@ -0,0 +1,101 @@
+// Recipient-scoped structural binding; the host supplies current grants and records.
+import { canonicalize } from '../attestation/jcs.mjs'
+import { edgeIdentity, immutable } from '../edge-policy/contract.mjs'
+import { edgeEvidenceOccurrences } from '../edge-policy/policy.mjs'
+import { sourceCitationFromProvenance } from '../edge-policy/source-citation-adapter.mjs'
+import { resolveLegacyNodeRef } from '../graph/repo-contribution.mjs'
+import { adaptRepositoryContribution } from './source-adapter.mjs'
+
+const invalid = 'Invalid multi-contribution edge record input'
+const missing = 'Required edge record repository is not selected'
+const oversized = 'Edge record exceeds graph access bounds'
+const need = (value, message = invalid) => { if (!value) throw new TypeError(message) }
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+const same = (a, b) => canonicalize(a) === canonicalize(b)
+const key = ref => canonicalize([ref.repoId, ref.localId])
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0
+
+function observedCitation(contribution, citation, kind) {
+  const matches = [...contribution.ordinaryLinks, ...contribution.declaredRelations].filter(observed => {
+    const pin = observed.provenance, range = pin.locator?.range
+    return (!kind || observed.origin === kind) && pin.repoId === citation.repoId && pin.path === citation.path &&
+      pin.revision === citation.revision && pin.digest === citation.fileDigest &&
+      range?.byteStart === citation.locator.byteStart && range?.byteEnd === citation.locator.byteEnd &&
+      same(sourceCitationFromProvenance(contribution, pin), citation)
+  })
+  need(matches.length === 1)
+  return matches[0]
+}
+
+/**
+ * Normalize one supplied full policy record over an explicitly selected set of
+ * native contributions and trusted ownerRefs. The caller must select permitted
+ * records AFTER checking current recipient grants. This pure function never
+ * authenticates a grant, accepts an assertion or verifies source bytes/custody.
+ * A missing dependency refuses the whole binding before any candidate returns.
+ * Rebuild the whole binding when grants change; never retain a partial slice of
+ * a previously authorized bundle. Every candidate must be complete before the
+ * host computes its contribution digest and invokes createGraphAccess.
+ * Optional topology must cover exactly the selected contribution set. Without
+ * it, unresolved cross-repository hyperlinks refuse rather than guess targets.
+ */
+export function adaptMultiContributionRecord(record, selected, options = {}) {
+  try {
+    need(plain(options) && Object.keys(options).every(name => name === 'topology'))
+    need(Array.isArray(selected) && selected.length > 0)
+    need(selected.length <= 64, oversized)
+    const { edgeId } = edgeIdentity(record)
+    const occurrences = edgeEvidenceOccurrences(record)
+    need(occurrences.length <= 64 && record.predicate.length <= 128, oversized)
+    const contributions = new Map(), candidates = new Map()
+    for (const entry of selected) {
+      need(plain(entry) && Object.keys(entry).sort().join(',') === 'contribution,ownerRef')
+      const candidate = adaptRepositoryContribution(entry.contribution, { ownerRef: entry.ownerRef })
+      const repoId = candidate.repository.repoId
+      need(!contributions.has(repoId))
+      contributions.set(repoId, entry.contribution)
+      candidates.set(repoId, candidate)
+    }
+    need([record.home, record.subject, record.object, ...occurrences.map(value => value.source)]
+      .every(value => contributions.has(value.repoId)), missing)
+    if (options.topology !== undefined) {
+      const topology = options.topology
+      need(plain(topology) && Array.isArray(topology.nodes) && Array.isArray(topology.ordinaryLinks))
+      need(topology.nodes.length === [...contributions.values()].reduce((total, value) => total + value.nodes.length, 0) &&
+        topology.nodes.every(node => contributions.has(node?.ref?.repoId)) &&
+        topology.ordinaryLinks.every(link => contributions.has(link?.source?.repoId)))
+      for (const entry of selected) candidates.set(entry.contribution.repository.repoId,
+        adaptRepositoryContribution(entry.contribution, { ownerRef: entry.ownerRef, topology }))
+    }
+    const nodeRefs = new Set([...contributions.values()].flatMap(value => value.nodes.map(node => key(node.ref))))
+    need(nodeRefs.has(key(record.subject)) && nodeRefs.has(key(record.object)))
+    const homeContribution = contributions.get(record.home.repoId)
+    const home = homeContribution.snapshot.files.find(file => file.path === record.home.path)
+    need(home)
+    const originContribution = contributions.get(record.origin.repoId)
+    const kind = record.family === 'hyperlink' ? 'ordinary-link' : record.family === 'source-declaration' ? 'declared' : undefined
+    const origin = observedCitation(originContribution, record.origin, kind)
+    if (record.family === 'hyperlink') {
+      const resolved = candidates.get(record.origin.repoId).edges.filter(edge => same(edge.sourceRef, origin.provenance))
+      need(record.predicate === 'links-to' && resolved.length === 1 &&
+        same(resolved[0].source, record.subject) && same(resolved[0].target, record.object))
+    }
+    if (record.family === 'source-declaration') need(same(origin.source, record.subject) && origin.predicate === record.predicate &&
+      same(resolveLegacyNodeRef(origin.target, [...contributions.values()]), record.object))
+    const evidence = new Map([...contributions.keys()].map(repoId => [repoId, []]))
+    for (const [index, occurrence] of occurrences.entries()) {
+      const contribution = contributions.get(occurrence.source.repoId)
+      const observed = index === 0 ? origin : observedCitation(contribution, occurrence.source)
+      evidence.get(contribution.repository.repoId).push({ evidenceId: occurrence.id, sourceRef: observed.provenance })
+    }
+    const edge = { edgeId, source: record.subject, target: record.object, predicate: record.predicate, family: record.family,
+      sourceRef: { repoId: record.home.repoId, path: home.path, revision: homeContribution.snapshot.digest, digest: home.rawDigest },
+      supportRefs: occurrences.map(value => value.id) }
+    return immutable([...candidates.values()].sort((a, b) => compare(a.repository.repoId, b.repository.repoId)).map(candidate =>
+      structuredClone({ ...candidate, edges: candidate.repository.repoId === record.home.repoId ? [edge] : [],
+        evidence: evidence.get(candidate.repository.repoId) })))
+  } catch (error) {
+    if (error instanceof TypeError && [invalid, missing, oversized].includes(error.message)) throw error
+    throw new TypeError(invalid)
+  }
+}

package/src/graph-access/multi-record-projection-adapter.mjs

@@ -0,0 +1,74 @@
+// Aggregate supplied policy records after the host selects current recipient scope.
+import { canonicalize } from '../attestation/jcs.mjs'
+import { immutable } from '../edge-policy/contract.mjs'
+import { adaptMultiContributionRecord } from './multi-contribution-record-adapter.mjs'
+import { adaptRepositoryContribution } from './source-adapter.mjs'
+
+const invalid = 'Invalid multi-record projection input'
+const duplicate = 'Duplicate graph edge or evidence identity'
+const oversized = 'Graph projection exceeds graph access bounds'
+const missing = 'Required edge record repository is not selected'
+const need = (value, message = invalid) => { if (!value) throw new TypeError(message) }
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0
+const sourceOnly = value => ({ ...value, edges: [], evidence: [] })
+
+/**
+ * Return complete per-repository candidates for explicitly selected records and
+ * native contributions. The host owns grants, current permitted-record selection,
+ * source verification and policy acceptance; this function creates none of them.
+ * Empty records retain selected source nodes with no governed edges or evidence.
+ * Rebuild all candidates when grants change; never slice an older recipient bundle.
+ * Delegated source validation repeats per record (O(records × selected repos));
+ * input limits are refusal bounds, not a demonstrated large-batch throughput claim.
+ */
+export function adaptMultiRecordProjection(records, selected, options = {}) {
+  try {
+    need(plain(options) && Object.keys(options).every(name => name === 'topology'))
+    need(Array.isArray(records) && Array.isArray(selected))
+    // Refuse oversized work before reading or validating any selected source.
+    need(records.length <= 10000 && selected.length <= 64, oversized)
+    need(records.length === 0 || selected.length > 0, missing)
+    const candidates = new Map(), sourcePins = new Map()
+    for (const entry of selected) {
+      need(plain(entry) && Object.keys(entry).sort().join(',') === 'contribution,ownerRef')
+      const candidate = sourceOnly(adaptRepositoryContribution(entry.contribution, { ownerRef: entry.ownerRef }))
+      const repoId = candidate.repository.repoId
+      need(!candidates.has(repoId))
+      candidates.set(repoId, candidate)
+      sourcePins.set(repoId, canonicalize(candidate))
+    }
+    const edgeIds = new Set(), evidenceIds = new Set()
+    for (const record of records) {
+      const bundle = adaptMultiContributionRecord(record, selected, options)
+      for (const contribution of bundle) {
+        const repoId = contribution.repository.repoId
+        need(sourcePins.get(repoId) === canonicalize(sourceOnly(contribution)))
+        const candidate = candidates.get(repoId)
+        for (const edge of contribution.edges) {
+          need(!edgeIds.has(edge.edgeId), duplicate)
+          edgeIds.add(edge.edgeId)
+          candidate.edges.push(edge)
+        }
+        for (const evidence of contribution.evidence) {
+          need(!evidenceIds.has(evidence.evidenceId), duplicate)
+          evidenceIds.add(evidence.evidenceId)
+          candidate.evidence.push(evidence)
+        }
+        need(candidate.edges.length <= 10000 && candidate.evidence.length <= 10000, oversized)
+      }
+    }
+    const complete = [...candidates.values()].sort((a, b) => compare(a.repository.repoId, b.repository.repoId)).map(candidate => ({
+      ...candidate,
+      edges: candidate.edges.sort((a, b) => compare(a.edgeId, b.edgeId)),
+      evidence: candidate.evidence.sort((a, b) => compare(a.evidenceId, b.evidenceId)),
+    }))
+    for (const candidate of complete) need(candidate.nodes.length <= 10000 && candidate.snapshot.files.length <= 10000 &&
+      Buffer.byteLength(canonicalize(candidate)) <= 8 * 1024 * 1024, oversized)
+    return immutable(structuredClone(complete))
+  } catch (error) {
+    if (error instanceof TypeError && error.message === 'Edge record exceeds graph access bounds') throw new TypeError(oversized)
+    if (error instanceof TypeError && [invalid, duplicate, oversized, missing].includes(error.message)) throw error
+    throw new TypeError(invalid)
+  }
+}

package/src/graph-access/source-adapter.mjs

@@ -0,0 +1,81 @@
+// Pure projection from the source producer; ownership and access remain host-owned.
+import { createHash } from 'node:crypto'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { deepFreeze } from '../composition/wire.mjs'
+import { validateRepositoryContribution } from '../graph/repo-contribution.mjs'
+
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 512 && !/[\u0000-\u001f]/u.test(value)
+const ref = value => plain(value) && Object.keys(value).sort().join(',') === 'localId,repoId' && text(value.repoId) && text(value.localId)
+const key = value => canonicalize([value.repoId, value.localId])
+const equal = (a, b) => canonicalize(a) === canonicalize(b)
+const hash = value => createHash('sha256').update(canonicalize(value)).digest('hex')
+const need = value => { if (!value) throw new TypeError('Invalid graph access source input') }
+// Resolution may change endpoints, never the observed occurrence or its pin.
+const occurrence = link => canonicalize({ ...link, target: null, resolution: 'unresolved' })
+
+function resolvedLinks(contribution, topology) {
+  if (topology === undefined) return contribution.ordinaryLinks
+  need(plain(topology) && Array.isArray(topology.nodes) && Array.isArray(topology.ordinaryLinks))
+  const nodes = new Map()
+  for (const node of topology.nodes) {
+    need(ref(node?.ref) && !nodes.has(key(node.ref)))
+    nodes.set(key(node.ref), node)
+  }
+  for (const node of contribution.nodes) need(equal(nodes.get(key(node.ref)), node))
+  const links = new Map()
+  for (const link of topology.ordinaryLinks) {
+    if (link?.source?.repoId !== contribution.repository.repoId) continue
+    need(plain(link))
+    const id = occurrence(link)
+    need(!links.has(id))
+    need(link.target === null
+      ? link.resolution === 'unresolved'
+      : ref(link.target) && nodes.has(key(link.target)) && link.resolution === (link.target.repoId === link.source.repoId ? 'resolved-local' : 'resolved-cross-repository'))
+    links.set(id, link)
+  }
+  need(links.size === contribution.ordinaryLinks.length)
+  return contribution.ordinaryLinks.map(link => {
+    const resolved = links.get(occurrence(link))
+    need(resolved)
+    return resolved
+  })
+}
+
+/**
+ * Normalize one buildRepositoryContribution result for createGraphAccess.
+ * ownerRef is an explicit trusted-host binding, never derived from source data.
+ * Optional topology comes from the host's explicitly supplied contribution set;
+ * it binds endpoints only and supplies no recipient grant or edge acceptance.
+ * Declared semantic relations stay with their assertion owner and are not
+ * converted into hyperlinks or activated by this navigation-only adapter.
+ * Structural integrity here does not verify raw bytes, ownership or freshness;
+ * the host's verifyContribution and evaluateEdge ports remain required.
+ */
+export function adaptRepositoryContribution(contribution, options = {}) {
+  need(plain(options) && Object.keys(options).every(k => ['ownerRef', 'topology'].includes(k)) && text(options.ownerRef))
+  need(validateRepositoryContribution(contribution).ok)
+  const links = resolvedLinks(contribution, options.topology).filter(link => link.target !== null)
+  const evidence = [], edges = []
+  const seen = new Set()
+  for (const link of links) {
+    const occurrenceDigest = hash({ source: link.source, sourceRef: link.provenance })
+    need(!seen.has(occurrenceDigest)); seen.add(occurrenceDigest)
+    const evidenceId = `ordinary-link-evidence:${occurrenceDigest}`
+    evidence.push({ evidenceId, sourceRef: link.provenance })
+    edges.push({ edgeId: `ordinary-link:${hash({ source: link.source, target: link.target, sourceRef: link.provenance })}`,
+      source: link.source, target: link.target, predicate: 'links_to', family: 'hyperlink',
+      sourceRef: link.provenance, supportRefs: [evidenceId] })
+  }
+  return deepFreeze(structuredClone({
+    repository: { repoId: contribution.repository.repoId, ownerRef: options.ownerRef },
+    snapshot: contribution.snapshot,
+    inputs: contribution.inputs,
+    nodes: contribution.nodes.map(node => ({
+      ref: node.ref, sourceKind: node.kgType, title: node.title, summary: node.summary,
+      classification: node.classification, lifecycle: node.lifecycle, tags: node.tags,
+      sourceRef: node.source, displayEligible: true,
+    })),
+    edges, evidence,
+  }))
+}

package/src/graph-refresh/compare.mjs

@@ -0,0 +1,110 @@
+import { canonicalize } from '../attestation/jcs.mjs'
+
+const order = (left, right) => left < right ? -1 : left > right ? 1 : 0
+const text = value => typeof value === 'string' && value.length > 0
+const fail = () => { throw new TypeError('Snapshot comparison requires matching authorized graph views') }
+const refKey = ref => ref && text(ref.repoId) && text(ref.localId) ? canonicalize([ref.repoId, ref.localId]) : fail()
+const sourceKey = ref => ref && text(ref.repoId) && text(ref.path) ? canonicalize([ref.repoId, ref.path]) : fail()
+
+function index(items, keyOf) {
+  if (!Array.isArray(items)) fail()
+  const records = new Map()
+  for (const item of items) {
+    const key = keyOf(item)
+    if (!text(key) || records.has(key)) fail()
+    records.set(key, item)
+  }
+  return records
+}
+
+function changes(before, after, identity) {
+  const added = [], removed = [], changed = []
+  for (const key of [...new Set([...before.keys(), ...after.keys()])].sort(order)) {
+    if (!before.has(key)) added.push(identity(after.get(key)))
+    else if (!after.has(key)) removed.push(identity(before.get(key)))
+    else if (canonicalize(before.get(key)) !== canonicalize(after.get(key))) changed.push(identity(after.get(key)))
+  }
+  return { added, removed, changed }
+}
+
+function records(view) {
+  if (!view || view.schema !== 'atelier.graph-view@v1' || !text(view.projectionDigest) || !view.accessContext) fail()
+  const nodes = index(view.nodes, node => refKey(node.ref))
+  const edges = index(view.edges, edge => text(edge.edgeId) ? edge.edgeId : fail())
+  const evidence = index(view.evidence, item => text(item.evidenceId) ? item.evidenceId : fail())
+  const questions = index(view.questions, item => text(item.questionId) ? item.questionId : fail())
+  const sources = new Map()
+  function addSource(source) {
+    if (!source) return
+    const key = sourceKey(source)
+    // Keep all exact source pins (including locators), not whichever record
+    // happened to be visited last. One source can support several questions.
+    if (!sources.has(key)) sources.set(key, { repoId: source.repoId, path: source.path, pins: new Set() })
+    sources.get(key).pins.add(canonicalize(source))
+  }
+  for (const item of [...nodes.values(), ...evidence.values()]) addSource(item.sourceRef)
+  for (const repository of view.sourceSnapshot?.repositories ?? []) {
+    for (const file of repository.files ?? []) addSource({ repoId: repository.repoId, path: file.path, revision: repository.digest, digest: file.rawDigest, byteLength: file.byteLength })
+    for (const input of Object.values(repository.inputs ?? {})) addSource(input)
+  }
+  for (const [key, source] of sources) sources.set(key, { ...source, pins: [...source.pins].sort(order) })
+  for (const edge of edges.values()) {
+    if (!nodes.has(refKey(edge.source)) || !nodes.has(refKey(edge.target)) ||
+        !Array.isArray(edge.supportRefs) || edge.supportRefs.some(id => !evidence.has(id))) fail()
+  }
+  for (const question of questions.values()) {
+    if (!Array.isArray(question.nodeRefs) || question.nodeRefs.some(ref => !nodes.has(refKey(ref))) ||
+        !Array.isArray(question.evidenceRefs) || question.evidenceRefs.some(id => !evidence.has(id)) ||
+        (question.contradictingRefs !== undefined && (!Array.isArray(question.contradictingRefs) || question.contradictingRefs.some(id => !evidence.has(id))))) fail()
+  }
+  return { nodes, edges, evidence, questions, sources }
+}
+
+// Derived data only. The trusted caller must revalidate BOTH snapshots before
+// calling. Matching accessContext refuses changed grants/principals/filters;
+// it is a compatibility check, never proof of recipient authorization.
+export function compareGraphSnapshots(before, after) {
+  if (!before?.accessContext || canonicalize(before.accessContext) !== canonicalize(after?.accessContext)) fail()
+  const a = records(before), b = records(after)
+  const nodes = changes(a.nodes, b.nodes, node => node.ref)
+  const edges = changes(a.edges, b.edges, edge => edge.edgeId)
+  const sources = changes(a.sources, b.sources, source => ({ repoId: source.repoId, path: source.path }))
+  const evidenceChanges = changes(a.evidence, b.evidence, item => item.evidenceId)
+  const questionChanges = changes(a.questions, b.questions, item => item.questionId)
+  const affectedNodes = new Set([...nodes.added, ...nodes.removed, ...nodes.changed].map(refKey))
+  const affectedEdges = new Set([...edges.added, ...edges.removed, ...edges.changed])
+  const affectedSources = new Set([...sources.added, ...sources.removed, ...sources.changed].map(sourceKey))
+  const affectedEvidence = new Set([...evidenceChanges.added, ...evidenceChanges.removed, ...evidenceChanges.changed])
+  const affectedQuestions = new Set([...questionChanges.added, ...questionChanges.removed, ...questionChanges.changed])
+  const adjacency = new Map()
+  for (const graph of [a, b]) {
+    for (const node of graph.nodes.values()) if (node.sourceRef && affectedSources.has(sourceKey(node.sourceRef))) affectedNodes.add(refKey(node.ref))
+    for (const item of graph.evidence.values()) if (item.sourceRef && affectedSources.has(sourceKey(item.sourceRef))) affectedEvidence.add(item.evidenceId)
+    for (const edge of graph.edges.values()) {
+      const from = refKey(edge.source), to = refKey(edge.target)
+      if (!adjacency.has(from)) adjacency.set(from, new Set())
+      if (!adjacency.has(to)) adjacency.set(to, new Set())
+      adjacency.get(from).add(to)
+      adjacency.get(to).add(from)
+      if (affectedEdges.has(edge.edgeId) || edge.supportRefs.some(id => affectedEvidence.has(id))) {
+        affectedNodes.add(from); affectedNodes.add(to)
+      }
+    }
+  }
+  // Conservative possible-impact reachability, not a claim that every link is
+  // a semantic dependency. Coverage is limited to the supplied authorized slice.
+  const queue = [...affectedNodes]
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    for (const neighbor of adjacency.get(queue[cursor]) ?? []) if (!affectedNodes.has(neighbor)) {
+      affectedNodes.add(neighbor); queue.push(neighbor)
+    }
+  }
+  for (const graph of [a, b]) for (const question of graph.questions.values()) {
+    if (question.nodeRefs.some(ref => affectedNodes.has(refKey(ref))) || [...question.evidenceRefs, ...(question.contradictingRefs ?? [])].some(id => affectedEvidence.has(id))) affectedQuestions.add(question.questionId)
+  }
+  return {
+    beforeDigest: before.projectionDigest, afterDigest: after.projectionDigest,
+    nodes, edges, sources,
+    possibleImpact: { scope: 'supplied-authorized-slice', questionIds: [...affectedQuestions].sort(order) },
+  }
+}