@tiinex/core 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -168,12 +168,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "030669b6596196da946edb049d15af044bcd96c6",
+  "gitHead": "d257bb3ae9e7c6361840d727ce5e359d1b6f6091",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "030669b6596196da946edb049d15af044bcd96c6",
-    "sourceTree": "090aaead28df51b2aeb6679018526f54260a1ca8",
+    "sourceCommit": "d257bb3ae9e7c6361840d727ce5e359d1b6f6091",
+    "sourceTree": "002c94ff43122ac8188de9514909dfdabd348803",
     "repository": "Tiinex/core",
-    "previousVersion": "0.13.0"
+    "previousVersion": "0.14.0"
   }
 }

package/src/integrity/integrity.c14nV1.js

@@ -0,0 +1,28 @@
+import { sha256Base64Url } from './integrity.c14nV2.js';
+
+export const C14N_V1_METHOD_ID = 'sha256-base64url-c14n-v1';
+
+export function canonicalC14nV1TargetState(markdown = '') {
+  const normalized = normalizeCanonicalSource(markdown);
+  const lines = normalized.split('\n');
+  const integrityHeading = lines.findIndex((line) => line.trim() === '# Continuity Integrity');
+  const canonical = (integrityHeading < 0 ? lines : lines.slice(0, integrityHeading)).join('\n');
+  return Object.freeze({
+    state: 'computed',
+    method: C14N_V1_METHOD_ID,
+    canonical,
+    computedValue: sha256Base64Url(canonical),
+    integrityHeading
+  });
+}
+
+export function c14nV1TargetDigest(markdown = '') {
+  return canonicalC14nV1TargetState(markdown).computedValue;
+}
+
+function normalizeCanonicalSource(markdown = '') {
+  return String(markdown || '')
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t]+$/gm, '')
+    .trimEnd();
+}

package/src/lineage/lineage.integrity.js

@@ -1,3 +1,5 @@
+import { C14N_V1_METHOD_ID, c14nV1TargetDigest } from '../integrity/integrity.c14nV1.js';
+import { C14N_V2_METHOD_ID } from '../integrity/integrity.c14nV2.js';
 import { LineageResolutionStatus } from './lineage.model.js';
 import { canonicalPath, canonicalToken, provenanceTargetKeysForValue } from './lineage.targetKeys.js';
 
@@ -5,57 +7,138 @@ 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' })]
+    diagnostics: [lineageDiagnostic('integrity.verified', 'Loaded parent integrity matches the child declaration.', { basis: 'checksum' })]
   });
 }
 
-export function withParentIntegrityStatus(match = null, expectedIntegrityValues = []) {
-  if (!match || !Array.isArray(expectedIntegrityValues) || !expectedIntegrityValues.length) return match;
+export function withParentIntegrityStatus(match = null, expectedIntegrity = []) {
+  if (!match || !Array.isArray(expectedIntegrity) || !expectedIntegrity.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) {
+  const expectations = normalizeIntegrityExpectations(expectedIntegrity);
+  if (!expectations.length) return match;
+  const checks = expectations.map((expectation) => verifyParentIntegrityExpectation(match, expectation));
+  const verified = checks.find((check) => check.state === 'verified');
+  if (verified) {
     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 || '' })]
+      status: LineageResolutionStatus.verified,
+      diagnostics: [lineageDiagnostic('integrity.verified', verified.message, { basis: verified.basis, method: verified.method, expected: verified.expected, actual: verified.actual })]
     });
   }
-  const matched = expected.some((value) => actual.includes(value));
-  if (matched) {
+  const comparable = checks.filter((check) => check.state === 'mismatch');
+  if (!comparable.length) {
     return Object.assign({}, match, {
-      status: LineageResolutionStatus.verified,
-      diagnostics: [lineageDiagnostic('integrity.verified', 'Declared parent found and self-integrity matches the child declaration.', { basis: match.method || '' })]
+      status: LineageResolutionStatus.probable,
+      diagnostics: [lineageDiagnostic('integrity.unavailable', 'Declared parent found, but the loaded parent does not expose the method-specific material required to verify the child declaration.', { basis: match.method || '', methods: expectations.map((item) => item.method).filter(Boolean).join(', ') })]
     });
   }
   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(', ') })]
