@tiinex/core 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.13.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": "7e705cbd611919cc46659f9bcee0cf363a09c41c",
+  "gitHead": "d257bb3ae9e7c6361840d727ce5e359d1b6f6091",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "7e705cbd611919cc46659f9bcee0cf363a09c41c",
-    "sourceTree": "f6b7df8dfa2757bd05cd4d9f764cd0696cc23797",
+    "sourceCommit": "d257bb3ae9e7c6361840d727ce5e359d1b6f6091",
+    "sourceTree": "002c94ff43122ac8188de9514909dfdabd348803",
     "repository": "Tiinex/core",
-    "previousVersion": "0.12.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);

package/src/tooling/portable/adapters/cli/cli.handoff-manufacture.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { prepareNodeHandoffManufacturingInput } from '../node/handoff.manufacture.js';
 import { prepareNodeWorkspaceCarrierManufacturingInput } from '../node/workspaceCarrier.manufacture.js';
+import { prepareNodeBootstrapCarrierManufacturingInput } from '../node/bootstrapCarrier.manufacture.js';
 import { projectHandoffHumanOutput } from '../../handoff/carrierProjection.js';
 import { writePortableRuntimePackageZip } from '../../output/node.zip.js';
 import { writeRecipientFacingV2PackageZip } from '../../output/recipientV2.zip.js';
@@ -16,8 +17,9 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
   const flags = parsed.flags || {};
   const workspaceRoot = flags.workspace || parsed.positionals?.[0] || '.';
   const carrierMode = String(flags['carrier-mode'] || 'handoff').trim().toLowerCase();
-  if (!['handoff', 'workspace'].includes(carrierMode)) throw new Error(`portable.cli.handoff-carrier.carrier-mode.invalid:${carrierMode}`);
+  if (!['handoff', 'workspace', 'bootstrap'].includes(carrierMode)) throw new Error(`portable.cli.handoff-carrier.carrier-mode.invalid:${carrierMode}`);
   if (carrierMode === 'workspace') return prepareWorkspaceCarrierCliCommand(flags, workspaceRoot, runtime);
+  if (carrierMode === 'bootstrap') return prepareBootstrapCarrierCliCommand(flags, runtime);
   const continuationState = parsed.surfaceCommand === 'handoff'
     ? await readGroundContinuationState(workspaceRoot)
     : {};
