@tiinex/core 0.1.1

package/src/lineage/lineage.githubIssueComment.js

@@ -0,0 +1,106 @@
+import { canonicalPath } from './lineage.targetKeys.js';
+
+export 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 '';
+}
+
+export function githubIssueCommentIdsForNode(node = {}) {
+  const record = node.record || {};
+  const snapshot = record.snapshot || {};
+  const sourceTarget = record.sourceTarget || {};
+  const target = snapshot.target || {};
+  const values = [
+    node.id,
+    node.path,
+    record.id,
+    record.path,
+    record.source?.path,
+    record.sourcePath,
+    record.recoveredFromUrl,
+    record.sourceOrigin,
+    record.rawUrl,
+    record.browseUrl,
+    sourceTarget.inputTarget,
+    sourceTarget.rawUrl,
+    sourceTarget.browseUrl,
+    sourceTarget.sourceArtifactPath,
+    snapshot.sourceUrl,
+    snapshot.sourceArtifactPath,
+    target.canonicalUrl,
+    target.html_url,
+    target.url
+  ];
+  return Array.from(new Set(values.map(githubIssueCommentIdFromValue).filter(Boolean)));
+}
+
+export function filterGitHubIssueCommentCandidatesForTarget(candidates = [], raw = '', declaringNode = null) {
+  const targetIssue = githubIssueContextForValue(raw) || githubIssueContextForNode(declaringNode);
+  const unique = uniqueNodes(candidates || []);
+  if (!targetIssue) return unique;
+  return unique.filter((candidate) => sameGithubIssueContext(githubIssueContextForNode(candidate), targetIssue));
+}
+
+function githubIssueContextForNode(node = {}) {
+  const record = node.record || {};
+  const snapshot = record.snapshot || {};
+  const sourceTarget = record.sourceTarget || {};
+  const target = snapshot.target || {};
+  const values = [node.path, record.path, record.recoveredFromUrl, sourceTarget.inputTarget, sourceTarget.rawUrl, sourceTarget.browseUrl, snapshot.sourceUrl, target.canonicalUrl, target.html_url, target.url];
+  for (const value of values) {
+    const context = githubIssueContextForValue(value);
+    if (context) return context;
+  }
+  if (target.repository && target.number) return { repo: normalizeRepoKey(target.repository), number: String(target.number) };
+  return null;
+}
+
+function githubIssueContextForValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  try {
+    const url = new URL(raw);
+    const host = url.hostname.toLowerCase();
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 4 && parts[2] === 'issues') {
+      const repo = normalizeRepoKey(`${parts[0]}/${parts[1]}`);
+      const number = String(parts[3] || '').trim();
+      if (repo && number) return { repo, number };
+    }
+    if (host === 'api.github.com' && parts.length >= 5 && parts[0] === 'repos' && parts[3] === 'issues') {
+      const repo = normalizeRepoKey(`${parts[1]}/${parts[2]}`);
+      const number = String(parts[4] || '').trim();
+      if (repo && number) return { repo, number };
+    }
+  } catch (_) {}
+  const pathParts = canonicalPath(raw).split('/').filter(Boolean);
+  const dotIssuesIndex = pathParts.findIndex((part) => part.toLowerCase() === '.issues');
+  if (dotIssuesIndex >= 0 && pathParts[dotIssuesIndex + 1]?.toLowerCase() === 'github') {
+    const repo = normalizeSyntheticRepoToken(pathParts[dotIssuesIndex + 2] || '');
+    const number = String(pathParts[dotIssuesIndex + 3] || '').trim();
+    if (repo && /^\d+$/.test(number)) return { repo, number };
+  }
+  const legacyDotGithubIndex = pathParts.findIndex((part, index) => part.toLowerCase() === '.issues' && pathParts[index - 1]?.toLowerCase() === '.github');
+  if (legacyDotGithubIndex >= 0) {
+    const legacy = legacyIssueFolderContext(pathParts[legacyDotGithubIndex + 1] || '');
+    if (legacy) return legacy;
+  }
+  return null;
+}
+
+function sameGithubIssueContext(a = null, b = null) {
+  if (!a || !b) return false;
+  return normalizeRepoKey(a.repo || '') === normalizeRepoKey(b.repo || '') && String(a.number || '') === String(b.number || '');
+}
+
+function normalizeRepoKey(value = '') { const parts = String(value || '').trim().toLowerCase().split('/').filter(Boolean); return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : ''; }
+function normalizeSyntheticRepoToken(value = '') { const parts = String(value || '').trim().toLowerCase().split('-').filter(Boolean); if (parts.length < 2) return ''; const owner = parts.shift(); const repo = parts.join('-'); return owner && repo ? `${owner}/${repo}` : ''; }
+function legacyIssueFolderContext(value = '') { const parts = String(value || '').trim().toLowerCase().split('-').filter(Boolean); const numberIndex = parts.findIndex((part, index) => index >= 2 && /^\d+$/.test(part)); if (numberIndex < 2) return null; const owner = parts[0] || ''; const repoParts = parts.slice(1, numberIndex).filter((part) => part !== 'issue' && part !== 'issues'); const repo = normalizeRepoKey(`${owner}/${repoParts.join('-')}`); const number = parts[numberIndex] || ''; return repo && number ? { repo, number } : null; }
+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; }

