graphlin 0.1.0

package/runtime/core/candidates.mjs

@@ -0,0 +1,300 @@
+import {
+  GENERIC_LABELS, LIMITS, RELATIONS, clone, equal, exactKeys, freeze, hash, integer, isHash, isId, opaque, plain, probability,
+} from './common.mjs';
+import { createPolicy, excluded, safeLabel, safeText } from './privacy.mjs';
+import { lexicalHints } from './lexical.mjs';
+
+const FIELDS = ['id', 'artifactId', 'hash', 'generation', 'label', 'text', 'startLine', 'endLine',
+  'sourceClass', 'complete', 'entityKey', 'labelOrigin', 'sourceRef', 'digest'];
+const approvedBundles = new WeakSet();
+
+export function validSourceRef(ref) {
+  if (ref?.type === 'artifact') return exactKeys(ref, ['type', 'artifactId', 'hash', 'generation']) &&
+    isId(ref.artifactId) && isHash(ref.hash) && integer(ref.generation, 1);
+  return ref?.type === 'message' && exactKeys(ref, ['type', 'messageId', 'hash', 'contentVersion']) &&
+    isId(ref.messageId) && isHash(ref.hash) && integer(ref.contentVersion, 1);
+}
+
+function digestFields(candidate) {
+  // Explicit field order makes digests independent of JSON object key order.
+  return {
+    artifactId: candidate.artifactId, hash: candidate.hash, generation: candidate.generation,
+    label: candidate.label, text: candidate.text, startLine: candidate.startLine, endLine: candidate.endLine,
+    sourceClass: candidate.sourceClass, complete: candidate.complete, entityKey: candidate.entityKey,
+    labelOrigin: candidate.labelOrigin, sourceRef: candidate.sourceRef,
+  };
+}
+const candidateDigest = (candidate, policy) => hash([policy.version, digestFields(candidate)]);
+
+export function validCandidate(candidate, policy) {
+  if (!policy.transmitSource || !exactKeys(candidate, FIELDS) || !isId(candidate.id) ||
+      !isId(candidate.artifactId) || !isId(candidate.entityKey) || !isHash(candidate.hash) ||
+      !isHash(candidate.digest) || !integer(candidate.generation, 1) ||
+      !integer(candidate.startLine, 1, 10000000) || !integer(candidate.endLine, candidate.startLine, 10000000) ||
+      candidate.endLine - candidate.startLine >= LIMITS.snippetLines ||
+      !safeLabel(candidate.label) || !safeText(candidate.text) || typeof candidate.complete !== 'boolean' ||
+      !validSourceRef(candidate.sourceRef)) return false;
+  const ref = candidate.sourceRef;
+  if (candidate.hash !== ref.hash || candidate.generation !== (ref.generation ?? ref.contentVersion) ||
+      candidate.artifactId !== (ref.artifactId ?? ref.messageId) ||
+      candidate.sourceClass !== (ref.type === 'artifact' ? 'source' : 'public_intent')) return false;
+  const lines = candidate.text.split('\n');
+  if (lines.length !== candidate.endLine - candidate.startLine + 1) return false;
+  const origin = candidate.labelOrigin;
+  if (origin?.type === 'span') {
+    if (!exactKeys(origin, ['type', 'startLine', 'endLine', 'startColumn', 'endColumn']) ||
+        !integer(origin.startLine, candidate.startLine, candidate.endLine) || origin.endLine !== origin.startLine ||
+        !integer(origin.startColumn, 1, LIMITS.snippetChars) ||
+        !integer(origin.endColumn, origin.startColumn, LIMITS.snippetChars + 1) ||
+        lines[origin.startLine - candidate.startLine]?.slice(origin.startColumn - 1, origin.endColumn - 1) !== candidate.label) return false;
+  } else if (!exactKeys(origin, ['type', 'label']) || origin.type !== 'generic' ||
+      origin.label !== candidate.label || !GENERIC_LABELS.includes(candidate.label)) return false;
+  return candidate.digest === candidateDigest(candidate, policy) && candidate.id === opaque('candidate', candidate.digest);
+}
+
+function snippets(text, coverage) {
+  const lines = text.split('\n'), result = [];
+  let current = [], startLine = 1, chars = 0, offset = 0, startOffset = 0;
+  function emit() {
+    if (current.length && current.some(line => line.trim())) result.push({ text: current.join('\n'), startLine, endLine: startLine + current.length - 1, offset: startOffset });
+    current = []; chars = 0;
+  }
+  let i = 0;
+  for (; i < lines.length && result.length < LIMITS.candidates; i++) {
+    const line = lines[i];
+    if (line.length > LIMITS.snippetChars) {
+      coverage.truncated = true;
+      emit(); startLine = i + 2; offset += line.length + 1; continue;
+    }
+    if (current.length >= LIMITS.snippetLines || chars + line.length + (current.length ? 1 : 0) > LIMITS.snippetChars) {
+      emit(); startLine = i + 1;
+    }
+    if (!current.length) { startLine = i + 1; startOffset = offset; }
+    chars += line.length + (current.length ? 1 : 0);
+    current.push(line);
+    offset += line.length + 1;
+  }
+  if (result.length < LIMITS.candidates) emit();
+  else if (current.length || i < lines.length) coverage.truncated = true;
+  return result;
+}
+
+function entities(snippet, hints, available) {
+  const found = [];
+  for (const hint of hints.entities) {
+    const { label } = hint, offset = hint.start - snippet.offset;
+    if (offset < 0 || hint.end > snippet.offset + snippet.text.length || !safeLabel(label)) continue;
+    available.add(`span:${label}`);
+    if (found.length >= LIMITS.candidates) continue;
+    const before = snippet.text.slice(0, offset), lineOffset = before.split('\n').length - 1;
+    const column = offset - before.lastIndexOf('\n');
+    found.push({
+      label, labelOrigin: { type: 'span', startLine: snippet.startLine + lineOffset, endLine: snippet.startLine + lineOffset,
+        startColumn: column, endColumn: column + label.length },
+    });
+  }
+  if (!found.length) available.add('generic:Module');
+  return found.length ? found : [{ label: 'Module', labelOrigin: { type: 'generic', label: 'Module' } }];
+}
+
+function candidatesFor(source, policy, coverage = {}) {
+  const selections = [], seen = new Set();
+  const available = new Set();
+  const hints = lexicalHints(source.text);
+  const ranks = new Map(hints.entities.map(hint => [hint.label, hint.rank]));
+  for (const selection of snippets(source.text, coverage)) {
+    const { offset, ...snippet } = selection;
+    if (!safeText(snippet.text)) continue;
+    for (const entity of entities(selection, hints, available)) {
+      // Same exact identifier in a file is one lexical entity, not a claim
+      // about language-level scoping. Different files always have distinct IDs.
+      const entityKey = opaque('entity', source.id, entity.labelOrigin.type, entity.label);
+      if (seen.has(entityKey)) continue;
+      seen.add(entityKey);
+      selections.push({ entity, snippet, entityKey, rank: ranks.get(entity.label) ?? 5 });
+    }
+  }
+  coverage.available = available.size;
+  return selections.sort((a, b) => a.rank - b.rank || a.snippet.startLine - b.snippet.startLine)
+    .slice(0, LIMITS.candidates).map(({ entity, snippet, entityKey }) => {
+      const fields = {
+        artifactId: source.id, hash: source.hash, generation: source.generation,
+        ...entity, ...snippet, sourceClass: source.sourceClass, complete: source.complete,
+        entityKey, sourceRef: source.sourceRef,
+      };
+      const digest = candidateDigest(fields, policy);
+      return freeze({ id: opaque('candidate', digest), ...fields, digest });
+    });
+}
+
+export function buildCandidates({ event, artifacts = [], publicText = null, policy, onDiagnostic } = {}) {
+  policy = createPolicy(policy);
+  const report = value => {
+    try {
+      const pending = onDiagnostic?.(freeze(value));
+      if (pending && typeof pending.then === 'function') Promise.resolve(pending).catch(() => {});
+    } catch { /* Diagnostics never affect extraction. */ }
+  };
+  if (!policy.transmitSource || !plain(event) || !isId(event.id) ||
+      ['tool.requested', 'capture.gap'].includes(event.kind)) {
+    report({ reason: !policy.transmitSource ? 'metadata_only' : 'event_not_classifiable', selected: 0 });
+    return [];
+  }
+  const groups = [];
+  const observations = [];
+  if (Array.isArray(artifacts)) for (const artifact of artifacts.slice(0, LIMITS.paths)) {
+    const observation = { artifactId: artifact?.id, available: 0, selected: 0, reason: 'no_candidates' };
+    observations.push(observation);
+    if (artifact?.status !== 'present' || artifact.exists !== true || artifact.complete !== true ||
+        !isId(artifact.id) || !isHash(artifact.hash) || !integer(artifact.generation, 1) ||
+        excluded(artifact.relativePath, policy) || !safeText(artifact.text, LIMITS.fileBytes)) {
+      observation.reason = excluded(artifact?.relativePath, policy) ? 'excluded_path'
+        : artifact?.status === 'missing' ? 'file_missing'
+        : artifact?.status === 'partial' || artifact?.complete === false ? 'incomplete_artifact'
+        : artifact?.status !== 'present' ? 'artifact_unavailable'
+        : typeof artifact.text !== 'string' ? 'source_withheld'
+        : !artifact.text.trim() ? 'empty_source' : 'source_not_safe';
+      continue;
+    }
+    const group = candidatesFor({
+      ...artifact, sourceClass: 'source', sourceRef: {
+        type: 'artifact', artifactId: artifact.id, hash: artifact.hash, generation: artifact.generation,
+      },
+    }, policy, observation);
+    groups.push(group);
+  }
+  if (['turn.prompted', 'intent.observed'].includes(event.kind) && safeText(publicText, LIMITS.snippetChars * 4)) {
+    const contentVersion = integer(event.sequence, 1) ? event.sequence : 1;
+    const digest = hash(publicText);
+    groups.push(candidatesFor({
+      id: event.id, text: publicText, hash: digest, generation: contentVersion,
+      complete: event.incomplete === false, sourceClass: 'public_intent',
+      sourceRef: { type: 'message', messageId: event.id, hash: digest, contentVersion },
+    }, policy));
+  }
+  const result = [];
+  for (let offset = 0; offset < LIMITS.candidates && result.length < LIMITS.candidates; offset++) {
+    for (const group of groups) if (group[offset] && result.length < LIMITS.candidates) result.push(group[offset]);
+  }
+  for (const observation of observations) {
+    observation.selected = result.filter(candidate => candidate.artifactId === observation.artifactId).length;
+    if (observation.truncated) observation.reason = 'snippet_limit';
+    else if (observation.available) observation.reason = observation.selected < observation.available ? 'candidate_limit' : 'candidates_ready';
+    report(observation);
+  }
+  if (Array.isArray(artifacts) && artifacts.length > LIMITS.paths) report({
+    reason: 'artifact_limit', available: artifacts.length, selected: LIMITS.paths,
+  });
+  return freeze(result);
+}
+
+function readSet(candidates) {
+  const refs = new Map();
+  for (const candidate of candidates) {
+    const ref = candidate.sourceRef.type === 'message' ? candidate.sourceRef :
+      { artifactId: candidate.artifactId, hash: candidate.hash, generation: candidate.generation };
+    refs.set(JSON.stringify(ref), clone(ref));
+  }
+  return [...refs.values()];
+}
+const bundleId = (policyVersion, candidates, refs) => opaque('bundle', policyVersion, candidates.map(c => c.digest), refs);
+
+export function materializeBundle({ candidates = [], verdicts = [], policy, intakePolicy = {} } = {}) {
+  policy = createPolicy(policy);
+  const sensitiveMax = intakePolicy?.sensitiveMax ?? 0.1, relevantMin = intakePolicy?.relevantMin ?? 0.5;
+  let approved = [];
+  const counts = new Map(), judgments = new Map(), versions = new Map(), quarantined = [];
+  // Overflow is rejected wholesale; trimming before duplicate detection would
+  // let a conflicting verdict placed beyond the limit approve content.
+  if (Array.isArray(candidates) && candidates.length <= LIMITS.candidates && Array.isArray(verdicts) &&
+      verdicts.length <= LIMITS.candidates && probability(sensitiveMax) && probability(relevantMin)) {
+    for (const c of candidates) {
+      counts.set(c?.id, (counts.get(c?.id) ?? 0) + 1);
+      if (c?.artifactId) {
+        const key = `${c.hash}:${c.generation}`;
+        const previous = versions.get(c.artifactId);
+        versions.set(c.artifactId, previous === undefined || previous === key ? key : null);
+      }
+    }
+    for (const v of verdicts) {
+      if (judgments.has(v?.candidateId)) judgments.set(v?.candidateId, null);
+      else judgments.set(v?.candidateId, v);
+    }
+    for (const c of candidates) {
+      const v = judgments.get(c?.id);
+      const sensitivityApproved = counts.get(c?.id) === 1 && versions.get(c?.artifactId) !== null && validCandidate(c, policy) &&
+        exactKeys(v, ['candidateId', 'digest', 'relevant', 'sensitive']) && v.digest === c.digest &&
+        probability(v.sensitive) && probability(v.relevant) && v.sensitive <= sensitiveMax;
+      if (!sensitivityApproved) { if (plain(c)) quarantined.push(c); continue; }
+      if (v.relevant < relevantMin) continue;
+      approved.push(clone(c));
+    }
+    // One snippet may describe several entities. A conflicting/missing safety
+    // answer quarantines its copied context, not just one candidate's title.
+    approved = approved.filter(c => !quarantined.some(blocked =>
+      c.text === blocked.text || c.artifactId === blocked.artifactId &&
+      c.startLine <= blocked.endLine && blocked.startLine <= c.endLine));
+  }
+  const refs = readSet(approved);
+  const bundle = freeze({ id: bundleId(policy.version, approved, refs), policyVersion: policy.version, candidates: approved, readSet: refs });
+  approvedBundles.add(bundle);
+  return bundle;
+}
+
+export function validBundle(bundle, policy) {
+  if (!approvedBundles.has(bundle) || !exactKeys(bundle, ['id', 'policyVersion', 'candidates', 'readSet']) || bundle.policyVersion !== policy.version ||
+      !Array.isArray(bundle.candidates) || bundle.candidates.length > LIMITS.candidates ||
+      !Array.isArray(bundle.readSet) || bundle.readSet.length > LIMITS.candidates ||
+      bundle.candidates.some(c => !validCandidate(c, policy))) return false;
+  if (new Set(bundle.candidates.map(c => c.id)).size !== bundle.candidates.length) return false;
+  const refs = readSet(bundle.candidates);
+  return equal(refs, bundle.readSet) && bundle.id === bundleId(policy.version, bundle.candidates, refs);
+}
+
+export function proposalId(bundle, source, target, relation, evidence) {
+  return opaque('proposal', bundle.id, source, target, relation, evidence);
+}
+export function buildRelationProposals(bundle, limits = {}) {
+  const candidates = Array.isArray(bundle?.candidates) ? bundle.candidates : [];
+  if (!approvedBundles.has(bundle) || candidates.length > LIMITS.candidates || !isId(bundle?.id) ||
+      new Set(candidates.map(c => c.id)).size !== candidates.length || candidates.some(c => !isId(c.id))) return { proposals: [], omitted: 0 };
+  const requested = [limits.maxProposals, limits.maxRelationProposals].filter(n => integer(n, 0));
+  const questionLimit = integer(limits.maxQuestionsPerStage, 0, 1000) ? limits.maxQuestionsPerStage : 40;
+  const maximum = Math.min(LIMITS.proposals, ...requested, Math.max(0, Math.floor((questionLimit - 1 - 2 * candidates.length) / 2)));
+  const pairs = [], hints = new Map(), analyses = new Map();
+  for (const candidate of candidates) {
+    const key = JSON.stringify([candidate.artifactId, candidate.hash, candidate.generation, candidate.startLine, candidate.text]);
+    if (analyses.has(key)) continue;
+    const analysis = lexicalHints(candidate.text);
+    analyses.set(key, analysis);
+    for (const hint of analysis.pairs) {
+      const pairKey = JSON.stringify([candidate.artifactId, candidate.hash, candidate.generation, hint.source, hint.target]);
+      const prior = hints.get(pairKey);
+      if (!prior || prior.rank > hint.rank) hints.set(pairKey, hint);
+    }
+  }
+  for (const source of candidates) for (const target of candidates) {
+    if (source.id === target.id || source.entityKey === target.entityKey) continue;
+    const colocated = source.artifactId === target.artifactId && source.hash === target.hash && source.generation === target.generation;
+    const hint = colocated ? hints.get(JSON.stringify([source.artifactId, source.hash, source.generation, source.label, target.label])) : null;
+    pairs.push({ source, target, rank: hint?.rank ?? (colocated ? 10 : 20), offset: hint?.offset ?? 0, kind: hint?.kind });
+  }
+  pairs.sort((a, b) => a.rank - b.rank || a.offset - b.offset);
+  const proposals = [];
+  // Exhaust the six independent relation questions for the best lexical pair
+  // before fanout. A binding/constructor pair prioritizes the dependency
+  // question in a remaining slot; this is selection, never semantic evidence.
+  for (const { source, target, kind } of pairs) {
+    const relations = kind === 'binding' ? ['depends_on', ...RELATIONS.filter(r => r !== 'depends_on')] : RELATIONS;
+    for (const relation of relations) {
+      if (proposals.length >= maximum) break;
+      const evidenceCandidateIds = [source.id, target.id];
+      proposals.push({
+        id: proposalId(bundle, source.id, target.id, relation, evidenceCandidateIds),
+        sourceCandidateId: source.id, targetCandidateId: target.id, relation, evidenceCandidateIds,
+      });
+    }
+    if (proposals.length >= maximum) break;
+  }
+  return freeze({ proposals, omitted: pairs.length * RELATIONS.length - proposals.length });
+}