@@ -146,13 +148,15 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
 }
 
 export async function materializeHandoffManufactureCliOutput(result = {}, flags = {}) {
-  const workspaceMode = String(result.carrierProjection?.mode || '') === 'workspace';
-  let humanOutput = workspaceMode ? projectWorkspaceCarrierHumanOutput(result, flags) : projectHandoffHumanOutput({
+  const carrierMode = String(result.carrierProjection?.mode || '');
+  const workspaceMode = carrierMode === 'workspace';
+  const bootstrapMode = carrierMode === 'bootstrap';
+  let humanOutput = workspaceMode ? projectWorkspaceCarrierHumanOutput(result, flags) : bootstrapMode ? projectBootstrapCarrierHumanOutput(result, flags) : projectHandoffHumanOutput({
     projection: result.carrierProjection || {},
     route: flags.route || '',
     collisionInstance: flags['collision-instance'] || 1
   });
-  if (!workspaceMode && result.bundle?.transportFormat) humanOutput = projectRecipientV2HumanOutput(humanOutput, result.inspection || {});
+  if (result.bundle?.transportFormat) humanOutput = projectRecipientV2HumanOutput(humanOutput, result.inspection || {});
   const wantsWrite = Boolean(flags.output || flags['output-dir']);
   const blocked = result.status === 'blocked' || result.transportExecutable === false || Number(result.findingSummary?.counts?.error || 0) > 0;
   if (!wantsWrite || blocked) return summarizeHandoffManufactureCliOutput(result, {}, humanOutput, null);
@@ -163,7 +167,6 @@ export async function materializeHandoffManufactureCliOutput(result = {}, flags
   const writeReceipt = writeBundle?.transportFormat
     ? await writeRecipientFacingV2PackageZip(writeBundle, target, writeBundle === result.bundle ? { inspection: result.inspection } : {})
     : await writePortableRuntimePackageZip(writeBundle, target);
-  if (workspaceMode && flags['transport-text']) throw new Error('portable.cli.workspace-carrier.transport-text.unavailable');
   const transportTextReceipt = flags['transport-text'] ? await writeTransportTextSidecar(humanOutput, target, flags['transport-text']) : null;
   return summarizeHandoffManufactureCliOutput(result, writeReceipt, humanOutput, transportTextReceipt);
 }
@@ -174,6 +177,7 @@ async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.'
   const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
   const workspaceDescriptorValue = await readOptionalJson(flags['workspace-roots'] || flags['workspace-descriptors']);
   const workspaceTargetValue = await readOptionalJson(flags['workspace-targets']);
+  const workspaceScopeValue = await readOptionalJson(flags['workspace-scopes']);
   const additionalWorkspaces = [...splitFlag(flags['additional-workspaces']), ...descriptorArray(workspaceDescriptorValue, 'workspaces')];
   const verifyRoundtrip = !flags['no-roundtrip'];
   const carrierProfile = selectCarrierProfile({ operator: operatorCarrierProfile, runtime: runtime.defaultCarrierProfile || null });
@@ -185,6 +189,8 @@ async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.'
     workspaceTitle: flags['workspace-title'] || flags.title || '',
     workspaceTargetPath: flags['workspace-target'] || flags['workspace-artifact'] || '',
     workspaceTargets: workspaceTargetValue,
+    workspaceScopes: descriptorArray(workspaceScopeValue, 'scopes').length ? descriptorArray(workspaceScopeValue, 'scopes') : workspaceScopeValue,
+    materialRepresentationWorkspaceIds: splitFlag(flags['material-representation-workspaces'] || flags['generic-material-workspaces']),
     toolingBootstrap: flags['tooling-bootstrap'] || 'embedded',
     expectedToolingBootstrap,
     maxFiles: flags['max-files'],
@@ -198,6 +204,37 @@ async function prepareWorkspaceCarrierCliCommand(flags = {}, workspaceRoot = '.'
   return { input, options: { verifyRoundtrip, packageInput: { builtAt: flags['built-at'] || undefined } } };
 }
 
+async function prepareBootstrapCarrierCliCommand(flags = {}, runtime = {}) {
+  if (flags.handoff || flags.route || flags.routes || flags['handoff-routes'] || flags['workspace-routes'] || flags.workspace || flags['workspace-target'] || flags['workspace-targets'] || flags['workspace-roots'] || flags['workspace-descriptors']) throw new Error('portable.cli.bootstrap-carrier.source-material-or-route.forbidden');
+  const operatorCarrierProfile = await readOptionalJson(flags['carrier-profile']);
+  const expectedToolingBootstrap = await readOptionalJson(flags['tooling-bootstrap-manifest']);
+  const verifyRoundtrip = !flags['no-roundtrip'];
+  const carrierProfile = selectCarrierProfile({ operator: operatorCarrierProfile, runtime: runtime.defaultCarrierProfile || null });
+  const input = await prepareNodeBootstrapCarrierManufacturingInput({
+    toolingBootstrap: flags['tooling-bootstrap'] || 'embedded', expectedToolingBootstrap, bootstrapMaxFiles: flags['bootstrap-max-files'], verifyRoundtrip, createdAt: flags['built-at'] || undefined,
+    carrierLineage: Object.freeze({ ...initialHandoffCarrierLineage(), checkpointKind: 'progression', majorReason: '' }), carrierProfile
+  }, runtime);
+  return { input, options: { verifyRoundtrip, packageInput: { builtAt: flags['built-at'] || undefined } } };
+}
+
+function projectBootstrapCarrierHumanOutput(result = {}, flags = {}) {
+  const projection = result.carrierProjection || {};
+  const ready = result.status === 'ready' && projection.status === 'ready' && projection.mode === 'bootstrap' && (projection.routes || []).length === 0 && (projection.workspaces || []).length === 0;
+  const dimension = String(projection.lineage?.dimension || '001');
+  const projectedFilename = String(flags['projected-filename'] || flags.projectedFilename || '').trim();
+  const filename = projectedFilename || `tiinex-${dimension}.handoff-package.zip`;
+  if (filename !== filename.trim() || !filename.endsWith('.handoff-package.zip') || /[<>:"/\\|?*\x00-\x1f\x7f]/.test(filename) || /[. ]$/.test(filename) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(filename) || new TextEncoder().encode(filename).byteLength > 255) throw new Error('portable.cli.bootstrap-carrier.filename.invalid');
+  return Object.freeze({
+    schema: 'tiinex.portable.handoff-human-output.v1', status: ready ? 'ready' : 'blocked',
+    primary: ready ? Object.freeze({ kind: 'bootstrap-package', filename, dimension, parentDimension: String(projection.lineage?.parentDimension || ''), checkpointKind: String(projection.lineage?.checkpointKind || ''), routeId: '', workspaceId: '', workspaceRelativeHandoffPath: '', collisionInstance: 1, singleHumanTransportChoice: true }) : null,
+    normalInlineRouting: ready ? Object.freeze({ kind: 'transport-text', content: '', normalEmission: true, requiredForHumanCompletion: true, placement: 'adjacent-to-primary', authority: 'none' }) : null, sharedRouting: null,
+    presentation: Object.freeze({ kind: 'bootstrap-only-carrier', label: 'Bootstrap carrier', authority: 'none', recipientLabel: '' }),
+    normalEmissionBoundary: Object.freeze({ allowed: Object.freeze(['package-file', 'generic-start-transport-text']), forbidden: Object.freeze(['workspace-label', 'route-specific-continue-from', 'recipient-label', 'holder-label', 'current-work-label']) }),
+    fallbackTransportText: ready ? Object.freeze({ supported: true, filename: filename.replace(/\.handoff-package\.zip$/i, '.transport.txt'), content: '', normalEmission: false, requiredForHumanCompletion: false, authority: 'none' }) : null, selectedRoute: null, findings: Object.freeze([]),
+    boundary: 'Bootstrap-only carrier output projection. Generic Start transport text only; no Workspace, Handoff route, recipient, holder, Role, or work projection exists.'
+  });
+}
+
 function projectWorkspaceCarrierHumanOutput(result = {}, flags = {}) {
   const projection = result.carrierProjection || {};
   const ready = result.status === 'ready' && projection.status === 'ready' && projection.mode === 'workspace' && (projection.routes || []).length === 0;
@@ -213,11 +250,11 @@ function projectWorkspaceCarrierHumanOutput(result = {}, flags = {}) {
     schema: 'tiinex.portable.handoff-human-output.v1',
     status: ready ? 'ready' : 'blocked',
     primary: ready ? Object.freeze({ kind: 'workspace-package', filename, dimension, parentDimension: String(projection.lineage?.parentDimension || ''), checkpointKind: String(projection.lineage?.checkpointKind || ''), routeId: '', workspaceId: '', workspaceRelativeHandoffPath: '', collisionInstance: 1, singleHumanTransportChoice: true }) : null,
-    normalInlineRouting: null, sharedRouting: null,
-    presentation: Object.freeze({ kind: 'pointerless-workspace-carrier', label: 'Workspace carrier', authority: 'none' }),
-    normalEmissionBoundary: Object.freeze({ allowed: Object.freeze(['package-file']), forbidden: Object.freeze(['handoff-routing-text', 'continue-from-pointer']) }),
-    fallbackTransportText: null, selectedRoute: null, findings: Object.freeze([]),
-    boundary: 'Pointerless Workspace-carrier output projection only. No Handoff routing text exists because the package role declares no Handoff route.'
+    normalInlineRouting: ready ? Object.freeze({ kind: 'transport-text', content: '', normalEmission: true, requiredForHumanCompletion: true, placement: 'adjacent-to-primary', authority: 'none' }) : null, sharedRouting: null,
+    presentation: Object.freeze({ kind: 'pointerless-workspace-carrier', label: 'Workspace carrier', authority: 'none', recipientLabel: '' }),
+    normalEmissionBoundary: Object.freeze({ allowed: Object.freeze(['package-file', 'generic-start-transport-text']), forbidden: Object.freeze(['route-specific-continue-from', 'recipient-label-from-material']) }),
+    fallbackTransportText: ready ? Object.freeze({ supported: true, filename: filename.replace(/\.handoff-package\.zip$/i, '.transport.txt'), content: '', normalEmission: false, requiredForHumanCompletion: false, authority: 'none' }) : null, selectedRoute: null, findings: Object.freeze([]),
+    boundary: 'Pointerless Workspace-carrier output projection. Generic Start transport text is permitted; Handoff Continue-from and recipient projection remain absent.'
   });
 }
 

package/src/tooling/portable/adapters/node/bootstrapCarrier.manufacture.js

@@ -0,0 +1,18 @@
+import { buildToolingBootstrapTransportFiles } from './handoff.manufacture.bootstrap.js';
+import { normalizeHandoffCarrierLineage } from '../../handoff/carrierLineage.js';
+import { normalizeHandoffCarrierProfile } from '../../handoff/carrierProfile.js';
+
+export async function prepareNodeBootstrapCarrierManufacturingInput(input = {}, options = {}) {
+  const toolingBootstrap = await buildToolingBootstrapTransportFiles({
+    delivery: input.toolingBootstrap || input.bootstrapDelivery || 'embedded',
+    runtimeRoot: input.runtimeRoot || options.runtimeRoot,
+    expected: input.expectedToolingBootstrap || null,
+    maxFiles: input.bootstrapMaxFiles || options.bootstrapMaxFiles
+  });
+  return Object.freeze({
+    carrierMode: 'bootstrap', createdAt: String(input.createdAt || ''), workspaceMaterializations: Object.freeze([]), workspaceTargets: Object.freeze([]),
+    additionalTransportFiles: toolingBootstrap.files,
+    carrierLineage: normalizeHandoffCarrierLineage(input.carrierLineage || null), carrierProfile: normalizeHandoffCarrierProfile(input.carrierProfile || null),
+    toolingBootstrap: toolingBootstrap.summary, manufacturingEvidence: Object.freeze({ toolingBootstrap: toolingBootstrap.summary }), verifyRoundtrip: input.verifyRoundtrip !== false
+  });
+}