package/src/lineage/lineage.githubIssueLocal.js

@@ -0,0 +1,196 @@
+export function issueLocalPathKeysForNode(node = {}) {
+  const issue = githubIssueContextForNode(node);
+  if (!issue) return [];
+  const record = node.record || {};
+  const paths = [node.path, record.path, ...(sourcePathsForNode(node))].map(canonicalPath).filter(Boolean);
+  const keys = [];
+  const add = (item = '') => { const clean = String(item || '').trim().toLowerCase(); if (clean && !keys.includes(clean)) keys.push(clean); };
+  for (const path of paths) {
+    add(issueLocalKey(issue, path));
+    const base = basename(path);
+    if (base && base !== path) add(issueLocalKey(issue, base));
+  }
+  for (const alias of issueLocalAliasesForNode(node)) add(issueLocalKey(issue, alias));
+  return keys;
+}
+
+export function issueLocalPathMatches(target = '', index = {}, declaringNode = null) {
+  const issue = githubIssueContextForNode(declaringNode);
+  if (!issue) return [];
+  const targetPath = canonicalPath(target);
+  if (!targetPath) return [];
+  const keys = [issueLocalKey(issue, targetPath), issueLocalKey(issue, basename(targetPath))].filter(Boolean);
+  const commentId = githubIssueCommentIdFromValue(target);
+  if (commentId) keys.push(issueLocalKey(issue, `comment-id-${commentId}`));
+  const out = [];
+  for (const key of keys) out.push(...(index.byIssueLocalPath?.get(key) || []));
+  return uniqueNodes(out);
+}
+
+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 issueLocalAliasesForNode(node = {}) {
+  const record = node.record || {};
+  const title = String(node.title || record.title || '').trim();
+  const sourceTarget = record.sourceTarget || {};
+  const targetKind = String(sourceTarget.targetKind || record.snapshot?.sourceKind || '').toLowerCase();
+  const recovered = String(record.recoveredFromUrl || sourceTarget.inputTarget || record.snapshot?.sourceUrl || '').trim();
+  const aliases = [];
+  const add = (item = '') => { const clean = canonicalPath(item); if (clean && !aliases.includes(clean)) aliases.push(clean); };
+  const isIssueRoot = githubIssueContextFromValue(recovered) && !/issuecomment-/i.test(recovered) && !targetKind.includes('comment');
+  if (isIssueRoot && title) {
+    const slug = slugPart(title).slice(0, 52) || 'artifact';
+    add(`issue-root-recovered-${slug}.trace.md`);
+    add(`issue-root-recovered-${slug}.workspace.md`);
+  }
+  const commentId = githubIssueCommentIdForNode(node);
+  if (commentId) {
+    add(`comment-id-${commentId}`);
+    if (title) {
+      const slug = slugPart(title).slice(0, 52) || 'artifact';
+      add(`comment-${commentId}-recovered-${slug}.trace.md`);
+      add(`comment-${commentId}-recovered-${slug}.workspace.md`);
+      add(`issuecomment-${commentId}-recovered-${slug}.trace.md`);
+      add(`issuecomment-${commentId}-recovered-${slug}.workspace.md`);
+    }
+  }
+  return aliases;
+}
+
+
+function githubIssueCommentIdForNode(node = {}) {
+  const record = node.record || {};
+  const sourceTarget = record.sourceTarget || {};
+  const snapshot = record.snapshot || {};
+  const target = snapshot.target || {};
+  const candidates = [
+    record.recoveredFromUrl,
+    sourceTarget.inputTarget,
+    sourceTarget.rawUrl,
+    sourceTarget.browseUrl,
+    snapshot.sourceUrl,
+    target.canonicalUrl,
+    target.html_url,
+    target.url,
+    node.path,
+    record.path,
+    record.source?.path,
+    record.sourcePath,
+    sourceTarget.sourceArtifactPath,
+    snapshot.sourceArtifactPath
+  ];
+  for (const candidate of candidates) {
+    const id = githubIssueCommentIdFromValue(candidate);
+    if (id) return id;
+  }
+  return '';
+}
+
+function githubIssueContextForNode(node = {}) {
+  const record = node?.record || {};
+  const snapshot = record.snapshot || {};
+  const target = snapshot.target || {};
+  const sourceTarget = record.sourceTarget || {};
+  const candidates = [node.path, record.path, record.recoveredFromUrl, sourceTarget.inputTarget, sourceTarget.rawUrl, sourceTarget.browseUrl, snapshot.sourceUrl, target.canonicalUrl, target.html_url, target.url];
+  for (const candidate of candidates) {
+    const parsed = githubIssueContextFromValue(candidate);
+    if (parsed) return parsed;
+  }
+  if (target.repository && target.number) return { repo: target.repository, number: target.number };
+  return null;
+}
+
+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 githubIssueContextFromValue(value = '') {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  try {
+    const url = new URL(raw);
+    const parts = url.pathname.split('/').filter(Boolean);
+    const host = url.hostname.toLowerCase();
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 4 && parts[2] === 'issues') {
+      const repo = normalizeRepoKey(`${parts[0]}/${parts[1]}`);
+      const number = String(parts[3] || '').trim();
+      if (repo && number) return { repo, number };
+    }
+    if (host === 'api.github.com' && parts.length >= 5 && parts[0] === 'repos' && parts[3] === 'issues') {
+      const repo = normalizeRepoKey(`${parts[1]}/${parts[2]}`);
+      const number = String(parts[4] || '').trim();
+      if (repo && number) return { repo, number };
+    }
+  } catch (error) {}
+  const pathParts = canonicalPath(raw).split('/').filter(Boolean);
+  const dotIssuesIndex = pathParts.findIndex((part) => part.toLowerCase() === '.issues');
+  if (dotIssuesIndex >= 0 && pathParts[dotIssuesIndex + 1]?.toLowerCase() === 'github') {
+    const repoToken = String(pathParts[dotIssuesIndex + 2] || '').trim();
+    const number = String(pathParts[dotIssuesIndex + 3] || '').trim();
+    const repo = normalizeSyntheticRepoToken(repoToken);
+    if (repo && /^\d+$/.test(number)) return { repo, number };
+  }
+  const legacyDotGithubIndex = pathParts.findIndex((part, index) => part.toLowerCase() === '.issues' && pathParts[index - 1]?.toLowerCase() === '.github');
+  if (legacyDotGithubIndex >= 0) {
+    const legacy = legacyIssueFolderContext(pathParts[legacyDotGithubIndex + 1] || '');
+    if (legacy) return legacy;
+  }
+  const issueIndex = pathParts.findIndex((part) => part.toLowerCase() === 'issues');
+  if (issueIndex >= 2 && pathParts.length > issueIndex + 1) {
+    const repo = normalizeRepoKey(`${pathParts[issueIndex - 2]}/${pathParts[issueIndex - 1]}`);
+    const number = String(pathParts[issueIndex + 1] || '').trim();
+    if (repo && /^\d+$/.test(number)) return { repo, number };
+  }
+  return null;
+}
+
+function issueLocalKey(issue = {}, path = '') {
+  const repo = normalizeRepoKey(issue.repo || '');
+  const number = String(issue.number || '').trim();
+  const clean = canonicalPath(path).toLowerCase();
+  return repo && number && clean ? `github-issue-local:${repo}#${number}:${clean}` : '';
+}
+function basename(path = '') { return canonicalPath(path).split('/').filter(Boolean).pop() || ''; }
+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; }
+function normalizeRepoKey(value = '') { const parts = String(value || '').trim().toLowerCase().split('/').filter(Boolean); return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : ''; }
+function normalizeSyntheticRepoToken(value = '') {
+  const token = String(value || '').trim().toLowerCase();
+  const parts = token.split('-').filter(Boolean);
+  if (parts.length < 2) return '';
+  const owner = parts.shift();
+  const repo = parts.join('-');
+  return owner && repo ? `${owner}/${repo}` : '';
+}
+function legacyIssueFolderContext(value = '') {
+  const token = String(value || '').trim().toLowerCase();
+  const parts = token.split('-').filter(Boolean);
+  const numberIndex = parts.findIndex((part, index) => index >= 2 && /^\d+$/.test(part));
+  if (numberIndex < 2) return null;
+  const owner = parts[0] || '';
+  const repoParts = parts.slice(1, numberIndex).filter((part) => part !== 'issue' && part !== 'issues');
+  const repo = normalizeRepoKey(`${owner}/${repoParts.join('-')}`);
+  const number = parts[numberIndex] || '';
+  return repo && number ? { repo, number } : null;
+}
+function canonicalPath(value = '') {
+  let raw = String(value || '').trim();
+  if (!raw) return '';
+  raw = raw.replace(/^record:/i, '');
+  try { const url = new URL(raw); raw = url.pathname.replace(/^\/+/, ''); } catch (e) {}
+  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 slugPart(value = '') { return String(value || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item'; }

package/src/lineage/lineage.githubIssueTarget.js

@@ -0,0 +1,89 @@
+export function filterExactGitHubIssueCandidatesForTarget(candidates = [], rawTarget = '', declaringNode = null) {
+  const expected = canonicalExactGitHubIssueTarget(rawTarget);
+  if (!expected || expected.commentId) return [];
+  return uniqueNodes(candidates).filter((candidate) => {
+    if (sameLineageNode(candidate, declaringNode)) return false;
+    return exactGitHubIssueProvenanceValuesForNode(candidate).some((value) => {
+      const actual = canonicalExactGitHubIssueTarget(value);
+      return Boolean(actual && !actual.commentId && actual.repo === expected.repo && actual.number === expected.number);
+    });
+  });
+}
+
+function exactGitHubIssueProvenanceValuesForNode(node = {}) {
+  const record = node.record || node || {};
+  const sourceTarget = record.sourceTarget || {};
+  const snapshot = record.snapshot || {};
+  const target = snapshot.target || {};
+  return [
+    record.recoveredFromUrl,
+    record.sourceOrigin,
+    record.rawUrl,
+    record.browseUrl,
+    sourceTarget.inputTarget,
+    sourceTarget.rawUrl,
+    sourceTarget.browseUrl,
+    snapshot.sourceUrl,
+    target.canonicalUrl,
+    target.html_url,
+    target.url
+  ].map((value) => String(value || '').trim()).filter(Boolean);
+}
+
+function canonicalExactGitHubIssueTarget(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const host = url.hostname.toLowerCase();
+    const parts = url.pathname.split('/').filter(Boolean);
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 4 && parts[2] === 'issues') {
+      const repo = `${String(parts[0] || '').toLowerCase()}/${String(parts[1] || '').toLowerCase()}`;
+      const number = String(parts[3] || '').trim();
+      return repo && number ? { repo, number, commentId: githubIssueCommentIdFromValue(value) } : null;
+    }
+    if (host === 'api.github.com' && parts.length >= 5 && parts[0] === 'repos' && parts[3] === 'issues') {
+      const repo = `${String(parts[1] || '').toLowerCase()}/${String(parts[2] || '').toLowerCase()}`;
+      const number = String(parts[4] || '').trim();
+      return repo && number ? { repo, number, commentId: '' } : null;
+    }
+  } catch (_) {}
+  return null;
+}
+
+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 { return new URL(raw).hash.match(/issuecomment-(\d+)/i)?.[1] || ''; } catch (_) { return ''; }
+}
+
+function sameLineageNode(candidate = {}, declaringNode = null) {
+  if (!candidate || !declaringNode) return false;
+  const candidateId = String(candidate.id || '').trim();
+  const declaringId = String(declaringNode.id || '').trim();
+  if (candidateId && declaringId) return candidateId === declaringId;
+  const candidatePath = canonicalPath(candidate.path || candidate.record?.path || '');
+  const declaringPath = canonicalPath(declaringNode.path || declaringNode.record?.path || '');
+  return Boolean(candidatePath && declaringPath && candidatePath === declaringPath);
+}
+
+function canonicalPath(value = '') {
+  const out = [];
+  for (const part of String(value || '').replace(/^record:/i, '').replace(/\\/g, '/').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop(); else out.push(part);
+  }
+  return out.join('/');
+}
+
+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;
+}

