graphlin 0.1.3 → 0.2.1

package/runtime/architecture/controller.mjs

@@ -0,0 +1,209 @@
+const MAX_PENDING = 10_000;
+const BATCH_SIZE = 6;
+const STATES = new Set(['waiting', 'queued', 'running', 'complete', 'partial', 'unavailable']);
+const version = value => `${value.generation}:${value.hash}:${value.status}`;
+const metadata = value => ({
+  artifactId: value.id, generation: value.generation, hash: value.hash, status: value.status,
+});
+
+/** Coalesces observations. Captured source lives only for the active analysis job. */
+export function createArchitectureController({
+  snapshot, capture, commit, analyze, available = () => null, ready = () => true,
+  onChange = () => {}, onDiagnostic = () => {}, now = Date.now, settleMs = 300,
+}) {
+  const known = new Map(), pending = new Map(), completed = new Map();
+  const retries = new Map();
+  let state = 'waiting', reason = 'no_source', timer, active, abort, activeVersions;
+  let closed = false, epoch = 0, manual = false, omitted = 0, failures = 0, lastRunAt = null;
+
+  function status() {
+    const model = snapshot();
+    const supported = (model.interpretations ?? []).filter(value =>
+      value.namespace === 'graphlin.architecture' && value.validity === 'current' &&
+      value.support === 'supported' && value.classification === 'accepted');
+    const blocked = available();
+    return {
+      status: blocked ? 'unavailable' : state,
+      ...(blocked || reason ? { reason: blocked || reason } : {}),
+      applications: supported.filter(value => value.kind === 'application').length,
+      components: supported.filter(value => value.kind === 'component').length,
+      pending: pending.size, inspected: completed.size, total: known.size,
+      omitted, failures, ...(lastRunAt === null ? {} : { lastRunAt }),
+    };
+  }
+  function publish(next, why = null) {
+    state = STATES.has(next) ? next : 'unavailable';
+    reason = why;
+    try { onChange(); } catch { /* Observation must remain fail-open. */ }
+  }
+  function diagnostic(result) {
+    try {
+      onDiagnostic({
+        status: result.status, code: result.diagnostics?.code ?? 'architecture_unavailable',
+        analyzed: result.coverage?.analyzedArtifactIds?.length ?? 0,
+        deferred: result.coverage?.deferredArtifactIds?.length ?? 0,
+        providerRequests: result.diagnostics?.providerRequests ?? 0,
+      });
+    } catch { /* Diagnostics cannot prevent admission or shutdown. */ }
+  }
+  function enqueue(id, { force = false } = {}) {
+    const item = known.get(id);
+    if (!item || (!force && completed.get(id) === version(item))) return;
+    if (!pending.has(id) && pending.size >= MAX_PENDING) { omitted++; return; }
+    pending.set(id, item);
+  }
+  function wake() {
+    if (closed) return;
+    const blocked = available();
+    if (blocked) {
+      clearTimeout(timer); timer = null;
+      abort?.abort();
+      return;
+    }
+    if (active || timer || (!pending.size && !manual)) return;
+    timer = setTimeout(() => {
+      timer = null;
+      if (!ready()) { wake(); return; }
+      void run();
+    }, settleMs);
+    timer.unref?.();
+  }
+  function observe(artifacts) {
+    if (closed) return;
+    for (const artifact of artifacts) {
+      const item = metadata(artifact), old = known.get(artifact.id);
+      if (old && version(old) === version(item)) continue;
+      if (!old && known.size >= MAX_PENDING) { omitted++; continue; }
+      known.set(artifact.id, item);
+      completed.delete(artifact.id);
+      retries.delete(artifact.id);
+      enqueue(artifact.id);
+      if (activeVersions?.has(artifact.id) && activeVersions.get(artifact.id) !== version(item)) abort?.abort();
+    }
+    if (!active && pending.size) { state = 'queued'; reason = null; }
+    wake();
+  }
+  async function run() {
+    if (active || closed || available()) return active;
+    clearTimeout(timer); timer = null;
+    if (manual) {
+      retries.clear();
+      completed.clear();
+      omitted = 0;
+      for (const id of known.keys()) enqueue(id, { force: true });
+      manual = false;
+    }
+    if (!pending.size) { publish('waiting', 'no_source'); return; }
+    const ids = [...pending.keys()].slice(0, BATCH_SIZE), generation = epoch;
+    abort = new AbortController();
+    const signal = abort.signal;
+    publish('running');
+    active = (async () => {
+      const artifacts = await capture(ids);
+      if (closed || signal.aborted || generation !== epoch) return;
+      const captured = new Map(artifacts.map(value => [value.id, metadata(value)]));
+      activeVersions = new Map(ids.flatMap(id => known.has(id)
+        ? [[id, version(captured.get(id) ?? known.get(id))]] : []));
+      // Parsing can settle after a newer capture was observed. Never mark that
+      // newer version inspected using an older capture.
+      if (ids.some(id => activeVersions.get(id) !== version(known.get(id) ?? {}))) return;
+      const result = await analyze({ model: snapshot(), artifacts, affectedArtifactIds: ids, signal });
+      if (closed || signal.aborted || generation !== epoch) return;
+      diagnostic(result);
+      const applied = result.affectedEntityIds?.length || result.coverage?.missingArtifactIds?.length
+        ? await commit(result, { artifacts: artifacts.map(metadata), signal, epoch: generation })
+        : true;
+      if (closed || signal.aborted || generation !== epoch) return;
+      if (!applied || applied.accepted === false) {
+        // A source race may be retried, but a persistently rejected admission
+        // must not become an endless background classification loop.
+        for (const id of ids) {
+          if (activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+          const count = (retries.get(id) ?? 0) + 1;
+          retries.set(id, count);
+          if (count >= 2) { pending.delete(id); completed.set(id, activeVersions.get(id)); failures++; }
+        }
+        publish(pending.size ? 'queued' : 'partial', 'source_changed');
+        return;
+      }
+      if (Number.isSafeInteger(applied.omitted) && applied.omitted > 0) omitted += applied.omitted;
+      const deferred = new Set(result.coverage?.deferredArtifactIds ?? []);
+      const progressed = ids.some(id => !deferred.has(id));
+      for (const id of ids) {
+        if (activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+        pending.delete(id);
+        // Move budget-deferred captures to the back, so the next batch can
+        // spend its source budget on them. Stop if a whole batch made no
+        // progress (for example, no capture is available).
+        if (deferred.has(id) && progressed) continue;
+        completed.set(id, activeVersions.get(id));
+        if (deferred.has(id)) failures++;
+      }
+      for (const id of deferred) enqueue(id);
+      for (const id of result.coverage?.deferredMembershipArtifactIds ?? []) {
+        const count = retries.get(id) ?? 0;
+        if (count < 2) { retries.set(id, count + 1); enqueue(id, { force: true }); }
+        else if (count === 2) { retries.set(id, 3); omitted++; }
+      }
+      lastRunAt = now();
+      if (result.status === 'unavailable') { failures++; publish('unavailable', 'analysis_failed'); }
+      else if (result.status === 'partial' || omitted) publish('partial', 'partial_coverage');
+      else {
+        const totals = status();
+        publish('complete', totals.applications + totals.components ? null : 'none_supported');
+      }
+    })().catch(() => {
+      if (!closed && !signal.aborted) {
+        failures++;
+        for (const id of ids) {
+          if (activeVersions && activeVersions.get(id) !== version(known.get(id) ?? {})) continue;
+          pending.delete(id);
+          if (known.has(id)) completed.set(id, version(known.get(id)));
+        }
+        publish('unavailable', 'analysis_failed');
+      }
+    }).finally(() => {
+      active = null; abort = null; activeVersions = null;
+      if (!closed) {
+        if (pending.size || manual) { state = 'queued'; wake(); }
+        else if (state === 'running') publish(available() ? 'unavailable' : 'partial', available() || 'source_changed');
+      }
+    });
+    return active;
+  }
+  function request() {
+    if (!closed) {
+      manual = true;
+      publish('queued', available());
+      wake();
+    }
+    return status();
+  }
+  function invalidate() {
+    epoch++;
+    abort?.abort();
+    completed.clear();
+    retries.clear();
+    for (const id of known.keys()) enqueue(id, { force: true });
+    wake();
+  }
+  return {
+    observe, wake, request, status, invalidate,
+    async whenIdle() {
+      clearTimeout(timer); timer = null;
+      while (!closed && !available() && (active || pending.size || manual)) {
+        if (!ready()) break;
+        await (active ?? run());
+      }
+      clearTimeout(timer); timer = null;
+    },
+    async close() {
+      closed = true;
+      clearTimeout(timer); timer = null;
+      abort?.abort();
+      pending.clear();
+      await active;
+      known.clear(); completed.clear(); retries.clear();
+    },
+  };
+}

package/runtime/architecture/evidence.mjs

@@ -0,0 +1,108 @@
+import { isDeepStrictEqual } from 'node:util';
+import { LIMITS, hash, isHash, isId, integer, opaque } from '../core/common.mjs';
+import { createPolicy, metadataEvent, safeLabel, safeText } from '../core/privacy.mjs';
+import { buildCandidates } from '../core/candidates.mjs';
+import { id, references, relativePath } from '../model/records.mjs';
+import { ARCHITECTURE_NAMESPACE } from './profile.mjs';
+
+export const ARCHITECTURE_LIMITS = Object.freeze({
+  artifacts: 6, candidatesPerArtifact: 8, membershipChecks: 6,
+  sourceRefs: 16, guardRefs: 128, sourceBytes: 512 * 1024,
+});
+export const requireValue = value => { if (!value) throw new Error('architecture_input_invalid'); };
+export const lineageOf = model => model.coverage?.lineage?.id ?? model.projectId;
+export const recordId = (projectId, ...parts) => opaque('architecture', projectId, ...parts);
+
+export function indexModel(model, policy) {
+  requireValue(model?.schemaVersion === 2 && id(model.projectId) && integer(model.revision)
+    && !model.replay && model.checkpointId === undefined && id(lineageOf(model))
+    && Array.isArray(model.entities) && model.entities.length <= 20_000
+    && Array.isArray(model.relations) && model.relations.length <= 40_000
+    && Array.isArray(model.interpretations) && model.interpretations.length <= 512
+    && Array.isArray(model.coverage?.artifacts) && model.coverage.artifacts.length <= 10_000);
+  const entities = new Map(), artifacts = new Map(), byArtifact = new Map();
+  for (const artifact of model.coverage.artifacts) {
+    requireValue(id(artifact?.id) && !artifacts.has(artifact.id));
+    artifacts.set(artifact.id, artifact);
+  }
+  function currentRefs(value, max = ARCHITECTURE_LIMITS.sourceRefs) {
+    const refs = references(value, max);
+    if (!refs?.length || !isDeepStrictEqual(refs, value)) return null;
+    return refs.every(ref => {
+      const artifact = artifacts.get(ref.artifactId);
+      return ref.sourceClass !== 'public_intent' && artifact?.status === 'present'
+        && artifact.fresh === true && artifact.hash === ref.hash && artifact.generation === ref.generation
+        && relativePath(artifact.relativePath, policy);
+    }) ? refs : null;
+  }
+  for (const entity of model.entities) {
+    requireValue(id(entity?.id) && !entities.has(entity.id));
+    entities.set(entity.id, entity);
+    if (!byArtifact.has(entity.artifactId)) byArtifact.set(entity.artifactId, []);
+    if (entity.basis === 'parsed' && entity.validity === 'current' && entity.classification === 'accepted'
+      && safeLabel(entity.label) && currentRefs(entity.sourceRefs)) byArtifact.get(entity.artifactId).push(entity);
+  }
+  const relations = model.relations.filter(value => value?.validity === 'current'
+    && value.basis === 'parsed' && entities.has(value.source) && entities.has(value.target)
+    && ['contains', 'imports', 'calls', 'depends_on'].includes(value.kind) && currentRefs(value.sourceRefs));
+  return { entities, artifacts, byArtifact, relations, currentRefs };
+}
+
+export function moduleForArtifact(index, artifactId) {
+  const modules = (index.byArtifact.get(artifactId) ?? []).filter(entity => ['module', 'file'].includes(entity.kind));
+  return modules.length === 1 ? modules[0] : null;
+}
+
+export function requestedArtifacts(model, index, captures, affectedArtifactIds) {
+  const supplied = captures.map(value => value?.id);
+  requireValue(supplied.every(isId) && new Set(supplied).size === supplied.length);
+  if (affectedArtifactIds === undefined) return supplied;
+  requireValue(Array.isArray(affectedArtifactIds) && affectedArtifactIds.length <= 128
+    && affectedArtifactIds.every(isId) && new Set(affectedArtifactIds).size === affectedArtifactIds.length);
+  const seeds = new Set(affectedArtifactIds), requested = new Set(seeds);
+  // One-hop dependencies nominate source for reconsideration, never membership.
+  for (const relation of index.relations) {
+    const source = index.entities.get(relation.source).artifactId;
+    const target = index.entities.get(relation.target).artifactId;
+    if (seeds.has(source) && isId(target)) requested.add(target);
+    if (seeds.has(target) && isId(source)) requested.add(source);
+  }
+  // Existing groups can depend on a changed file even if an import disappeared.
+  for (const value of model.interpretations) {
+    if (value.namespace !== ARCHITECTURE_NAMESPACE || !Array.isArray(value.sourceRefs)
+      || value.sourceRefs.length > ARCHITECTURE_LIMITS.sourceRefs
+      || !value.sourceRefs.some(ref => seeds.has(ref.artifactId))) continue;
+    for (const ref of value.sourceRefs) if (isId(ref.artifactId)) requested.add(ref.artifactId);
+  }
+  return [...seeds, ...[...requested].filter(value => !seeds.has(value)).sort()];
+}
+
+export function candidatesForCapture(capture, index, event, policy) {
+  const current = index.artifacts.get(capture.id);
+  const anchor = moduleForArtifact(index, capture.id);
+  if (!anchor || !current || current.status !== 'present' || current.fresh !== true
+    || capture.status !== 'present' || capture.exists !== true || capture.complete !== true
+    || !isHash(capture.hash) || !integer(capture.generation, 1)
+    || current.hash !== capture.hash || current.generation !== capture.generation
+    || !relativePath(capture.relativePath, policy) || current.relativePath !== capture.relativePath
+    || typeof capture.text !== 'string' || Buffer.byteLength(capture.text) > LIMITS.fileBytes
+    || !safeText(capture.text, LIMITS.fileBytes) || hash(capture.text) !== capture.hash) return null;
+  const candidates = buildCandidates({ event, artifacts: [capture], policy });
+  return { anchor, candidates: candidates.slice(0, ARCHITECTURE_LIMITS.candidatesPerArtifact),
+    omitted: Math.max(0, candidates.length - ARCHITECTURE_LIMITS.candidatesPerArtifact),
+    sourceRef: { artifactId: capture.id, hash: capture.hash, generation: capture.generation } };
+}
+export function unionRefs(...groups) {
+  const refs = new Map(groups.flat().map(ref => [JSON.stringify(ref), structuredClone(ref)]));
+  return refs.size <= ARCHITECTURE_LIMITS.guardRefs ? [...refs.values()] : null;
+}
+export function analysisEvent(model) {
+  return metadataEvent({
+    projectId: model.projectId, id: opaque('event', ARCHITECTURE_NAMESPACE, model.projectId, model.revision, lineageOf(model)),
+    kind: 'artifact.changed', toolCategory: 'read', outcome: 'observed', incomplete: false,
+  });
+}
+export function unchanged(model, basis, policy, signal) {
+  return !signal?.aborted && model.revision === basis.revision && model.projectId === basis.projectId
+    && lineageOf(model) === basis.lineageId && createPolicy(policy).version === basis.policyVersion;
+}

package/runtime/architecture/profile.mjs

@@ -0,0 +1,56 @@
+import { freeze } from '../core/common.mjs';
+
+export const ARCHITECTURE_NAMESPACE = 'graphlin.architecture';
+export const ARCHITECTURE_VERSION = 'source-boundaries-v4';
+export const ROLE_PROFILE_ID = 'graphlin.architecture.roles';
+export const MEMBERSHIP_PROFILE_ID = 'graphlin.architecture.membership';
+
+const boolean = (question, focus, yes, no) => ({
+  type: 'boolean', instructions: { question, focus },
+  criteria: { true: yes, false: no }, requiredMetrics: ['probability'],
+});
+const rules = 'Use only visible source. Names, directories, documentation, imports alone, and co-occurrence '
+  + 'do not establish an architectural boundary. An application has visible executable bootstrap or '
+  + 'composition of a user-facing program, server or worker. A component has a coherent responsibility '
+  + 'and an implemented interface; an incidental helper, constant, type or external dependency is not '
+  + 'automatically a component. Classify what this code implements when invoked, never claim it ran.';
+
+/** Register this source profile with the existing decision service; it cannot bypass A. */
+export const ARCHITECTURE_PROFILES = freeze([
+  {
+    id: ROLE_PROFILE_ID, version: ARCHITECTURE_VERSION, scope: 'bundle',
+    questions: {
+      kind: {
+        type: 'choice', requiredMetrics: ['probabilities', 'confidence'],
+        instructions: {
+          question: 'What does this source file locally implement in `evidence`?', focus: rules,
+        },
+        criteria: {
+          application: 'Visible executable bootstrap or composition that starts an application, server or worker when invoked.',
+          component: 'A cohesive implemented API with visible operation bodies, beyond an incidental helper.',
+          unknown: 'Only imports, declarations, stubs, constants or incidental helpers; no such local responsibility is established.',
+        },
+      },
+      supported: boolean(
+        'Does `evidence` directly show implemented behavior for this source file?',
+        'Judge implementation presence, independently of the architectural role. Actual startup statements or '
+          + 'operation bodies show implementation. Imports, signatures, empty bodies, placeholder throws, comments '
+          + 'and a name alone do not. External callers, deployment manifests, imported collaborator internals '
+          + 'and runtime execution are not prerequisites for recognizing visible local implementation.',
+        'Executable statements directly implement startup or operations in this file.',
+        'Only imports, declarations, scalar constants, empty bodies or placeholders are visible.',
+      ),
+      missing_context: boolean(
+        'Is a local statement or definition absent from `evidence` that prevents identifying what this file implements?',
+        'This is only about classifying the visible file as application, component or unknown. '
+          + 'Missing context requires an omitted/truncated body or unresolved local operation that prevents that decision. '
+          + 'A visible server construction and listen call suffice for application startup. Visible class or function '
+          + 'operation bodies can establish a component. Standard library internals, implementation of imported collaborators, '
+          + 'upstream callers, deployment configuration and runtime execution are not required to identify the file’s own role. '
+          + 'A fully visible constant or helper can conclusively be unknown without missing context.',
+        'A necessary local body or statement is absent, so the file’s implemented responsibility cannot be identified.',
+        'Visible code suffices to support or reject an application/component role for this file.',
+      ),
+    },
+  },
+]);

package/runtime/core/evidence.mjs

@@ -9,13 +9,16 @@ const fingerprint = stat => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.c
 
 export class EvidenceStore {
   #root; #inputRoot; #policy; #records = new Map(); #byId = new Map();
-  constructor({ projectRoot, policy } = {}) {
+  #maxTrackedPaths; #reconcileCursor = 0; #lineage = null; #generationFloor;
+  constructor({ projectRoot, policy, maxTrackedPaths = LIMITS.trackedPaths, generationFloor = 0 } = {}) {
     try {
       this.#inputRoot = path.resolve(projectRoot);
       this.#root = realpathSync(projectRoot);
       if (!statSync(this.#root).isDirectory()) fail();
     } catch { fail('INVALID_PROJECT_ROOT'); }
     this.#policy = createPolicy(policy);
+    this.#maxTrackedPaths = integer(maxTrackedPaths, 1, 20000) ? maxTrackedPaths : LIMITS.trackedPaths;
+    this.#generationFloor = integer(generationFloor, 0, Number.MAX_SAFE_INTEGER - 1) ? generationFloor : 0;
   }
 
   #locator(input) {
@@ -43,17 +46,26 @@ export class EvidenceStore {
     }
     const parts = locator.relative.split('/');
     let current = this.#root;
+    let finalStat;
     try {
       if (await realpath(this.#root) !== this.#root) return this.#unavailable('root_changed');
       for (const part of parts) {
         current = path.join(current, part);
         const stat = await lstat(current, { bigint: true });
         if (stat.isSymbolicLink()) return this.#unavailable(`symlink:${fingerprint(stat)}`);
+        finalStat = stat;
       }
     } catch (error) {
       return absent(error) ? { status: 'missing', exists: false, complete: true, hash: null, text: null, stamp: 'missing' }
         : this.#unavailable('unreadable');
     }
+    // Metadata consent permits names/stat observations, never content reads or
+    // hashes. A local-source grant is distinct from permission to transmit it.
+    if (!this.#policy.readSource) {
+      if (!finalStat?.isFile()) return this.#unavailable('not_file');
+      return { status: 'present', exists: true, complete: true,
+        hash: null, text: null, stamp: fingerprint(finalStat) };
+    }
     let handle;
     try {
       // NOFOLLOW closes the final-component race. Revalidate the complete path
@@ -83,7 +95,7 @@ export class EvidenceStore {
       if (text.includes('\0')) return { status: 'partial', exists: true, complete: false, hash: hash(bytes), text: null, stamp };
       return {
         status: 'present', exists: true, complete: true, hash: hash(bytes),
-        text: this.#policy.transmitSource && !privateText(text) ? text : null, stamp,
+        text: !privateText(text) ? text : null, stamp,
       };
     } catch {
       // A disappearing/racing file during open/read is uncertainty. A subsequent
@@ -106,9 +118,9 @@ export class EvidenceStore {
   async #captureOne(locator) {
     const observed = await this.#inspect(locator);
     const previous = this.#records.get(locator.relative);
-    const version = hash([observed.status, observed.hash, observed.stamp]);
+    const version = hash([this.#lineage, observed.status, observed.hash, observed.stamp]);
     const id = opaque('artifact', this.#root, locator.relative);
-    const generation = previous ? previous.generation + (previous.version !== version ? 1 : 0) : 1;
+    const generation = previous ? previous.generation + (previous.version !== version ? 1 : 0) : this.#generationFloor + 1;
     const artifact = {
       id, path: locator.absolute, relativePath: locator.relative,
       hash: observed.hash, generation, exists: observed.exists, status: observed.status,
@@ -116,7 +128,7 @@ export class EvidenceStore {
     };
     // Registry retains no source bytes; returned captures are immutable private
     // snapshots. All path/cache cardinalities are bounded.
-    const record = { ...locator, id, generation, hash: observed.hash, status: observed.status, version };
+    const record = { ...locator, id, generation, hash: observed.hash, status: observed.status, version, lineage: this.#lineage };
     this.#records.set(locator.relative, record);
     this.#byId.set(id, record);
     return freeze(artifact);
@@ -129,14 +141,35 @@ export class EvidenceStore {
       const locator = this.#locator(input);
       if (!locator || seen.has(locator.relative)) continue;
       seen.add(locator.relative);
-      if (!this.#records.has(locator.relative) && this.#records.size >= LIMITS.trackedPaths) continue;
+      if (!this.#records.has(locator.relative) && this.#records.size >= this.#maxTrackedPaths) continue;
       results.push(await this.#captureOne(locator));
     }
     return results;
   }
-  async reconcile() {
+  setLineage(id) {
+    if (typeof id !== 'string' || !/^[a-f0-9]{64}$/.test(id)) fail('INVALID_LINEAGE');
+    if (id === this.#lineage) return [];
+    this.#lineage = id;
+    // A checkout change invalidates in-flight references immediately. The next
+    // real capture advances each generation, even if its bytes are identical.
+    return [...this.#records.values()].map(record => ({
+      id: record.id, path: record.absolute, relativePath: record.relative,
+      generation: record.generation, hash: record.hash, status: 'unavailable',
+      complete: false, exists: null, text: null,
+    }));
+  }
+  async reconcile({ refs, limit } = {}) {
     const results = [];
-    for (const record of this.#records.values()) results.push(await this.#captureOne(record));
+    let records;
+    if (Array.isArray(refs)) {
+      records = [...new Set(refs.slice(0, LIMITS.trackedPaths).map(ref => this.#byId.get(ref.artifactId)).filter(Boolean))];
+    } else if (integer(limit, 1, this.#maxTrackedPaths)) {
+      const all = [...this.#records.values()];
+      const count = Math.min(limit, all.length);
+      records = Array.from({ length: count }, (_, index) => all[(this.#reconcileCursor + index) % all.length]);
+      this.#reconcileCursor = all.length ? (this.#reconcileCursor + count) % all.length : 0;
+    } else records = [...this.#records.values()];
+    for (const record of records) results.push(await this.#captureOne(record));
     return results;
   }
   isCurrent(refs) {
@@ -144,7 +177,8 @@ export class EvidenceStore {
     return refs.every(ref => {
       if (!plain(ref) || !isHash(ref.hash) || !integer(ref.generation, 1)) return false;
       const current = this.#byId.get(ref.artifactId);
-      return current?.status === 'present' && current.hash === ref.hash && current.generation === ref.generation;
+      return current?.status === 'present' && current.lineage === this.#lineage &&
+        current.hash === ref.hash && current.generation === ref.generation;
     });
   }
 }

package/runtime/core/graph.mjs

@@ -31,7 +31,8 @@ function validReference(ref) {
   if (!exactKeys(ref, REF, ['excerpt', 'sourceRef']) || !isId(ref.artifactId) || !isHash(ref.hash) ||
       !integer(ref.generation, 1) || !isId(ref.eventId) || !integer(ref.startLine, 1, 10000000) ||
       !integer(ref.endLine, ref.startLine, 10000000) || ref.endLine - ref.startLine >= LIMITS.snippetLines ||
-      !['source', 'public_intent'].includes(ref.sourceClass) || ref.basis !== 'jev_interpretation' ||
+      !['source', 'public_intent'].includes(ref.sourceClass) ||
+      !['jev_interpretation', 'decision_interpretation'].includes(ref.basis) ||
       (Object.hasOwn(ref, 'excerpt') && !safeText(ref.excerpt, LIMITS.excerptChars))) return false;
   if (ref.sourceClass === 'public_intent' && !ref.sourceRef) return false;
   if (ref.sourceRef) {
@@ -131,11 +132,11 @@ function makePatch(graph, operations, causedBy = []) {
     baseRevision: graph.revision, revision: graph.revision + 1, causedBy, operations,
   });
 }
-function sourceReference(candidate, event, policy) {
+function sourceReference(candidate, event, policy, basis = 'jev_interpretation') {
   const ref = {
     artifactId: candidate.artifactId, hash: candidate.hash, generation: candidate.generation, eventId: event.id,
     startLine: candidate.startLine, endLine: candidate.endLine, sourceClass: candidate.sourceClass,
-    basis: 'jev_interpretation', sourceRef: clone(candidate.sourceRef),
+    basis, sourceRef: clone(candidate.sourceRef),
   };
   if (policy.displayEvidence || policy.persistEvidence) {
     const excerpt = candidate.text.slice(0, LIMITS.excerptChars);
@@ -251,6 +252,10 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
       new Set(decision.edges.map(e => e?.proposalId)).size !== decision.edges.length) return audit.reject(decision, 'duplicate_judgments');
   if (!decision.nodes.every(n => validNodeJudgment(n, candidates)) ||
       !decision.edges.every(e => validEdgeJudgment(e, bundle, candidates))) return audit.reject(decision, 'invalid_judgments');
+  // The service supplies validated provider provenance. Older manual decisions
+  // omit it and keep the legacy basis; answers/candidates cannot select a basis.
+  const providerId = decision.provider?.id;
+  const basis = providerId && providerId !== 'jev' ? 'decision_interpretation' : 'jev_interpretation';
   const existingNodes = new Map(graph.nodes.map(n => [n.id, n]));
   const existingEdges = new Map(graph.edges.map(e => [e.id, e]));
   const admitted = new Map(), operations = [];
@@ -278,7 +283,7 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
     const classification = judgment.classification === 'accepted' && candidate.complete && !event.incomplete &&
       judgment.supportProbability >= 0.85 && judgment.roleProbability >= 0.8 && judgment.roleConfidence >= 0.6 ? 'accepted' : 'tentative';
     const index = projected.nodes.length;
-    const refs = mergeReferences(old?.sourceRefs ?? [], [sourceReference(candidate, event, policy)]);
+    const refs = mergeReferences(old?.sourceRefs ?? [], [sourceReference(candidate, event, policy, basis)]);
     const node = {
       id, label: candidate.label, kind: judgment.role, shape: ROLE_SHAPES[judgment.role],
       x: old?.x ?? 80 + (index % 6) * 220, y: old?.y ?? 80 + Math.floor(index / 6) * 140,
@@ -301,10 +306,10 @@ function compileAuditedDecision(graph, { event, decision, policy }, audit) {
       (ref.generation > c.generation || (old.validity !== 'current' && ref.generation === c.generation))))) {
       report('skipped', 'stale_generation'); continue;
     }
-    const refs = mergeReferences([], evidence.map(c => sourceReference(c, event, policy)));
+    const refs = mergeReferences([], evidence.map(c => sourceReference(c, event, policy, basis)));
     // Every relation retains all dependencies; never silently drop evidence
     // when the reference budget is exceeded.
-    if (refs.length !== new Set(evidence.map(c => refKey(sourceReference(c, event, policy)))).size) {
+    if (refs.length !== new Set(evidence.map(c => refKey(sourceReference(c, event, policy, basis)))).size) {
       report('skipped', 'reference_limit'); continue;
     }
     const classification = judgment.classification === 'accepted' && source.classification === 'accepted' &&

package/runtime/core/privacy.mjs

@@ -19,6 +19,7 @@ export function createPolicy(options = {}) {
       .filter(p => !DEFAULT_EXCLUDES.includes(p)).slice(0, 64) : []
   )])].sort();
   const fields = {
+    readSource: options.readSource === true || options.transmitSource === true,
     transmitSource: options.transmitSource === true,
     displayEvidence: options.displayEvidence !== false,
     persistEvidence: options.persistEvidence === true,

package/runtime/daemon/auth.mjs

@@ -10,12 +10,16 @@ export function createAuth({ origin, instanceId, now = Date.now }) {
     for (const [key, expires] of map) if (expires <= now()) map.delete(key);
     while (map.size >= 16) map.delete(map.keys().next().value);
   }
+  function validTransport(req) {
+    const hosts = req.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'host');
+    return hosts.length === 1 && req.headers.host === new URL(origin).host &&
+      ['127.0.0.1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress);
+  }
   return {
     cookieName,
+    validTransport,
     validRequest(req, { mutation = false } = {}) {
-      const hosts = req.rawHeaders.filter((value, index) => index % 2 === 0 && value.toLowerCase() === 'host');
-      if (hosts.length !== 1 || req.headers.host !== new URL(origin).host) return false;
-      if (!['127.0.0.1', '::ffff:127.0.0.1'].includes(req.socket.remoteAddress)) return false;
+      if (!validTransport(req)) return false;
       if (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(req.headers['sec-fetch-site'])) return false;
       if (mutation) return req.headers.origin === origin;
       return req.headers.origin === undefined || req.headers.origin === origin;

package/runtime/daemon/diagnostics.mjs

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { CATEGORIES, KINDS, ROLES, RELATIONS, isId, opaque, plain } from '../core/common.mjs';
 import { createPolicy, excluded, privateText, safeLabel } from '../core/privacy.mjs';
-import { ACTIVITIES } from '../jev/questions.mjs';
+import { ACTIVITIES } from '../decisions/questions.mjs';
 import { runtimeError, uid } from './paths.mjs';
 
 export const DIAGNOSTIC_LIMITS = Object.freeze({