package/runtime/core/common.mjs

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+
+export const LIMITS = Object.freeze({
+  paths: 32, trackedPaths: 1024, fileBytes: 256 * 1024,
+  candidates: 12, snippetChars: 1800, snippetLines: 24,
+  labelChars: 80, refs: 8, excerptChars: 256, graphBytes: 1024 * 1024,
+  admissionBytes: 896 * 1024, nodes: 256, edges: 768, operations: 1024,
+  proposals: 7, coordinate: 100000, rawChars: 256 * 1024,
+});
+export const ROLES = Object.freeze([
+  'client', 'service', 'datastore', 'queue', 'external', 'module',
+  'function', 'class', 'interface', 'event', 'configuration', 'package',
+]);
+export const ROLE_SHAPES = Object.freeze({
+  client: 'browser', service: 'component', datastore: 'cylinder', queue: 'queue',
+  external: 'cloud', module: 'rect', function: 'hexagon', class: 'class_box',
+  interface: 'interface_box', event: 'document', configuration: 'parallelogram', package: 'folder',
+});
+export const ROLE_LABELS = Object.freeze({
+  client: 'Client', service: 'Service', datastore: 'Datastore', queue: 'Queue',
+  external: 'External', module: 'Module', function: 'Function', class: 'Class',
+  interface: 'Interface', event: 'Event', configuration: 'Configuration', package: 'Package',
+});
+export const GENERIC_LABELS = Object.freeze([
+  'Component', 'Module', 'Client', 'Service', 'Datastore', 'Queue', 'External',
+  'Function', 'Class', 'Interface', 'Event', 'Configuration', 'Package',
+]);
+export const RELATIONS = Object.freeze(['calls', 'reads', 'writes', 'publishes', 'consumes', 'depends_on']);
+export const KINDS = Object.freeze([
+  'session.started', 'turn.prompted', 'intent.observed', 'tool.requested',
+  'tool.succeeded', 'tool.failed', 'tool.interrupted', 'tool.denied', 'tool.unresolved',
+  'batch.completed', 'artifact.changed', 'verification.observed', 'agent.started',
+  'agent.stopped', 'turn.stopped', 'session.ended', 'capture.gap',
+]);
+export const CATEGORIES = Object.freeze(['read', 'write', 'edit', 'shell', 'search', 'test', 'other']);
+export const OUTCOMES = Object.freeze(['pending', 'succeeded', 'failed', 'interrupted', 'denied', 'unresolved', 'observed']);
+export const SHAPES = Object.freeze([
+  'rounded_rect', 'rect', 'cylinder', 'cloud', 'diamond', 'group',
+  'hexagon', 'class_box', 'interface_box', 'document', 'parallelogram', 'folder',
+  'browser', 'component', 'queue',
+]);
+export const EVIDENCE_STATES = Object.freeze(['proposed', 'observed', 'verified', 'removed']);
+export const ACTIVITY_STATES = Object.freeze(['idle', 'pending', 'running', 'failed', 'interrupted', 'unknown']);
+export const CLASSIFICATIONS = Object.freeze(['pending', 'accepted', 'tentative', 'abstained', 'stale']);
+export const VALIDITIES = Object.freeze(['current', 'stale', 'retracted']);
+
+export const hash = value => createHash('sha256').update(typeof value === 'string' || value instanceof Uint8Array ? value : JSON.stringify(value)).digest('hex');
+export const opaque = (prefix, ...values) => `${prefix}-${hash(values).slice(0, 32)}`;
+export const isId = value => typeof value === 'string' && /^(?:[a-z][a-z0-9_]{0,23}-)?[a-f0-9]{24,64}$/.test(value);
+export const isHash = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export const probability = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+export const integer = (value, min = 0, max = Number.MAX_SAFE_INTEGER) => Number.isSafeInteger(value) && value >= min && value <= max;
+export const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+export const exactKeys = (value, required, optional = []) => plain(value) &&
+  required.every(key => Object.hasOwn(value, key)) &&
+  Object.keys(value).every(key => required.includes(key) || optional.includes(key));
+export const equal = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export const clone = value => structuredClone(value);
+export function freeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+export function fail(code = 'INVALID_CORE_INPUT') {
+  // Fixed errors only: no paths, source, transport messages or raw caller fields.
+  throw new TypeError(code);
+}

