@tiinex/core 0.1.1

package/src/lineage/lineage.parentBinding.js

@@ -0,0 +1,104 @@
+import { canonicalPath, githubRepoRelativePathFromUrl } from './lineage.targetKeys.js';
+
+export function declaredParentBindingTargetValuesForNode(node = {}, rawTarget = '') {
+  const record = node?.record || node || {};
+  const values = [
+    record?.sourceTarget?.parentRawUrl,
+    record?.sourceTarget?.parentSourceUrl,
+    record?.snapshot?.parentRawUrl,
+    record?.snapshot?.parentSourceUrl,
+    record?.sourceTarget?.parentArtifactPath,
+    record?.snapshot?.parentArtifactPath,
+    record?.parentOrigin,
+    record?.origin
+  ];
+  const out = [];
+  const seen = new Set();
+  for (const value of values) {
+    const raw = String(value || '').trim();
+    if (!raw || seen.has(raw)) continue;
+    seen.add(raw);
+    const githubFilePath = githubRepoRelativePathFromUrl(raw);
+    const filePath = githubFilePath || (isExternalUrl(raw) ? '' : canonicalPath(raw));
+    if (!filePath && !isGitHubIssueTarget(raw)) continue;
+    if (!declaredParentBindingMatchesTarget(raw, rawTarget)) continue;
+    if (!isStrongDeclaredParentBinding(raw, filePath)) continue;
+    out.push(Object.freeze({ raw, filePath, isGitHubIssueTarget: isGitHubIssueTarget(raw) }));
+  }
+  return out;
+}
+
+export function isSyntheticPublicationLineageNode(node = {}) {
+  const record = node?.record || node || {};
+  const mode = String(record.sourceMode || record.recoveryKind || '').toLowerCase();
+  const targetKind = String(record.sourceTarget?.targetKind || record.snapshot?.sourceKind || '').toLowerCase();
+  const path = canonicalPath(record.path || node?.path || '').toLowerCase();
+  const recovered = String(record.recoveredFromUrl || record.sourceTarget?.inputTarget || record.snapshot?.sourceUrl || '').trim();
+  return Boolean(
+    mode.includes('github-issue') ||
+    mode.includes('github-comment') ||
+    targetKind.includes('github-issue') ||
+    targetKind.includes('github-comment') ||
+    path.includes('/.issues/') ||
+    path.includes('/.github/.issues/') ||
+    isGitHubIssueTarget(recovered)
+  );
+}
+
+function declaredParentBindingMatchesTarget(parent = '', target = '') {
+  const parentPath = githubRepoRelativePathFromUrl(parent) || canonicalPath(parent);
+  const targetPath = githubRepoRelativePathFromUrl(target) || canonicalPath(target);
+  if (isGitHubIssueTarget(parent)) {
+    if (isGitHubIssueTarget(target)) return normalizeGitHubIssueTarget(parent) === normalizeGitHubIssueTarget(target);
+    const parentCommentId = githubIssueCommentIdFromValue(parent);
+    const targetCommentId = githubIssueCommentIdFromValue(targetPath || target);
+    if (parentCommentId && targetCommentId && parentCommentId === targetCommentId) return true;
+    return false;
+  }
+  if (!parentPath) return false;
+  if (!targetPath) return true;
+  if (parentPath === targetPath || parentPath.endsWith(`/${targetPath}`) || targetPath.endsWith(`/${parentPath}`)) return true;
+  const parentBase = basename(parentPath);
+  const targetBase = basename(targetPath);
+  return Boolean(parentBase && targetBase && parentBase === targetBase && parentPath.includes('/'));
+}
+
+
+function githubIssueCommentIdFromValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+  const direct = raw.match(/(?:issuecomment-|issues\/comments\/|comment-(?:\d+-)?)(\d{4,})/i)?.[1] || '';
+  if (direct) return direct;
+  try {
+    const url = new URL(raw);
+    return url.hash.match(/issuecomment-(\d+)/i)?.[1] || '';
+  } catch (_) {}
+  return '';
+}
+
+function isStrongDeclaredParentBinding(raw = '', path = '') {
+  if (isGitHubIssueTarget(raw)) return true;
+  const clean = canonicalPath(path || raw);
+  if (!clean) return false;
+  if (/^\.topics(?:\/|$)/.test(clean)) return true;
+  return clean.includes('/');
+}
+
+function isExternalUrl(value = '') { try { const url = new URL(String(value || '').trim()); return /^https?:$/i.test(url.protocol); } catch (_) { return false; } }
+
+function isGitHubIssueTarget(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    return (url.hostname === 'github.com' || url.hostname.endsWith('.github.com') || url.hostname === 'api.github.com') && parts.includes('issues');
+  } catch (_) { return false; }
+}
+
+function normalizeGitHubIssueTarget(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    return `${url.hostname.toLowerCase()}${url.pathname.toLowerCase()}${url.hash.toLowerCase()}`;
+  } catch (_) { return String(value || '').trim().toLowerCase(); }
+}
+
+function basename(path = '') { return canonicalPath(path).split('/').filter(Boolean).pop() || ''; }