package/src/lineage/lineage.integrity.js

@@ -0,0 +1,133 @@
+import { LineageResolutionStatus } from './lineage.model.js';
+import { canonicalPath, canonicalToken, provenanceTargetKeysForValue } from './lineage.targetKeys.js';
+
+export function verifiedIntegrityMatch(match = null) {
+  if (!match || match.ambiguous || match.selfReference || match.blocked) return match;
+  return Object.assign({}, match, {
+    status: LineageResolutionStatus.verified,
+    diagnostics: [lineageDiagnostic('integrity.verified', 'Loaded parent self-integrity matches the child declaration.', { basis: 'checksum' })]
+  });
+}
+
+export function withParentIntegrityStatus(match = null, expectedIntegrityValues = []) {
+  if (!match || !Array.isArray(expectedIntegrityValues) || !expectedIntegrityValues.length) return match;
+  if (match.ambiguous || match.selfReference || match.blocked) return match;
+  if (match.status === LineageResolutionStatus.verified || match.status === LineageResolutionStatus.mismatch || match.status === LineageResolutionStatus.probable) return match;
+  const expected = expectedIntegrityValues.map(canonicalIntegrityValue).filter(Boolean);
+  const actual = selfIntegrityValuesForNode(match);
+  if (!actual.length) {
+    return Object.assign({}, match, {
+      status: LineageResolutionStatus.probable,
+      diagnostics: [lineageDiagnostic('integrity.unavailable', 'Declared parent found, but loaded parent has no self-integrity value to verify against.', { basis: match.method || '' })]
+    });
+  }
+  const matched = expected.some((value) => actual.includes(value));
+  if (matched) {
+    return Object.assign({}, match, {
+      status: LineageResolutionStatus.verified,
+      diagnostics: [lineageDiagnostic('integrity.verified', 'Declared parent found and self-integrity matches the child declaration.', { basis: match.method || '' })]
+    });
+  }
+  return Object.assign({}, match, {
+    status: LineageResolutionStatus.mismatch,
+    diagnostics: [lineageDiagnostic('integrity.mismatch', 'Declared parent found, but loaded parent self-integrity does not match the child declaration.', { basis: match.method || '', expected: expected.join(', '), actual: actual.join(', ') })]
+  });
+}
+
+export function parentIntegrityValuesForTarget(node = {}, target = '') {
+  const targetKeys = lineageTargetComparisonKeys(target);
+  if (!targetKeys.length) return [];
+  const entries = integrityEntriesForNode(node);
+  const values = [];
+  for (const entry of entries) {
+    const towards = String(entry.towards || '').trim();
+    if (!towards || /^self$/i.test(towards)) continue;
+    const entryKeys = lineageTargetComparisonKeys(towards);
+    if (!entryKeys.some((key) => targetKeys.includes(key))) continue;
+    const value = canonicalIntegrityValue(entry.value);
+    if (value) values.push(value);
+  }
+  return Array.from(new Set(values));
+}
+
+export function selfIntegrityValuesForNode(node = {}) {
+  const entries = integrityEntriesForNode(node);
+  return Array.from(new Set(entries
+    .filter((entry) => /^self$/i.test(String(entry.towards || '').trim()))
+    .map((entry) => canonicalIntegrityValue(entry.value))
+    .filter(Boolean)));
+}
+
+function integrityEntriesForNode(node = {}) {
+  const record = node?.record || node || {};
+  const entries = Array.isArray(record.integrity?.entries) ? record.integrity.entries : [];
+  if (entries.length) return entries;
+  return parseIntegrityEntriesFromMarkdown(record.markdown || '');
+}
+
+function parseIntegrityEntriesFromMarkdown(markdown = '') {
+  const text = String(markdown || '');
+  const start = text.search(/^#\s+Continuity Integrity\s*$/im);
+  if (start === -1) return [];
+  const lines = text.slice(start).split('\n');
+  const entries = [];
+  let current = null;
+  const flush = () => {
+    if (!current) return;
+    const method = current.fields.Method || current.label || '';
+    entries.push({
+      method: stripMarkdown(method),
+      towards: normalizeIntegrityField(current.fields.Towards || ''),
+      value: stripMarkdown(current.fields.Value || ''),
+      raw: current.lines.join('\n')
+    });
+    current = null;
+  };
+  for (const line of lines) {
+    const top = line.match(/^-\s+(.+?)\s*$/);
+    if (top) {
+      flush();
+      current = { label: top[1].trim(), fields: {}, lines: [line] };
+      continue;
+    }
+    if (!current) continue;
+    current.lines.push(line);
+    const field = line.match(/^\s+-\s*([A-Za-z][A-Za-z0-9 _+-]{0,40}):\s*(.+?)\s*$/);
+    if (field) current.fields[field[1].trim()] = field[2].trim();
+  }
+  flush();
+  return entries.filter((entry) => entry.method || entry.towards || entry.value);
+}
+
+function lineageTargetComparisonKeys(value = '') {
+  const raw = String(value || '').trim();
+  const keys = [];
+  const add = (item = '') => {
+    const clean = String(item || '').trim().toLowerCase();
+    if (clean && !keys.includes(clean)) keys.push(clean);
+  };
+  add(canonicalToken(raw));
+  add(canonicalPath(raw));
+  for (const key of provenanceTargetKeysForValue(raw)) add(key);
+  return keys.filter(Boolean);
+}
+
+export function canonicalIntegrityValue(value = '') {
+  return String(value || '').trim();
+}
+
+function normalizeIntegrityField(value = '') {
+  const raw = String(value || '').trim();
+  const link = raw.match(/^\[([^\]]*)\]\(([^)]+)\)$/);
+  if (link) return String(link[2] || link[1] || '').trim();
+  return stripMarkdown(raw);
+}
+
+function stripMarkdown(value = '') {
+  return String(value || '').replace(/^\[([^\]]+)\]\([^)]+\)$/, '$1').trim();
+}
+
+function lineageDiagnostic(code, message, extra = {}) {
+  return Object.freeze(Object.assign({ code, message }, extra || {}));
+}
+