package/runtime/core/evidence.mjs

@@ -0,0 +1,150 @@
+import { constants, realpathSync, statSync } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { LIMITS, fail, freeze, hash, integer, isHash, opaque, plain } from './common.mjs';
+import { createPolicy, excluded, privateText } from './privacy.mjs';
+
+const absent = error => error?.code === 'ENOENT' || error?.code === 'ENOTDIR';
+const fingerprint = stat => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.mode].map(String).join(':');
+
+export class EvidenceStore {
+  #root; #inputRoot; #policy; #records = new Map(); #byId = new Map();
+  constructor({ projectRoot, policy } = {}) {
+    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);
+  }
+
+  #locator(input) {
+    if (typeof input !== 'string' || !input || input.length > 4096 || /[\0\r\n\\]/.test(input)) return null;
+    let absolute = path.resolve(this.#root, input);
+    // Accept the root spelling supplied by the caller (e.g. macOS /var ->
+    // /private/var), while keeping the authority and stored identity canonical.
+    const inputRelative = path.relative(this.#inputRoot, absolute);
+    if (this.#inputRoot !== this.#root && inputRelative && inputRelative !== '..' &&
+        !inputRelative.startsWith(`..${path.sep}`) && !path.isAbsolute(inputRelative)) {
+      absolute = path.resolve(this.#root, inputRelative);
+    }
+    const relative = path.relative(this.#root, absolute);
+    if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
+    return { absolute, relative: relative.split(path.sep).join('/') };
+  }
+
+  async #inspect(locator) {
+    // Fail closed on symlinks, including inside-root aliases. Never follow an
+    // excluded path through a differently named alias.
+    if (excluded(locator.relative, this.#policy)) {
+      let stamp = 'excluded';
+      try { stamp += `:${fingerprint(await lstat(locator.absolute, { bigint: true }))}`; } catch { /* No absence assertion through a policy exclusion. */ }
+      return { status: 'unavailable', exists: null, complete: false, hash: null, text: null, stamp };
+    }
+    const parts = locator.relative.split('/');
+    let current = this.#root;
+    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)}`);
+      }
+    } catch (error) {
+      return absent(error) ? { status: 'missing', exists: false, complete: true, hash: null, text: null, stamp: 'missing' }
+        : this.#unavailable('unreadable');
+    }
+    let handle;
+    try {
+      // NOFOLLOW closes the final-component race. Revalidate the complete path
+      // and inode before and after reading to reject ancestor replacement races.
+      handle = await open(locator.absolute, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+      const before = await handle.stat({ bigint: true });
+      const stamp = fingerprint(before);
+      if (!before.isFile() || (before.mode & 0o444n) === 0n) return this.#unavailable(stamp);
+      if (before.size > BigInt(LIMITS.fileBytes)) return { status: 'partial', exists: true, complete: false, hash: null, text: null, stamp };
+      if (!(await this.#sameFile(locator, before))) return this.#unavailable(stamp);
+      const buffer = Buffer.alloc(Number(before.size) + 1);
+      let offset = 0;
+      while (offset < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+        if (!bytesRead) break;
+        offset += bytesRead;
+      }
+      const after = await handle.stat({ bigint: true });
+      if (fingerprint(after) !== stamp || offset !== Number(before.size) || !(await this.#sameFile(locator, after))) {
+        return { status: 'partial', exists: true, complete: false, hash: null, text: null, stamp: `unstable:${fingerprint(after)}` };
+      }
+      const bytes = buffer.subarray(0, offset);
+      let text;
+      try { text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); } catch {
+        return { status: 'partial', exists: true, complete: false, hash: hash(bytes), text: null, stamp };
+      }
+      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,
+      };
+    } catch {
+      // A disappearing/racing file during open/read is uncertainty. A subsequent
+      // reconcile can confirm absence with a fresh path walk.
+      return this.#unavailable('unreadable');
+    } finally { if (handle) await handle.close().catch(() => {}); }
+  }
+
+  #unavailable(stamp) {
+    return { status: 'unavailable', exists: null, complete: false, hash: null, text: null, stamp };
+  }
+  async #sameFile(locator, stat) {
+    try {
+      if (await realpath(locator.absolute) !== locator.absolute) return false;
+      const current = await lstat(locator.absolute, { bigint: true });
+      return current.isFile() && !current.isSymbolicLink() && fingerprint(current) === fingerprint(stat);
+    } catch { return false; }
+  }
+
+  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 id = opaque('artifact', this.#root, locator.relative);
+    const generation = previous ? previous.generation + (previous.version !== version ? 1 : 0) : 1;
+    const artifact = {
+      id, path: locator.absolute, relativePath: locator.relative,
+      hash: observed.hash, generation, exists: observed.exists, status: observed.status,
+      text: observed.text, complete: observed.complete,
+    };
+    // 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 };
+    this.#records.set(locator.relative, record);
+    this.#byId.set(id, record);
+    return freeze(artifact);
+  }
+
+  async capture(paths = []) {
+    if (!Array.isArray(paths)) return [];
+    const results = [], seen = new Set();
+    for (const input of paths.slice(0, LIMITS.paths)) {
+      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;
+      results.push(await this.#captureOne(locator));
+    }
+    return results;
+  }
+  async reconcile() {
+    const results = [];
+    for (const record of this.#records.values()) results.push(await this.#captureOne(record));
+    return results;
+  }
+  isCurrent(refs) {
+    if (!Array.isArray(refs) || refs.length > LIMITS.trackedPaths) return false;
+    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;
+    });
+  }
+}