package/src/lineage/lineage.pathBasis.js

@@ -0,0 +1,47 @@
+export function lineageBasePathForNode(node = {}) {
+  return lineageBasePathForRecord(node?.record || { path: node?.path || '' }, node?.path || '');
+}
+
+export function lineageBasePathForRecord(record = {}, fallbackPath = '') {
+  const recordPath = firstNonEmpty(fallbackPath, record.path);
+  const sourcePath = firstNonEmpty(record.sourceTarget?.sourceArtifactPath, record.snapshot?.sourceArtifactPath, record.sourcePath, record.source?.path);
+  if (isSyntheticIssueMaterialPath(recordPath)) return sourcePath || recordPath;
+  return recordPath || sourcePath;
+}
+
+function firstNonEmpty(...items) { return items.map((item) => String(item || '').trim()).find(Boolean) || ''; }
+
+function isSyntheticIssueMaterialPath(path = '') {
+  const raw = String(path || '').trim();
+  const clean = canonicalPath(raw).toLowerCase();
+  if (!clean) return false;
+  if (/^https?:\/\/github\.com\//i.test(raw)) return true;
+  return clean.includes('/.github/.issues/') || clean.includes('/.issues/github/') || clean.includes('/issues/') || /^github\.com\/[^/]+\/[^/]+\/issues\/\d+/.test(clean);
+}
+
+function canonicalPath(value = '') {
+  let raw = String(value || '').trim();
+  if (!raw) return '';
+  const githubPath = githubRepoRelativePathFromUrl(raw);
+  if (githubPath) raw = githubPath;
+  else { try { const url = new URL(raw); raw = url.pathname.replace(/^\/+/, ''); } catch (_) {} }
+  const out = [];
+  for (const part of raw.replace(/\\/g, '/').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}
+
+
+function githubRepoRelativePathFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const parts = url.pathname.split('/').filter(Boolean);
+    const host = url.hostname.toLowerCase();
+    if (host === 'raw.githubusercontent.com' && parts.length >= 4) return parts.slice(3).join('/');
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 5 && parts[2] === 'blob') return parts.slice(4).join('/');
+  } catch (_) {}
+  return '';
+}

package/src/lineage/lineage.resolve.js