+    diagnostics: comparable.map((check) => lineageDiagnostic('integrity.mismatch', check.message, { basis: check.basis, method: check.method, expected: check.expected, actual: check.actual }))
   });
 }
 
-export function parentIntegrityValuesForTarget(node = {}, target = '') {
+export function parentIntegrityExpectationsForTarget(node = {}, target = '') {
   const targetKeys = lineageTargetComparisonKeys(target);
   if (!targetKeys.length) return [];
   const entries = integrityEntriesForNode(node);
-  const values = [];
+  const expectations = [];
   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);
+    if (!value) continue;
+    expectations.push(Object.freeze({ method: canonicalIntegrityMethod(entry.method || entry.declaredMethod || ''), value, towards }));
   }
-  return Array.from(new Set(values));
+  return dedupeExpectations(expectations);
+}
+
+export function parentIntegrityValuesForTarget(node = {}, target = '') {
+  return parentIntegrityExpectationsForTarget(node, target).map((entry) => entry.value);
 }
 
 export function selfIntegrityValuesForNode(node = {}) {
-  const entries = integrityEntriesForNode(node);
-  return Array.from(new Set(entries
+  return Array.from(new Set(selfIntegrityEntriesForNode(node).map((entry) => canonicalIntegrityValue(entry.value)).filter(Boolean)));
+}
+
+export function selfIntegrityEntriesForNode(node = {}) {
+  return integrityEntriesForNode(node)
     .filter((entry) => /^self$/i.test(String(entry.towards || '').trim()))
-    .map((entry) => canonicalIntegrityValue(entry.value))
-    .filter(Boolean)));
+    .map((entry) => Object.freeze({
+      method: canonicalIntegrityMethod(entry.method || entry.declaredMethod || ''),
+      value: canonicalIntegrityValue(entry.value),
+      towards: 'self'
+    }))
+    .filter((entry) => entry.value);
+}
+
+function verifyParentIntegrityExpectation(match = {}, expectation = {}) {
+  const method = canonicalIntegrityMethod(expectation.method || '');
+  const expected = canonicalIntegrityValue(expectation.value);
+  if (!expected) return unavailableCheck(method, expected, 'integrity-value-missing');
+  const markdown = String(match?.record?.markdown || match?.markdown || '');
+  if (method === C14N_V1_METHOD_ID) {
+    if (!markdown) return unavailableCheck(method, expected, 'target-markdown-unavailable');
+    const actual = c14nV1TargetDigest(markdown);
+    return Object.freeze({
+      state: actual === expected ? 'verified' : 'mismatch',
+      method,
+      expected,
+      actual,
+      basis: C14N_V1_METHOD_ID,
+      message: actual === expected
+        ? 'Declared parent found and direct c14n-v1 canonicalization of the resolved target matches the child declaration.'
+        : 'Declared parent found, but direct c14n-v1 canonicalization of the resolved target does not match the child declaration.'
+    });
+  }
+
+  const selfEntries = selfIntegrityEntriesForNode(match);
+  const comparableEntries = method ? selfEntries.filter((entry) => entry.method === method) : selfEntries;
+  const actualValues = Array.from(new Set(comparableEntries.map((entry) => entry.value).filter(Boolean)));
+  if (!actualValues.length) return unavailableCheck(method, expected, 'target-self-integrity-unavailable');
+  const matched = actualValues.includes(expected);
+  return Object.freeze({
+    state: matched ? 'verified' : 'mismatch',
+    method,
+    expected,
+    actual: actualValues.join(', '),
+    basis: method || match.method || 'target-self-integrity',
+    message: matched
+      ? 'Declared parent found and method-compatible target self-integrity matches the child declaration.'
+      : 'Declared parent found, but method-compatible target self-integrity does not match the child declaration.'
+  });
+}
+
+function unavailableCheck(method = '', expected = '', reason = '') {
+  return Object.freeze({ state: 'unavailable', method, expected, actual: '', basis: method || reason, reason, message: 'Method-specific target integrity material is unavailable.' });
+}
+
+function normalizeIntegrityExpectations(values = []) {
+  const out = [];
+  for (const item of values) {
+    if (item && typeof item === 'object') {
+      const value = canonicalIntegrityValue(item.value);
+      if (value) out.push(Object.freeze({ method: canonicalIntegrityMethod(item.method || item.declaredMethod || ''), value, towards: String(item.towards || '') }));
+      continue;
+    }
+    const value = canonicalIntegrityValue(item);
+    if (value) out.push(Object.freeze({ method: '', value, towards: '' }));
+  }
+  return dedupeExpectations(out);
+}
+
+function dedupeExpectations(entries = []) {
+  const seen = new Set();
+  const out = [];
+  for (const entry of entries) {
+    const key = `${entry.method}\u0000${entry.value}\u0000${entry.towards}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(entry);
+  }
+  return out;
 }
 
 function integrityEntriesForNode(node = {}) {
@@ -116,6 +199,10 @@ export function canonicalIntegrityValue(value = '') {
   return String(value || '').trim();
 }
 
+export function canonicalIntegrityMethod(value = '') {
+  return stripMarkdown(String(value || '').trim()).toLowerCase();
+}
+
 function normalizeIntegrityField(value = '') {
   const raw = String(value || '').trim();
   const link = raw.match(/^\[([^\]]*)\]\(([^)]+)\)$/);
@@ -130,4 +217,3 @@ function stripMarkdown(value = '') {
 function lineageDiagnostic(code, message, extra = {}) {
   return Object.freeze(Object.assign({ code, message }, extra || {}));
 }
-

package/src/lineage/lineage.resolve.js

@@ -3,7 +3,7 @@ import { issueLocalPathKeysForNode, issueLocalPathMatches } from './lineage.gith
 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 { canonicalIntegrityValue, parentIntegrityExpectationsForTarget, parentIntegrityValuesForTarget, selfIntegrityValuesForNode, 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';
@@ -22,7 +22,7 @@ export function resolveLineage(artifacts = [], options = {}) {
     }
     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 parentMatch = traceTarget ? resolveTarget(traceTarget.value, index, node, { expectedIntegrityValues: traceTarget.integrityValues, expectedIntegrity: traceTarget.integrityExpectations, 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 }));
@@ -170,7 +170,10 @@ export function resolveLineage(artifacts = [], options = {}) {
 }
 function declaredTargetsFor(node = {}) {
   const targets = [];
-  if (node.trace) targets.push({ kind: LineageEdgeKind.parent, value: node.trace, integrityValues: parentIntegrityValuesForTarget(node, node.trace) });
+  if (node.trace) {
+    const integrityExpectations = parentIntegrityExpectationsForTarget(node, node.trace);
+    targets.push({ kind: LineageEdgeKind.parent, value: node.trace, integrityExpectations, integrityValues: integrityExpectations.length ? integrityExpectations.map((entry) => entry.value) : parentIntegrityValuesForTarget(node, node.trace) });
+  }
   if (node.origin) targets.push({ kind: LineageEdgeKind.origin, value: node.origin });
   return targets;
 }
@@ -228,23 +231,27 @@ 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 expectedIntegrity = Array.isArray(options.expectedIntegrity) && options.expectedIntegrity.length
+    ? options.expectedIntegrity
+    : Array.isArray(options.expectedIntegrityValues) ? options.expectedIntegrityValues : [];
+  const expectedIntegrityValues = expectedIntegrity.map((entry) => canonicalIntegrityValue(entry && typeof entry === 'object' ? entry.value : entry)).filter(Boolean);
   const token = canonicalToken(raw);
   const path = canonicalPath(raw);
   const urlFilePath = githubRepoRelativePathFromUrl(raw);
   const urlSourceKey = sourceKeyFromTarget(raw);
+  const targetSourceConstraint = urlSourceKey ? sourceConstraintFromTarget(raw) : null;
+  if (expectedIntegrityValues.length && !targetSourceConstraint?.ref) {
+    const integrityMatch = resolveIntegrityTarget(expectedIntegrityValues, index, declaringNode);
+    if (integrityMatch) return withParentIntegrityStatus(integrityMatch, expectedIntegrity);
+  }
+
   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 finalize = (match) => withParentIntegrityStatus(match, expectedIntegrity);
 
   const resolveDirectToken = () => {
     const directTokenCandidates = [
@@ -297,7 +304,7 @@ function resolveTarget(target, index, declaringNode = null, options = {}) {
         continue;
       }
       const sourceKey = sourceKeyFromTarget(binding.raw);
-      const constraint = sourceKey ? sourceConstraintFromTarget(sourceKey) : declaringConstraint;
+      const constraint = sourceKey ? sourceConstraintFromTarget(binding.raw) : declaringConstraint;
       const exact = exactPathMatches(binding.filePath, index, constraint, Boolean(constraint.hasConstraint));
       const resolvedExact = resolveCandidateNodes(exact, 'declared-parent-path', declaringNode);
       if (resolvedExact) return finalize(resolvedExact);
@@ -357,12 +364,12 @@ function resolveTarget(target, index, declaringNode = null, options = {}) {
   const direct = resolveDirectToken();
   if (direct) return finalize(direct);
 
-  const pathConstraint = urlSourceKey ? sourceConstraintFromTarget(urlSourceKey) : declaringConstraint;
+  const pathConstraint = targetSourceConstraint || 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 suffixConstraint = targetSourceConstraint || declaringConstraint;
   const suffixCandidates = [
     ['path-suffix', findPathSuffixMatches(path, index.byPath, suffixConstraint, Boolean(urlSourceKey))],
     ['source-path-suffix', findPathSuffixMatches(path, index.bySourcePath, suffixConstraint, Boolean(urlSourceKey))]
@@ -384,5 +391,5 @@ function resolveIntegrityTarget(expectedIntegrityValues = [], index = {}, declar
   }
   const resolved = resolveCandidateNodes(nodes, 'integrity-self-hash', declaringNode);
   if (!resolved || resolved.ambiguous || resolved.selfReference || resolved.blocked) return resolved;
-  return verifiedIntegrityMatch(resolved);
+  return resolved;
 }

package/src/lineage/lineage.sourceScope.js

@@ -1,4 +1,4 @@
-import { canonicalPath, normalizeRef, normalizeRepoKey } from './lineage.targetKeys.js';
+import { canonicalPath, githubFileIdentityFromUrl, normalizeRef, normalizeRepoKey } from './lineage.targetKeys.js';
 
 export function exactPathMatches(path, index, constraint = {}, strictSource = false) {
   const source = [
@@ -27,18 +27,47 @@ export function findPathSuffixMatches(targetPath, pathIndex = new Map(), constra
 }
 
 export function sourceConstraintFromNode(node = {}) {
-  const source = node?.record?.source || {};
-  const adapterId = String(source.adapterId || '').trim().toLowerCase();
+  const record = node?.record || node || {};
+  const source = record.source || {};
+  const provenance = sourceIdentityFromRecord(record);
   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 };
+  const adapterId = String(source.adapterId || source.adapter || provenance.adapterId || '').trim().toLowerCase();
+  const repo = normalizeRepoKey(source.repo || source.repository || source.config?.repo || provenance.repo || '');
+  const ref = normalizeRef(source.commit || source.ref || source.config?.commit || source.config?.ref || provenance.ref || '');
+  const isLocal = adapterId === 'local' || sourceId === 'local' || source.kind === 'local-session';
+  if (isLocal && !repo && !ref) return { hasConstraint: false, sourceId: '', repo: '', ref: '', adapterId: '', exactRef: false };
+  return { hasConstraint: Boolean(sourceId || repo || adapterId || ref), sourceId, repo, ref, adapterId, exactRef: Boolean(ref) };
 }
 
-export function sourceConstraintFromTarget(repo = '') {
-  const key = normalizeRepoKey(repo);
-  return { hasConstraint: Boolean(key), repo: key, sourceId: '', ref: '', adapterId: 'github' };
+export function sourceConstraintFromTarget(value = '') {
+  const identity = githubFileIdentityFromUrl(value);
+  if (identity.repo) return { hasConstraint: true, repo: identity.repo, ref: identity.ref, sourceId: '', adapterId: 'github', exactRef: Boolean(identity.ref) };
+  const key = normalizeRepoKey(value);
+  return { hasConstraint: Boolean(key), repo: key, ref: '', sourceId: '', adapterId: key ? 'github' : '', exactRef: false };
+}
+
+function sourceIdentityFromRecord(record = {}) {
+  const sourceTarget = record.sourceTarget || {};
+  const snapshot = record.snapshot || {};
+  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
+  ];
+  for (const value of values) {
+    const identity = githubFileIdentityFromUrl(value);
+    if (identity.repo) return { ...identity, adapterId: 'github' };
+  }
+  return { repo: '', ref: '', path: '', adapterId: '' };
 }
 
 function filterBySource(nodes = [], constraint = {}, strictSource = false) {
@@ -46,7 +75,7 @@ function filterBySource(nodes = [], constraint = {}, strictSource = false) {
   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;
+  if (strictSource && !constraint.ref && items.length && items.every((node) => !sourceConstraintFromNode(node).hasConstraint)) return items;
   return [];
 }
 
@@ -55,7 +84,7 @@ function nodeMatchesSourceConstraint(node = {}, constraint = {}) {
   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.ref && candidate.ref !== constraint.ref) return false;
   if (constraint.repo && !candidate.repo) return false;
   if (constraint.adapterId && !candidate.adapterId) return false;
   return true;

package/src/lineage/lineage.targetKeys.js

@@ -31,14 +31,29 @@ export function provenanceTargetKeysForValue(value = '') {
   }
   return keys;
 }
-export function githubRepoRelativePathFromUrl(value = '') {
-  try { const u = new URL(String(value || '').trim()), p = u.pathname.split('/').filter(Boolean), h = u.hostname.toLowerCase();
-    if (h === 'raw.githubusercontent.com' && p.length >= 4) return p.slice(3).join('/');
-    if ((h === 'github.com' || h.endsWith('.github.com')) && p.length >= 5 && p[2] === 'blob') return p.slice(4).join('/');
+
+export function githubFileIdentityFromUrl(value = '') {
+  try {
+    const url = new URL(String(value || '').trim());
+    const host = url.hostname.toLowerCase();
+    const parts = url.pathname.split('/').filter(Boolean);
+    if (host === 'raw.githubusercontent.com' && parts.length >= 4) {
+      return Object.freeze({ repo: normalizeRepoKey(`${parts[0]}/${parts[1]}`), ref: normalizeRef(parts[2]), path: normalizePathParts(parts.slice(3)) });
+    }
+    if ((host === 'github.com' || host.endsWith('.github.com')) && parts.length >= 5 && parts[2] === 'blob') {
+      return Object.freeze({ repo: normalizeRepoKey(`${parts[0]}/${parts[1]}`), ref: normalizeRef(parts[3]), path: normalizePathParts(parts.slice(4)) });
+    }
   } catch (_) {}
-  return '';
+  return Object.freeze({ repo: '', ref: '', path: '' });
 }
+
+export function githubRepoRelativePathFromUrl(value = '') {
+  return githubFileIdentityFromUrl(value).path;
+}
+
 export function sourceKeyFromTarget(value = '') {
+  const identity = githubFileIdentityFromUrl(value);
+  if (identity.repo) return identity.repo;
   try {
     const url = new URL(String(value || ''));
     const parts = url.pathname.split('/').filter(Boolean);
@@ -53,7 +68,7 @@ export function normalizeRepoKey(value = '') {
   return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : '';
 }
 export function normalizeRef(value = '') {
-  return String(value || '').trim().toLowerCase();
+  return String(value || '').trim();
 }
 export function canonicalToken(value = '') {
   return String(value || '').trim().replace(/^record:/i, 'record:').replace(/\s+/g, '');
@@ -70,8 +85,12 @@ export function canonicalPath(value = '') {
       raw = url.pathname.replace(/^\/+/, '');
     } catch (e) {}
   }
+  return normalizePathParts(raw.replace(/\\/g, '/').split('/'));
+}
+
+function normalizePathParts(parts = []) {
   const out = [];
-  for (const part of raw.replace(/\\/g, '/').split('/')) {
+  for (const part of parts) {
     if (!part || part === '.') continue;
     if (part === '..') out.pop();
     else out.push(part);