package/src/lineage/lineage.materialPreference.js

@@ -0,0 +1,26 @@
+export function preferredLineageMaterialCandidates(nodes = [], method = '') {
+  const unique = uniqueNodes(nodes || []);
+  if (unique.length <= 1) return unique;
+  const text = String(method || '');
+  const publicationIdentity = text.includes('provenance') || text.includes('issue-local') || text.includes('github-comment') || text.includes('github-issue');
+  if (!publicationIdentity) return unique;
+  const embedded = unique.filter((node) => isEmbeddedRecoveredArtifact(node));
+  return embedded.length ? embedded : unique;
+}
+function isEmbeddedRecoveredArtifact(node = {}) {
+  const record = node.record || {};
+  const mode = String(record.sourceMode || node.sourceMode || '').toLowerCase();
+  const kind = String(record.recoveryKind || record.sourceTarget?.targetKind || record.snapshot?.sourceKind || '').toLowerCase();
+  return Boolean(record.snapshot?.embedded || mode.includes('embedded-artifact') || kind.includes('embedded') || kind.includes('recovered'));
+}
+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;
+}

package/src/lineage/lineage.model.js

@@ -0,0 +1,63 @@
+import { schemaIdForRecord } from '../schemas/schema.identity.js';
+
+export const LINEAGE_VIEW_MODEL_SCHEMA_ID = 'tiinex.lineage.view.v1';
+
+export const LineageEdgeKind = Object.freeze({
+  parent: 'parent',
+  origin: 'origin',
+  transition: 'transition'
+});
+
+export const LineageResolutionStatus = Object.freeze({
+  root: 'root',
+  resolved: 'resolved',
+  verified: 'verified',
+  probable: 'probable',
+  mismatch: 'mismatch',
+  ambiguous: 'ambiguous',
+  missing: 'missing',
+  degraded: 'degraded'
+});
+
+export function createLineageNode(record = {}, index = 0) {
+  return {
+    id: record.id || record.path || `lineage-node-${index}`,
+    title: record.title || record.path || 'Untitled artifact',
+    path: record.path || '',
+    schemaId: schemaIdForRecord(record),
+    sourceId: record.source?.id || '',
+    sourceMode: record.sourceMode || '',
+    boundary: record.boundary || record.source?.boundary || '',
+    trace: record.trace || '',
+    origin: record.origin || '',
+    parentSchemaId: record.parentSchemaId || '',
+    hasContinuityContext: Boolean(record.hasContinuityContext),
+    hasIntegrity: Boolean(record.hasIntegrity),
+    record
+  };
+}
+
+export function createLineageEdge(from, to, kind = LineageEdgeKind.parent, input = {}) {
+  return {
+    id: input.id || `${kind}:${from || 'missing'}->${to || 'missing'}`,
+    from: from || '',
+    to: to || '',
+    kind,
+    status: input.status || LineageResolutionStatus.resolved,
+    target: input.target || '',
+    method: input.method || '',
+    label: input.label || kind,
+    diagnostics: input.diagnostics || []
+  };
+}
+
+export function createLineageFinding(code, message, severity = 'warning', input = {}) {
+  return {
+    code,
+    message,
+    severity,
+    nodeId: input.nodeId || '',
+    target: input.target || '',
+    source: 'tiinex.lineage.v1'
+  };
+}

package/src/lineage/lineage.parentAuthority.js

@@ -0,0 +1,5 @@
+import { LineageResolutionStatus } from './lineage.model.js';
+
+export function exactUnloadedParent(recoveryTarget = '', method = 'declared-parent-unloaded') {
+  return { unresolvedExact: true, recoveryTarget: String(recoveryTarget || '').trim(), method, status: LineageResolutionStatus.missing };
+}