@@ -0,0 +1,388 @@
+import { createLineageEdge, createLineageFinding, createLineageNode, LINEAGE_VIEW_MODEL_SCHEMA_ID, LineageEdgeKind, LineageResolutionStatus } from './lineage.model.js';
+import { issueLocalPathKeysForNode, issueLocalPathMatches } from './lineage.githubIssueLocal.js';
+import { filterGitHubIssueCommentCandidatesForTarget, githubIssueCommentIdFromValue, githubIssueCommentIdsForNode } from './lineage.githubIssueComment.js';
+import { filterExactGitHubIssueCandidatesForTarget } from './lineage.githubIssueTarget.js';
+import { isDotRelativeReference, isSimpleRelativeReference, isUrlLike, relativeCandidatePath, resolveCandidateNodes } from './lineage.candidateResolution.js';
+import { canonicalIntegrityValue, parentIntegrityValuesForTarget, selfIntegrityValuesForNode, verifiedIntegrityMatch, withParentIntegrityStatus } from './lineage.integrity.js';
+import { canonicalPath, canonicalToken, githubRepoRelativePathFromUrl, provenanceTargetKeysForValue, sourceKeyFromTarget } from './lineage.targetKeys.js';
+import { declaredParentBindingTargetValuesForNode, isSyntheticPublicationLineageNode } from './lineage.parentBinding.js';
+import { exactUnloadedParent } from './lineage.parentAuthority.js';
+import { exactPathMatches, findPathSuffixMatches, sourceConstraintFromNode, sourceConstraintFromTarget } from './lineage.sourceScope.js';
+export function resolveLineage(artifacts = [], options = {}) {
+  const records = Array.isArray(artifacts) ? artifacts : [];
+  const nodes = records.map((record, index) => createLineageNode(record, index));
+  const index = buildLineageIndex(nodes);
+  const edges = [];
+  const findings = [];
+  for (const node of nodes) {
+    const targets = declaredTargetsFor(node);
+    if (!targets.length) {
+      findings.push(createLineageFinding('lineage.root', 'No declared parent trace/origin; artifact is treated as a lineage root in the loaded set.', 'info', { nodeId: node.id }));
+      continue;
+    }
+    const traceTarget = targets.find((target) => target.kind === LineageEdgeKind.parent);
+    const originTarget = targets.find((target) => target.kind === LineageEdgeKind.origin);
+    const parentMatch = traceTarget ? resolveTarget(traceTarget.value, index, node, { expectedIntegrityValues: traceTarget.integrityValues, targetKind: LineageEdgeKind.parent }) : null;
+    const originMatch = originTarget ? resolveTarget(originTarget.value, index, node, { targetKind: LineageEdgeKind.origin }) : null;
+    if (parentMatch?.selfReference) {
+      findings.push(createLineageFinding('lineage.parent.selfReference', 'Declared Parent Trace resolves to the declaring artifact itself; no parent edge was created.', 'warning', { nodeId: node.id, target: traceTarget.value }));
+      if (originMatch?.ambiguous) {
+        findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      } else if (originMatch?.blocked) {
+        findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget && originMatch && originMatch.id !== node.id) {
+        edges.push(createLineageEdge(originMatch.id, node.id, LineageEdgeKind.origin, {
+          target: originTarget.value,
+          method: originMatch.method,
+          label: 'origin recovery hint',
+          status: LineageResolutionStatus.degraded
+        }));
+        findings.push(createLineageFinding('lineage.parent.selfReferenceOriginFallback', 'Parent Trace resolved to self; Origin resolved as recovery context only.', 'info', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget && !originMatch) {
+        findings.push(createLineageFinding('lineage.origin.unresolved', 'Origin not present in loaded material.', 'info', { nodeId: node.id, target: originTarget.value }));
+      }
+      continue;
+    }
+    if (parentMatch?.blocked) {
+      findings.push(createLineageFinding(parentMatch.code || 'lineage.target.outOfBoundary', parentMatch.message || 'Lineage target outside boundary; no edge created.', 'warning', { nodeId: node.id, target: traceTarget.value }));
+      if (originMatch?.ambiguous) {
+        findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      } else if (originTarget && originMatch && !originMatch.blocked) {
+        edges.push(createLineageEdge(originMatch.id, node.id, LineageEdgeKind.origin, {
+          target: originTarget.value,
+          method: originMatch.method,
+          label: 'origin fallback edge',
+          status: LineageResolutionStatus.degraded
+        }));
+        findings.push(createLineageFinding('lineage.parent.boundaryBlocked', 'Parent Trace was outside boundary; Origin is recovery context.', 'info', { nodeId: node.id, target: originTarget.value }));
+      } else if (originMatch?.blocked) {
+        findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget) {
+        findings.push(createLineageFinding('lineage.origin.unresolved', 'Origin not present in loaded material.', 'info', { nodeId: node.id, target: originTarget.value }));
+      }
+      continue;
+    }
+    if (parentMatch?.unresolvedExact) {
+      const recoveryTarget = parentMatch.recoveryTarget || traceTarget?.value || '';
+      edges.push(createLineageEdge('', node.id, LineageEdgeKind.parent, {
+        status: LineageResolutionStatus.missing,
+        target: recoveryTarget,
+        method: parentMatch.method || 'declared-parent-unloaded',
+        label: 'declared parent known but not loaded'
+      }));
+      findings.push(createLineageFinding('lineage.parent.exactTargetNotLoaded', 'Declared parent identity is known but its artifact is not loaded yet.', 'warning', { nodeId: node.id, target: recoveryTarget }));
+      if (originMatch?.ambiguous) {
+        findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      } else if (originMatch?.blocked) {
+        findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget && originMatch) {
+        edges.push(createLineageEdge(originMatch.id, node.id, LineageEdgeKind.origin, { target: originTarget.value, method: originMatch.method, label: 'origin recovery hint', status: LineageResolutionStatus.degraded }));
+      }
+      continue;
+    }
+    if (parentMatch?.ambiguous) {
+      findings.push(createLineageFinding('lineage.target.ambiguous', 'Parent Trace ambiguous; no edge created.', 'warning', { nodeId: node.id, target: traceTarget.value, candidates: parentMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      if (originMatch?.ambiguous) {
+        findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      } else if (originMatch?.blocked) {
+        findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget && !originMatch) {
+        findings.push(createLineageFinding('lineage.origin.unresolved', 'Origin not present in loaded material.', 'info', { nodeId: node.id, target: originTarget.value }));
+      }
+      continue;
+    }
+    if (parentMatch) {
+      edges.push(createLineageEdge(parentMatch.id, node.id, LineageEdgeKind.parent, {
+        target: traceTarget.value,
+        method: parentMatch.method,
+        label: 'declared parent trace',
+        status: parentMatch.status || LineageResolutionStatus.resolved,
+        diagnostics: parentMatch.diagnostics || []
+      }));
+      if (parentMatch.status === LineageResolutionStatus.mismatch) {
+        findings.push(createLineageFinding('lineage.parent.integrityMismatch', 'Declared parent was found by stable identity, but its loaded integrity value does not match the child declaration.', 'error', { nodeId: node.id, target: traceTarget.value }));
+      } else if (parentMatch.status === LineageResolutionStatus.probable) {
+        findings.push(createLineageFinding('lineage.parent.probable', 'Declared parent was found by stable identity, but no loaded self-integrity value was available to verify the edge.', 'info', { nodeId: node.id, target: traceTarget.value }));
+      }
+      if (originMatch?.ambiguous) {
+        findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      } else if (originMatch?.blocked) {
+        findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      } else if (originTarget && originMatch && originMatch.id !== parentMatch.id) {
+        edges.push(createLineageEdge(originMatch.id, node.id, LineageEdgeKind.origin, {
+          target: originTarget.value,
+          method: originMatch.method,
+          label: 'origin recovery hint'
+        }));
+      } else if (originTarget && !originMatch) {
+        findings.push(createLineageFinding('lineage.origin.unresolved', 'Origin not present in loaded material.', 'info', { nodeId: node.id, target: originTarget.value }));
+      }
+      continue;
+    }
+    if (traceTarget) {
+      edges.push(createLineageEdge('', node.id, LineageEdgeKind.parent, {
+        status: LineageResolutionStatus.missing,
+        target: traceTarget.value,
+        method: 'unresolved-trace',
+        label: 'missing parent trace'
+      }));
+      findings.push(createLineageFinding('lineage.parent.missing', 'Parent Trace target not loaded.', 'warning', { nodeId: node.id, target: traceTarget.value }));
+    }
+    if (originMatch?.ambiguous) {
+      findings.push(createLineageFinding('lineage.target.ambiguous', 'Origin ambiguous; no edge created.', 'warning', { nodeId: node.id, target: originTarget.value, candidates: originMatch.candidates.map((candidate) => candidate.id).join(', ') }));
+      continue;
+    }
+    if (originMatch?.blocked) {
+      findings.push(createLineageFinding(originMatch.code || 'lineage.target.outOfBoundary', originMatch.message || 'Declared Origin is outside boundary; no edge was created.', 'warning', { nodeId: node.id, target: originTarget.value }));
+      continue;
+    }
+    if (originTarget && originMatch) {
+      edges.push(createLineageEdge(originMatch.id, node.id, LineageEdgeKind.origin, {
+        target: originTarget.value,
+        method: originMatch.method,
+        label: 'origin fallback edge',
+        status: traceTarget ? LineageResolutionStatus.degraded : LineageResolutionStatus.resolved
+      }));
+      if (traceTarget) {
+        findings.push(createLineageFinding('lineage.parent.originFallback', 'Parent Trace is missing; Origin is recovery context.', 'info', { nodeId: node.id, target: originTarget.value }));
+      }
+      continue;
+    }
+    if (originTarget) {
+      findings.push(createLineageFinding('lineage.origin.unresolved', 'Origin not present in loaded material.', traceTarget ? 'info' : 'warning', { nodeId: node.id, target: originTarget.value }));
+    }
+  }
+  return {
+    schema: LINEAGE_VIEW_MODEL_SCHEMA_ID,
+    nodes,
+    artifacts: records,
+    edges,
+    findings,
+    stats: {
+      nodes: nodes.length,
+      edges: edges.filter((edge) => edge.status !== LineageResolutionStatus.missing).length,
+      missingEdges: edges.filter((edge) => edge.status === LineageResolutionStatus.missing).length,
+      roots: findings.filter((finding) => finding.code === 'lineage.root').length,
+      warnings: findings.filter((finding) => finding.severity === 'warning' || finding.severity === 'error').length
+    },
+    options: { depth: options.depth || 'loaded' }
+  };
+}
+function declaredTargetsFor(node = {}) {
+  const targets = [];
+  if (node.trace) targets.push({ kind: LineageEdgeKind.parent, value: node.trace, integrityValues: parentIntegrityValuesForTarget(node, node.trace) });
+  if (node.origin) targets.push({ kind: LineageEdgeKind.origin, value: node.origin });
+  return targets;
+}
+function buildLineageIndex(nodes = []) {
+  const index = { byId: new Map(), byRecordTrace: new Map(), byPath: new Map(), bySourcePath: new Map(), byProvenance: new Map(), byIssueLocalPath: new Map(), byGitHubIssueCommentId: new Map(), bySelfIntegrity: new Map() };
+  for (const node of nodes) {
+    const id = canonicalToken(node.id);
+    if (id) {
+      addIndexed(index.byId, id, node);
+      addIndexed(index.byRecordTrace, `record:${id}`, node);
+    }
+    const path = canonicalPath(node.path);
+    if (path) addIndexed(index.byPath, path, node);
+    for (const sourcePath of sourcePathsForNode(node)) addIndexed(index.bySourcePath, sourcePath, node);
+    for (const target of provenanceTargetsForNode(node)) addIndexed(index.byProvenance, target, node);
+    for (const commentId of githubIssueCommentIdsForNode(node)) addIndexed(index.byGitHubIssueCommentId, commentId, node);
+    for (const hash of selfIntegrityValuesForNode(node)) addIndexed(index.bySelfIntegrity, hash, node);
+    for (const issueLocalPath of issueLocalPathKeysForNode(node)) addIndexed(index.byIssueLocalPath, issueLocalPath, node);
+  }
+  return index;
+}
+function sourcePathsForNode(node = {}) {
+  const record = node.record || {};
+  const values = [record.source?.path, record.sourcePath, record.sourceTarget?.sourceArtifactPath, record.snapshot?.sourceArtifactPath].map(canonicalPath).filter(Boolean);
+  return Array.from(new Set(values));
+}
+function provenanceTargetsForNode(node = {}) {
+  const record = node.record || {};
+  const snapshot = record.snapshot || {};
+  const sourceTarget = record.sourceTarget || {};
+  const target = snapshot.target || {};
+  const values = [
+    record.recoveredFromUrl,
+    record.sourceOrigin,
+    record.rawUrl,
+    record.browseUrl,
+    sourceTarget.inputTarget,
+    sourceTarget.rawUrl,
+    sourceTarget.browseUrl,
+    snapshot.sourceUrl,
+    target.canonicalUrl,
+    target.html_url,
+    target.url
+  ];
+  return Array.from(new Set(values.flatMap(provenanceTargetKeysForValue).filter(Boolean)));
+}
+
+function addIndexed(map, key, node) {
+  if (!key || !node) return;
+  const existing = map.get(key);
+  if (!existing) map.set(key, [node]);
+  else existing.push(node);
+}
+function resolveTarget(target, index, declaringNode = null, options = {}) {
+  const raw = String(target || '').trim();
+  if (!raw) return null;
+
+  const expectedIntegrityValues = Array.isArray(options.expectedIntegrityValues) ? options.expectedIntegrityValues.map(canonicalIntegrityValue).filter(Boolean) : [];
+  if (expectedIntegrityValues.length) {
+    const integrityMatch = resolveIntegrityTarget(expectedIntegrityValues, index, declaringNode);
+    if (integrityMatch) return integrityMatch;
+  }
+
+  const token = canonicalToken(raw);
+  const path = canonicalPath(raw);
+  const urlFilePath = githubRepoRelativePathFromUrl(raw);
+  const urlSourceKey = sourceKeyFromTarget(raw);
+  const declaringConstraint = sourceConstraintFromNode(declaringNode);
+  const relative = relativeCandidatePath(raw, declaringNode);
+  const simpleRelative = isSimpleRelativeReference(raw);
+  const dotRelative = isDotRelativeReference(raw);
+  const urlLike = isUrlLike(raw);
+  const recordToken = /^record:/i.test(raw);
+  const finalize = (match) => withParentIntegrityStatus(match, expectedIntegrityValues);
+
+  const resolveDirectToken = () => {
+    const directTokenCandidates = [
+      ['record-trace', index.byRecordTrace.get(token)],
+      ['id', index.byId.get(token)]
+    ];
+    for (const [method, nodes] of directTokenCandidates) {
+      const resolved = resolveCandidateNodes(nodes || [], method, declaringNode);
+      if (resolved) return finalize(resolved);
+    }
+    return null;
+  };
+
+  const resolveProvenanceTarget = () => {
+    for (const targetKey of provenanceTargetKeysForValue(raw)) {
+      const resolved = resolveCandidateNodes(index.byProvenance.get(targetKey) || [], 'provenance-target', declaringNode);
+      if (resolved) return finalize(resolved);
+    }
+    return null;
+  };
+
+  const resolveGithubIssueCommentTarget = (method = 'github-issue-comment-id') => {
+    const commentId = githubIssueCommentIdFromValue(raw);
+    if (!commentId) return null;
+    const candidates = filterGitHubIssueCommentCandidatesForTarget(index.byGitHubIssueCommentId?.get(commentId) || [], raw, declaringNode);
+    const resolved = resolveCandidateNodes(candidates, method, declaringNode);
+    return resolved ? finalize(resolved) : null;
+  };
+
+  const resolveDeclaredParentBinding = () => {
+    if (options.targetKind !== LineageEdgeKind.parent) return null;
+    const bindings = declaredParentBindingTargetValuesForNode(declaringNode, raw);
+    let unresolvedExact = null;
+    for (const binding of bindings) {
+      if (binding.isGitHubIssueTarget) {
+        const commentId = githubIssueCommentIdFromValue(binding.raw);
+        if (commentId) {
+          const exactCommentCandidates = filterGitHubIssueCommentCandidatesForTarget(index.byGitHubIssueCommentId?.get(commentId) || [], binding.raw, declaringNode);
+          const resolvedComment = resolveCandidateNodes(exactCommentCandidates, 'declared-parent-github-comment-id', declaringNode);
+          if (resolvedComment) return finalize(resolvedComment);
+          unresolvedExact ||= exactUnloadedParent(binding.raw, 'declared-parent-github-comment-unloaded');
+          continue;
+        }
+        const issueCandidates = [];
+        for (const targetKey of provenanceTargetKeysForValue(binding.raw)) issueCandidates.push(...(index.byProvenance.get(targetKey) || []));
+        const exactIssueCandidates = filterExactGitHubIssueCandidatesForTarget(issueCandidates, binding.raw, declaringNode);
+        const resolvedIssue = resolveCandidateNodes(exactIssueCandidates, 'declared-parent-github-issue', declaringNode);
+        if (resolvedIssue) return finalize(resolvedIssue);
+        unresolvedExact ||= exactUnloadedParent(binding.raw, 'declared-parent-github-issue-unloaded');
+        continue;
+      }
+      const sourceKey = sourceKeyFromTarget(binding.raw);
+      const constraint = sourceKey ? sourceConstraintFromTarget(sourceKey) : declaringConstraint;
+      const exact = exactPathMatches(binding.filePath, index, constraint, Boolean(constraint.hasConstraint));
+      const resolvedExact = resolveCandidateNodes(exact, 'declared-parent-path', declaringNode);
+      if (resolvedExact) return finalize(resolvedExact);
+      if (canonicalPath(binding.filePath).includes('/')) {
+        const suffix = [
+          ...findPathSuffixMatches(binding.filePath, index.byPath, constraint, Boolean(constraint.hasConstraint)),
+          ...findPathSuffixMatches(binding.filePath, index.bySourcePath, constraint, Boolean(constraint.hasConstraint))
+        ];
+        const resolvedSuffix = resolveCandidateNodes(suffix, 'declared-parent-path-suffix', declaringNode);
+        if (resolvedSuffix) return finalize(resolvedSuffix);
+      }
+      unresolvedExact ||= exactUnloadedParent(binding.raw || binding.filePath, 'declared-parent-path-unloaded');
+    }
+    return unresolvedExact;
+  };
+
+  if (recordToken) return finalize(resolveDirectToken());
+
+  // A declared parent binding is stronger evidence than cwd/path inference.
+  // Evaluate it before relative aliases so a weak ambiguous path cannot veto an
+  // exact publication/comment/source binding carried by the declaring artifact.
+  const strongDeclaredParent = resolveDeclaredParentBinding();
+  if (strongDeclaredParent) return strongDeclaredParent;
+
+  if ((simpleRelative || dotRelative) && relative) {
+    if (relative.blocked) return relative;
+    const contextual = exactPathMatches(relative.path, index, declaringConstraint, true);
+    const resolved = resolveCandidateNodes(contextual, relative.method, declaringNode);
+    if (resolved) return finalize(resolved);
+    const issueLocal = issueLocalPathMatches(raw, index, declaringNode);
+    const resolvedIssueLocal = resolveCandidateNodes(issueLocal, 'issue-local-relative-path', declaringNode);
+    if (resolvedIssueLocal) return finalize(resolvedIssueLocal);
+    const commentIdMatch = resolveGithubIssueCommentTarget('github-issue-comment-id-relative-path');
+    if (commentIdMatch) return commentIdMatch;
+    if (dotRelative && isSyntheticPublicationLineageNode(declaringNode) && path.includes('/')) {
+      const suffix = [
+        ...findPathSuffixMatches(path, index.byPath, declaringConstraint, Boolean(declaringConstraint.hasConstraint)),
+        ...findPathSuffixMatches(path, index.bySourcePath, declaringConstraint, Boolean(declaringConstraint.hasConstraint))
+      ];
+      const resolvedSuffix = resolveCandidateNodes(suffix, 'synthetic-parent-path-suffix', declaringNode);
+      if (resolvedSuffix) return finalize(resolvedSuffix);
+    }
+    return null;
+  }
+
+  if (urlLike && !urlFilePath) {
+    const provenance = resolveProvenanceTarget();
+    if (provenance) return finalize(provenance);
+  }
+
+  const issueLocal = issueLocalPathMatches(raw, index, declaringNode);
+  const resolvedIssueLocal = resolveCandidateNodes(issueLocal, 'issue-local-path', declaringNode);
+  if (resolvedIssueLocal) return finalize(resolvedIssueLocal);
+  const commentIdMatch = resolveGithubIssueCommentTarget('github-issue-comment-id');
+  if (commentIdMatch) return commentIdMatch;
+
+  const direct = resolveDirectToken();
+  if (direct) return finalize(direct);
+
+  const pathConstraint = urlSourceKey ? sourceConstraintFromTarget(urlSourceKey) : declaringConstraint;
+  const exact = exactPathMatches(path, index, pathConstraint, Boolean(pathConstraint.hasConstraint));
+  const resolvedExact = resolveCandidateNodes(exact, 'path', declaringNode);
+  if (resolvedExact) return finalize(resolvedExact);
+
+  const suffixConstraint = urlSourceKey ? sourceConstraintFromTarget(urlSourceKey) : declaringConstraint;
+  const suffixCandidates = [
+    ['path-suffix', findPathSuffixMatches(path, index.byPath, suffixConstraint, Boolean(urlSourceKey))],
+    ['source-path-suffix', findPathSuffixMatches(path, index.bySourcePath, suffixConstraint, Boolean(urlSourceKey))]
+  ];
+  for (const [method, nodes] of suffixCandidates) {
+    const resolved = resolveCandidateNodes(nodes || [], method, declaringNode);
+    if (resolved) return finalize(resolved);
+  }
+
+  if (urlLike) return finalize(resolveProvenanceTarget());
+  return null;
+}
+
+
+function resolveIntegrityTarget(expectedIntegrityValues = [], index = {}, declaringNode = null) {
+  const nodes = [];
+  for (const value of expectedIntegrityValues.map(canonicalIntegrityValue).filter(Boolean)) {
+    nodes.push(...(index.bySelfIntegrity?.get(value) || []));
+  }
+  const resolved = resolveCandidateNodes(nodes, 'integrity-self-hash', declaringNode);
+  if (!resolved || resolved.ambiguous || resolved.selfReference || resolved.blocked) return resolved;
+  return verifiedIntegrityMatch(resolved);
+}

package/src/lineage/lineage.sourceScope.js

@@ -0,0 +1,74 @@
+import { canonicalPath, normalizeRef, normalizeRepoKey } from './lineage.targetKeys.js';
+
+export function exactPathMatches(path, index, constraint = {}, strictSource = false) {
+  const source = [
+    ...(index.byPath.get(canonicalPath(path)) || []),
+    ...(index.bySourcePath.get(canonicalPath(path)) || [])
+  ];
+  return uniqueNodes(filterBySource(source, constraint, strictSource));
+}
+
+export function findPathSuffixMatches(targetPath, pathIndex = new Map(), constraint = {}, strictSource = false) {
+  const path = canonicalPath(targetPath);
+  if (!path || !path.includes('/')) return [];
+  let bestLength = -1;
+  let matches = [];
+  for (const [candidatePath, nodes] of pathIndex.entries()) {
+    if (!candidatePath || path === candidatePath) continue;
+    if (!(path.endsWith(`/${candidatePath}`) || path.endsWith(candidatePath) || candidatePath.endsWith(`/${path}`) || candidatePath.endsWith(path))) continue;
+    const filtered = filterBySource(nodes, constraint, strictSource);
+    if (!filtered.length) continue;
+    if (candidatePath.length > bestLength) {
+      bestLength = candidatePath.length;
+      matches = filtered.slice();
+    } else if (candidatePath.length === bestLength) matches.push(...filtered);
+  }
+  return uniqueNodes(matches);
+}
+
+export function sourceConstraintFromNode(node = {}) {
+  const source = node?.record?.source || {};
+  const adapterId = String(source.adapterId || '').trim().toLowerCase();
+  const sourceId = String(source.id || '').trim();
+  if (adapterId === 'local' || sourceId === 'local' || source.kind === 'local-session') return { hasConstraint: false, sourceId: '', repo: '', ref: '', adapterId: '' };
+  const repo = normalizeRepoKey(source.repo || source.repository || source.config?.repo || '');
+  const ref = normalizeRef(source.ref || source.config?.ref || '');
+  return { hasConstraint: Boolean(sourceId || repo || adapterId), sourceId, repo, ref, adapterId };
+}
+
+export function sourceConstraintFromTarget(repo = '') {
+  const key = normalizeRepoKey(repo);
+  return { hasConstraint: Boolean(key), repo: key, sourceId: '', ref: '', adapterId: 'github' };
+}
+
+function filterBySource(nodes = [], constraint = {}, strictSource = false) {
+  const items = Array.isArray(nodes) ? nodes : [];
+  if (!constraint?.hasConstraint) return items;
+  const filtered = items.filter((node) => nodeMatchesSourceConstraint(node, constraint));
+  if (filtered.length) return filtered;
+  if (strictSource && items.length && items.every((node) => !sourceConstraintFromNode(node).hasConstraint)) return items;
+  return [];
+}
+
+function nodeMatchesSourceConstraint(node = {}, constraint = {}) {
+  const candidate = sourceConstraintFromNode(node);
+  if (constraint.sourceId && candidate.sourceId && constraint.sourceId !== candidate.sourceId) return false;
+  if (constraint.adapterId && candidate.adapterId && constraint.adapterId !== candidate.adapterId) return false;
+  if (constraint.repo && candidate.repo !== constraint.repo) return false;
+  if (constraint.ref && candidate.ref && constraint.ref !== candidate.ref) return false;
+  if (constraint.repo && !candidate.repo) return false;
+  if (constraint.adapterId && !candidate.adapterId) return false;
+  return true;
+}
+
+function uniqueNodes(nodes = []) {
+  const seen = new Set();
+  const out = [];
+  for (const node of Array.isArray(nodes) ? nodes : []) {
+    const key = node?.id || node?.path || JSON.stringify(node || {});
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(node);
+  }
+  return out;
+}