@tiinex/core 0.1.1

package/src/tooling/portable/package/schema.transition.companion.js

@@ -0,0 +1,196 @@
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { projectPortableContractInstance } from '../schema/contract.project.js';
+import { extractQualifiedMarkdownLinkTarget, portableFieldDomainOccurrenceQualification } from './material.graph.js';
+
+export const PORTABLE_SCHEMA_TRANSITION_COMPANION_SCHEMA_ID = 'tiinex.portable.schema-transition-companion.v1';
+
+export function compilePortableSchemaTransitionCompanion(input = {}) {
+  const material = input.material || {};
+  const compiledContract = input.compiledContract;
+  const findings = [];
+  if (!compiledContract) {
+    findings.push(portableFinding('error', 'portable.companion.contract.missing', 'Schema Transition Companion compilation requires a compiled canonical contract chain.', { ref: material.path || material.representationKey || '' }));
+    return companionResult(material, null, null, [], findings);
+  }
+
+  const projection = projectPortableContractInstance({
+    markdown: material.markdown || '',
+    compiledContract,
+    resolvers: input.resolvers || {}
+  });
+  findings.push(...projection.validation.findings);
+
+  const schemaReference = ordinaryFieldValue(projection, 'Schema Binding', 'Schema Reference');
+  const rawSchemaBinding = resolveQualifiedReference({
+    projection,
+    group: 'Schema Binding',
+    field: 'Schema Reference',
+    value: schemaReference,
+    resolve: input.resolveSchemaReference,
+    material,
+    entry: ''
+  });
+  const schemaBinding = Object.freeze({
+    ...rawSchemaBinding,
+    representationKey: String(rawSchemaBinding.material?.representationKey || ''),
+    schemaId: String(rawSchemaBinding.material?.schemaId || ''),
+    path: String(rawSchemaBinding.material?.path || '')
+  });
+  if (schemaBinding.finding) findings.push(schemaBinding.finding);
+
+  const attachmentGroup = declarationGroup(projection.validation.declarations, 'Transition Attachment Declaration');
+  const entries = attachmentGroup?.sections?.flatMap((section) => section.present ? section.entries : []) || [];
+  const noneEntries = entries.filter((entry) => entry.name === 'none');
+  const explicitEmpty = noneEntries.length === 1 && entries.length === 1;
+  const attachments = [];
+  const seenRepresentationKeys = new Set();
+
+  if (noneEntries.length && !explicitEmpty) {
+    findings.push(portableFinding('error', 'portable.companion.attachments.none.invalid', 'Literal none must be the sole Transition Attachments entry.', { ref: material.path || '' }));
+  }
+
+  for (const entry of entries) {
+    if (entry.name === 'none') continue;
+    const reference = String(entry.fields?.['Transition Reference'] || '');
+    const resolution = resolveQualifiedReference({
+      projection,
+      group: 'Transition Attachment Declaration',
+      field: 'Transition Reference',
+      value: reference,
+      resolve: input.resolveTransitionReference,
+      material,
+      entry: entry.name
+    });
+    if (resolution.finding) findings.push(resolution.finding);
+    const targetKey = String(resolution.material?.representationKey || '');
+    let duplicate = false;
+    if (resolution.qualification === 'resolved' && targetKey) {
+      if (seenRepresentationKeys.has(targetKey)) {
+        duplicate = true;
+        findings.push(portableFinding('error', 'portable.companion.attachment.duplicate', 'Two companion attachment entries resolve to the same exact Transition representation.', {
+          ref: material.path || '',
+          entry: entry.name,
+          transitionRepresentationKey: targetKey
+        }));
+      }
+      seenRepresentationKeys.add(targetKey);
+    }
+    const participation = resolution.qualification === 'resolved' && typeof input.qualifyParticipation === 'function'
+      ? input.qualifyParticipation({ companionMaterial: material, schemaBinding, transitionMaterial: resolution.material, attachmentEntry: entry })
+      : Object.freeze({ qualification: 'unresolved', evidence: Object.freeze([]) });
+    if (participation?.qualification === 'contradictory') {
+      findings.push(portableFinding('error', 'portable.companion.attachment.participation.contradictory', 'Resolved Transition participation definitively excludes the companion-bound schema.', {
+        ref: material.path || '',
+        entry: entry.name,
+        transitionRepresentationKey: targetKey
+      }));
+    } else if (resolution.qualification === 'resolved' && participation?.qualification === 'unresolved') {
+      findings.push(portableFinding('warning', 'portable.companion.attachment.participation.unresolved', 'Attachment resolves, but Transition participation for the companion-bound schema remains unresolved.', {
+        ref: material.path || '',
+        entry: entry.name,
+        transitionRepresentationKey: targetKey
+      }));
+    }
+    attachments.push(Object.freeze({
+      name: entry.name,
+      reference,
+      referenceTarget: resolution.referenceTarget,
+      referenceQualification: resolution.qualification,
+      transitionRepresentationKey: targetKey,
+      transitionPath: String(resolution.material?.path || ''),
+      duplicate,
+      note: String(entry.fields?.Note || ''),
+      participation: participation || Object.freeze({ qualification: 'unresolved', evidence: Object.freeze([]) }),
+      source: entry.source || null
+    }));
+  }
+
+  return companionResult(material, projection, schemaBinding, attachments, findings, explicitEmpty);
+}
+
+function companionResult(material, projection, schemaBinding, attachments, findings, explicitEmpty = false) {
+  const summary = summarizePortableFindings(findings);
+  const status = summary.counts.error ? 'invalid' : summary.counts.warning ? 'unresolved' : 'valid';
+  return Object.freeze({
+    schema: PORTABLE_SCHEMA_TRANSITION_COMPANION_SCHEMA_ID,
+    status,
+    representationKey: String(material?.representationKey || ''),
+    path: String(material?.path || ''),
+    source: Object.freeze({ ...(material?.source || {}) }),
+    references: Object.freeze([...(material?.referenceAliases || [])]),
+    projection,
+    schemaBinding: schemaBinding || Object.freeze({ qualification: 'unresolved', reference: '', representationKey: '', schemaId: '' }),
+    attachmentSet: Object.freeze({
+      state: explicitEmpty ? 'explicit-empty' : 'declared',
+      explicitEmpty,
+      attachments: Object.freeze([...(attachments || [])])
+    }),
+    findings: Object.freeze([...(findings || [])]),
+    findingSummary: summary
+  });
+}
+
+function resolveQualifiedReference({ projection, group, field, value, resolve, material, entry }) {
+  const text = String(value || '');
+  if (!text) {
+    return Object.freeze({
+      qualification: 'unresolved', reference: text, referenceTarget: '', material: null,
+      finding: portableFinding('error', 'portable.companion.reference.missing', `Required reference field is missing: ${group}.${field}.`, { ref: material.path || '', entry, field })
+    });
+  }
+  const shape = portableFieldDomainOccurrenceQualification(projection, group, field, text, entry);
+  if (shape !== 'core') {
+    return Object.freeze({
+      qualification: 'unresolved', reference: text, referenceTarget: '', material: null,
+      finding: portableFinding('warning', 'portable.companion.reference.shape.unresolved', `Reference field does not have resolved canonical Markdown Link shape authority: ${group}.${field}.`, { ref: material.path || '', entry, field, fieldDomainQualification: shape })
+    });
+  }
+  const target = extractQualifiedMarkdownLinkTarget(text);
+  if (!target) {
+    return Object.freeze({
+      qualification: 'unresolved', reference: text, referenceTarget: '', material: null,
+      finding: portableFinding('error', 'portable.companion.reference.decomposition.failed', 'A shape-qualified Markdown Link could not be decomposed into its target.', { ref: material.path || '', entry, field })
+    });
+  }
+  if (typeof resolve !== 'function') {
+    return Object.freeze({
+      qualification: 'unresolved', reference: text, referenceTarget: target, material: null,
+      finding: portableFinding('warning', 'portable.companion.reference.resolver.unavailable', 'No package-scoped reference resolver was supplied for a shape-qualified reference.', { ref: material.path || '', entry, field, target })
+    });
+  }
+  const resolved = resolve({ target, value: text, fromMaterial: material, entry, field, group }) || {};
+  const qualification = String(resolved.qualification || 'unresolved');
+  const severity = qualification === 'ambiguous' || qualification === 'invalid' ? 'error' : 'warning';
+  const finding = qualification === 'resolved'
+    ? null
+    : portableFinding(severity, qualification === 'ambiguous' ? 'portable.companion.reference.ambiguous' : qualification === 'invalid' ? 'portable.companion.reference.invalid' : 'portable.companion.reference.unresolved', resolved.finding || `Reference could not resolve exactly: ${target}.`, { ref: material.path || '', entry, field, target });
+  const candidates = Object.freeze((resolved.candidates || []).map((candidate) => Object.freeze({
+    representationKey: String(candidate?.representationKey || ''),
+    path: String(candidate?.path || ''),
+    schemaId: String(candidate?.schemaId || ''),
+    source: Object.freeze({ ...(candidate?.source || {}) })
+  })));
+  return Object.freeze({
+    qualification,
+    reference: text,
+    referenceTarget: target,
+    material: qualification === 'resolved' ? (resolved.material || resolved.candidates?.[0] || null) : null,
+    candidates,
+    finding
+  });
+}
+
+function ordinaryFieldValue(projection = {}, groupName = '', fieldName = '') {
+  const group = (projection.ordinaryGroups || []).find((item) => exact(item.group) === exact(groupName));
+  const field = (group?.fields || []).find((item) => exact(item.label) === exact(fieldName));
+  const occurrences = field?.occurrences || [];
+  return occurrences.length === 1 ? String(occurrences[0].value ?? '') : '';
+}
+
+function declarationGroup(groups = [], name = '') {
+  return (groups || []).find((item) => exact(item.contract?.group) === exact(name));
+}
+
+function exact(value = '') {
+  return String(value || '').trim();
+}

package/src/tooling/portable/package/semantic.package.graph.js

@@ -0,0 +1,272 @@
+import { portableFinding } from '../findings.js';
+import { projectPortableContractInstance } from '../schema/contract.project.js';
+import {
+  dirname,
+  extractQualifiedMarkdownLinkTarget,
+  isAbsoluteReference,
+  normalizePortablePath,
+  pathWithinBoundary,
+  portableFieldDomainOccurrenceQualification,
+  relativePathEscapesBoundary,
+  resolvePortableMaterialReference
+} from './material.graph.js';
+import { isCompanionArtifact, isPackageManifestArtifact, isTransitionArtifact } from './semantic.package.types.js';
+import { materialIsSchemaDocument } from './material.graph.js';
+
+export function compileSemanticPackageGraph(input = {}) {
+  const state = {
+    materialIndex: input.materialIndex,
+    compiledContract: input.compiledContract,
+    resolvers: input.resolvers || {},
+    nodes: new Map(),
+    edges: [],
+    findings: [],
+    active: []
+  };
+  compilePackageNode(input.selectedManifest, state, Object.freeze({ kind: 'selected', fromPackageKey: '', declarationName: '', reference: '', referenceTarget: '' }));
+  const nodes = [...state.nodes.values()];
+  for (const node of nodes) node.reachablePackageKeys = Object.freeze(reachablePackageKeys(node.manifestKey, state));
+  return Object.freeze({ nodes: Object.freeze(nodes), edges: Object.freeze(state.edges), findings: Object.freeze(state.findings), state });
+}
+
+export function selectSemanticPackageManifest(index, selector) {
+  if (selector && typeof selector === 'object' && selector.representationKey && index.byKey.has(selector.representationKey)) {
+    return Object.freeze({ qualification: 'resolved', material: index.byKey.get(selector.representationKey) });
+  }
+  const token = String(selector || '');
+  if (index.byKey.has(token)) return Object.freeze({ qualification: 'resolved', material: index.byKey.get(token) });
+  const byPath = index.byPath.get(normalizePortablePath(token)) || [];
+  const byReference = index.byReference.get(token) || [];
+  const candidates = uniqueMaterials([...byPath, ...byReference]);
+  if (candidates.length === 1) return Object.freeze({ qualification: 'resolved', material: candidates[0] });
+  return Object.freeze({ qualification: candidates.length > 1 ? 'ambiguous' : 'unresolved', material: null, candidates: Object.freeze(candidates) });
+}
+
+export function packageContainingMaterial(materialKey, nodes = []) {
+  const matches = [...nodes].filter((node) => node.localMaterialKeys.includes(materialKey));
+  return matches.length === 1 ? matches[0].manifestKey : '';
+}
+
+export function projectPackageGraph(nodes = [], edges = []) {
+  return Object.freeze({
+    nodes: Object.freeze([...nodes].map(freezePackageNode).sort((a, b) => compare(a.manifestKey, b.manifestKey))),
+    edges: Object.freeze([...edges].sort(compareEdge))
+  });
+}
+
+function compilePackageNode(manifest, state, route) {
+  const key = manifest.representationKey;
+  const existing = state.nodes.get(key);
+  if (existing) {
+    pushUniqueRoute(existing.routes, route);
+    if (state.active.includes(key)) {
+      state.findings.push(portableFinding('info', 'portable.semantic-package.cycle.observed', 'Package dependency cycle observed and terminated by exact manifest representation.', { ref: manifest.path || key, packageKey: key, route }));
+    }
+    return existing;
+  }
+
+  const manifestPathAvailable = Boolean(String(manifest.path || ''));
+  const root = manifestPathAvailable ? dirname(manifest.path) : '';
+  const projection = projectPortableContractInstance({ markdown: manifest.markdown, compiledContract: state.compiledContract, resolvers: state.resolvers });
+  if (!manifestPathAvailable) {
+    state.findings.push(portableFinding('error', 'portable.semantic-package.boundary.manifest-path-missing', 'Semantic Package Manifest cannot establish Boundary Root: manifest-directory without an exact material path.', { ref: key, packageKey: key }));
+  }
+  state.findings.push(...projection.validation.findings);
+  const boundaryRoot = ordinaryFieldValue(projection, 'Package Boundary', 'Boundary Root');
+  const discoveryPolicy = ordinaryFieldValue(projection, 'Package Boundary', 'Discovery Policy');
+  const nestedPolicy = ordinaryFieldValue(projection, 'Package Boundary', 'Nested Package Policy');
+  if (boundaryRoot !== 'manifest-directory' || discoveryPolicy !== 'recursive-within-boundary' || nestedPolicy !== 'explicit-only') {
+    state.findings.push(portableFinding('error', 'portable.semantic-package.boundary.unsupported', 'Selected package boundary policy is not the canonical v1 manifest-directory / recursive-within-boundary / explicit-only policy.', { ref: manifest.path || key }));
+  }
+
+  const packageManifests = manifestPathAvailable
+    ? state.materialIndex.materials.filter((item) => isPackageManifestArtifact(item) && item.path && pathWithinBoundary(item.path, root))
+    : [manifest];
+  const sameDirectory = packageManifests.filter((item) => dirname(item.path) === root);
+  const manifestBoundaryAmbiguous = sameDirectory.length !== 1 || sameDirectory[0].representationKey !== key;
+  if (manifestBoundaryAmbiguous) {
+    state.findings.push(portableFinding('error', 'portable.semantic-package.boundary.manifest-ambiguous', 'Package boundary directory exposes competing Semantic Package Manifest authority.', { ref: manifest.path || key, count: sameDirectory.length }));
+  }
+
+  const allNestedRoots = unique(packageManifests.map((item) => dirname(item.path)).filter((dir) => dir !== root)).sort(compare);
+  const nestedRoots = nearestNestedPackageRoots(packageManifests, root);
+  const boundaryPolicyValid = boundaryRoot === 'manifest-directory' && discoveryPolicy === 'recursive-within-boundary' && nestedPolicy === 'explicit-only';
+  const boundaryUsable = manifestPathAvailable && boundaryPolicyValid && !manifestBoundaryAmbiguous;
+  const localMaterials = boundaryUsable
+    ? state.materialIndex.materials.filter((item) => item.path && pathWithinBoundary(item.path, root) && !nestedRoots.some((nested) => pathWithinBoundary(item.path, nested)))
+    : [manifest];
+
+  const node = {
+    manifestKey: key,
+    manifestPath: manifest.path,
+    manifestSource: Object.freeze({ ...(manifest.source || {}) }),
+    manifestReferences: Object.freeze([...(manifest.referenceAliases || [])]),
+    packageRoot: root,
+    manifestProjection: projection,
+    routes: [route],
+    nestedPackageRoots: Object.freeze(nestedRoots),
+    allNestedPackageRoots: Object.freeze(allNestedRoots),
+    boundaryQualification: boundaryUsable ? 'valid' : 'invalid',
+    localMaterialKeys: Object.freeze(localMaterials.map((item) => item.representationKey)),
+    localSchemaKeys: Object.freeze(localMaterials.filter(materialIsSchemaDocument).map((item) => item.representationKey)),
+    localCompanionKeys: Object.freeze(localMaterials.filter(isCompanionArtifact).map((item) => item.representationKey)),
+    localTransitionKeys: Object.freeze(localMaterials.filter((item) => isTransitionArtifact(item) && transitionPathIsAutoDiscovered(item.path, root)).map((item) => item.representationKey)),
+    includedDeclarations: Object.freeze(declarationEntries(projection, 'Included Package Declaration')),
+    externalDeclarations: Object.freeze(declarationEntries(projection, 'External Package Dependency Declaration')),
+    schemaBindingDeclarations: Object.freeze(declarationEntries(projection, 'Schema Resolution Binding Declaration')),
+    outgoingEdges: [],
+    reachablePackageKeys: Object.freeze([])
+  };
+  state.nodes.set(key, node);
+  state.active.push(key);
+
+  for (const entry of node.includedDeclarations) resolveAndTraverseEdge('included', node, entry, state);
+  for (const entry of node.externalDeclarations) resolveAndTraverseEdge('external', node, entry, state);
+
+  state.active.pop();
+  return node;
+}
+
+function resolveAndTraverseEdge(kind, node, entry, state) {
+  if (entry.name === 'none') return;
+  const edge = resolvePackageEdge({ kind, node, entry, state });
+  node.outgoingEdges.push(edge);
+  state.edges.push(edge);
+  if (edge.qualification === 'resolved') compilePackageNode(state.materialIndex.byKey.get(edge.targetPackageKey), state, edgeRoute(edge));
+}
+
+function resolvePackageEdge({ kind, node, entry, state }) {
+  const field = 'Package Reference';
+  const value = String(entry.fields?.[field] || '');
+  const group = kind === 'included' ? 'Included Package Declaration' : 'External Package Dependency Declaration';
+  const shape = portableFieldDomainOccurrenceQualification(node.manifestProjection, group, field, value, entry.name);
+  if (shape !== 'core') return findingEdge(kind, node, entry, value, '', 'unresolved', '', 'Reference shape authority is unresolved or invalid.', state, 'shape.unresolved', 'warning');
+
+  const target = extractQualifiedMarkdownLinkTarget(value);
+  const manifestMaterial = state.materialIndex.byKey.get(node.manifestKey);
+  if (kind === 'included' && !isAbsoluteReference(target) && relativePathEscapesBoundary(manifestMaterial, target, node.packageRoot)) {
+    return findingEdge(kind, node, entry, value, target, 'invalid', '', 'Included Package Reference escapes the current package boundary.', state, 'boundary.invalid', 'error');
+  }
+  if (kind === 'external' && !isAbsoluteReference(target) && relativePathEscapesBoundary(manifestMaterial, target, node.packageRoot)) {
+    return findingEdge(kind, node, entry, value, target, 'invalid', '', 'External Package Reference must not rely on a relative path escaping the current package boundary.', state, 'relative-escape', 'error');
+  }
+
+  const resolved = resolvePortableMaterialReference(state.materialIndex, manifestMaterial, target);
+  if (resolved.qualification !== 'resolved') {
+    return findingEdge(kind, node, entry, value, target, resolved.qualification, '', resolved.finding || 'Package reference did not resolve exactly.', state, `reference.${resolved.qualification}`, resolved.qualification === 'ambiguous' ? 'error' : 'warning');
+  }
+  const material = resolved.candidates[0];
+  if (!isPackageManifestArtifact(material)) return findingEdge(kind, node, entry, value, target, 'invalid', '', 'Package Reference target is not a Semantic Package Manifest artifact.', state, 'target.invalid', 'error');
+
+  if (kind === 'included') {
+    if (!node.allNestedPackageRoots.includes(dirname(material.path))) {
+      return findingEdge(kind, node, entry, value, target, 'invalid', '', 'Included Package Reference does not resolve to an explicit nested package boundary below the current package root.', state, 'boundary.invalid', 'error');
+    }
+  } else if (pathWithinBoundary(material.path, node.packageRoot)) {
+    return findingEdge(kind, node, entry, value, target, 'invalid', '', 'External Package Reference resolves inside the current package boundary instead of an external package authority.', state, 'target.local', 'error');
+  }
+
+  return frozenEdge(kind, node, entry, value, target, 'resolved', material.representationKey, '');
+}
+
+function findingEdge(kind, node, entry, reference, target, qualification, targetPackageKey, message, state, suffix, severity) {
+  const edge = frozenEdge(kind, node, entry, reference, target, qualification, targetPackageKey, message);
+  state.findings.push(portableFinding(severity, `portable.semantic-package.${kind}.${suffix}`, message, { ref: node.manifestPath, entry: entry.name, target }));
+  return edge;
+}
+
+function nearestNestedPackageRoots(packageManifests, root) {
+  const roots = unique(packageManifests.map((item) => dirname(item.path)).filter((dir) => dir !== root));
+  return roots.filter((candidate) => !roots.some((other) => other !== candidate && pathWithinBoundary(candidate, other))).sort(compare);
+}
+
+function reachablePackageKeys(start, state) {
+  const visited = new Set();
+  const stack = [start];
+  while (stack.length) {
+    const key = stack.pop();
+    if (visited.has(key)) continue;
+    visited.add(key);
+    const node = state.nodes.get(key);
+    for (const edge of node?.outgoingEdges || []) if (edge.qualification === 'resolved' && edge.targetPackageKey) stack.push(edge.targetPackageKey);
+  }
+  return [...visited].sort(compare);
+}
+
+function ordinaryFieldValue(projection, groupName, fieldName) {
+  const group = (projection.ordinaryGroups || []).find((item) => exact(item.group) === exact(groupName));
+  const field = (group?.fields || []).find((item) => exact(item.label) === exact(fieldName));
+  return field?.occurrences?.length === 1 ? String(field.occurrences[0].value ?? '') : '';
+}
+
+function declarationEntries(projection, groupName) {
+  const group = (projection.validation?.declarations || []).find((item) => exact(item.contract?.group) === exact(groupName));
+  return group?.sections?.flatMap((section) => section.present ? section.entries : []) || [];
+}
+
+function transitionPathIsAutoDiscovered(path, root) {
+  if (!pathWithinBoundary(path, root)) return false;
+  return normalizePortablePath(path).split('/').filter(Boolean).includes('.transitions');
+}
+
+function frozenEdge(kind, node, entry, reference, target, qualification, targetPackageKey, finding) {
+  return Object.freeze({
+    kind,
+    fromPackageKey: node.manifestKey,
+    fromPackagePath: node.manifestPath,
+    declarationName: entry.name,
+    declarationSource: entry.source || null,
+    reference,
+    referenceTarget: target,
+    qualification,
+    targetPackageKey,
+    finding: String(finding || '')
+  });
+}
+
+function edgeRoute(edge) {
+  return Object.freeze({ kind: edge.kind, fromPackageKey: edge.fromPackageKey, declarationName: edge.declarationName, reference: edge.reference, referenceTarget: edge.referenceTarget });
+}
+
+function freezePackageNode(node) {
+  return Object.freeze({
+    manifestKey: node.manifestKey,
+    manifestPath: node.manifestPath,
+    manifestSource: node.manifestSource,
+    manifestReferences: node.manifestReferences,
+    packageRoot: node.packageRoot,
+    routes: Object.freeze([...(node.routes || [])].sort(compareObject)),
+    nestedPackageRoots: node.nestedPackageRoots,
+    allNestedPackageRoots: node.allNestedPackageRoots,
+    boundaryQualification: node.boundaryQualification,
+    localMaterialKeys: node.localMaterialKeys,
+    localSchemaKeys: node.localSchemaKeys,
+    localCompanionKeys: node.localCompanionKeys,
+    localTransitionKeys: node.localTransitionKeys,
+    reachablePackageKeys: node.reachablePackageKeys,
+    outgoingEdges: Object.freeze([...(node.outgoingEdges || [])].sort(compareEdge))
+  });
+}
+
+function pushUniqueRoute(routes, route) {
+  const text = JSON.stringify(route);
+  if (!routes.some((item) => JSON.stringify(item) === text)) routes.push(route);
+}
+
+function unique(values = []) { return [...new Set(values.map(String).filter(Boolean))]; }
+
+function uniqueMaterials(values = []) {
+  const seen = new Set();
+  return values.filter((item) => {
+    if (!item || seen.has(item.representationKey)) return false;
+    seen.add(item.representationKey);
+    return true;
+  });
+}
+
+function compare(a = '', b = '') { const left = String(a); const right = String(b); return left < right ? -1 : left > right ? 1 : 0; }
+function compareObject(a = {}, b = {}) { return compare(JSON.stringify(a), JSON.stringify(b)); }
+function compareEdge(a = {}, b = {}) {
+  return compare(`${a.fromPackageKey || ''}\u0000${a.kind || ''}\u0000${a.declarationName || ''}\u0000${a.targetPackageKey || ''}\u0000${a.referenceTarget || ''}`, `${b.fromPackageKey || ''}\u0000${b.kind || ''}\u0000${b.declarationName || ''}\u0000${b.targetPackageKey || ''}\u0000${b.referenceTarget || ''}`);
+}
+function exact(value = '') { return String(value || '').trim(); }

package/src/tooling/portable/package/semantic.package.js

@@ -0,0 +1,203 @@
+import { portableFinding, summarizePortableFindings } from '../findings.js';
+import { indexPortableMaterials } from './material.graph.js';
+import { compilePortableSchemaTransitionCompanion } from './schema.transition.companion.js';
+import {
+  compileSemanticPackageGraph,
+  packageContainingMaterial,
+  projectPackageGraph,
+  selectSemanticPackageManifest
+} from './semantic.package.graph.js';
+import {
+  compileSemanticPackageSchemaResolution,
+  projectSchemaResolutions,
+  resolveCompanionSchemaReference
+} from './semantic.package.schema-resolution.js';
+import {
+  compileAttachmentStates,
+  detectCompanionConflicts,
+  ensureTransitionRegistryEntry,
+  finalizeTransitionRegistry,
+  qualifyAttachmentParticipation,
+  resolvePackageTransitionReference
+} from './semantic.package.transition-registry.js';
+import {
+  PORTABLE_SEMANTIC_PACKAGE_COMPILATION_SCHEMA_ID,
+  SEMANTIC_PACKAGE_SCHEMA_ID,
+  SCHEMA_TRANSITION_COMPANION_SCHEMA_ID,
+  TRANSITION_DEFINITION_SCHEMA_ID,
+  isPackageManifestArtifact
+} from './semantic.package.types.js';
+
+export {
+  PORTABLE_SEMANTIC_PACKAGE_COMPILATION_SCHEMA_ID,
+  SEMANTIC_PACKAGE_SCHEMA_ID,
+  SCHEMA_TRANSITION_COMPANION_SCHEMA_ID,
+  TRANSITION_DEFINITION_SCHEMA_ID
+} from './semantic.package.types.js';
+
+export function compilePortableSemanticPackage(input = {}) {
+  const materialIndex = indexPortableMaterials(input.materials || []);
+  const findings = [];
+  for (const conflict of materialIndex.representationKeyConflicts || []) {
+    findings.push(portableFinding('error', 'portable.material-graph.representation-key.duplicate', 'One supplied representationKey maps to more than one concrete material representation; v1 fails closed instead of deduplicating or choosing one.', {
+      representationKey: conflict.representationKey,
+      candidates: conflict.candidates
+    }));
+  }
+  if (findings.length) return finalResult({ selected: null, materialIndex, findings });
+  const selected = selectSemanticPackageManifest(materialIndex, input.selectedManifest || input.manifest || input.manifestReference || '');
+  if (selected.qualification !== 'resolved' || !isPackageManifestArtifact(selected.material)) {
+    findings.push(portableFinding('error', 'portable.semantic-package.selected-manifest.unresolved', 'Selected Semantic Package Manifest did not resolve to exactly one manifest artifact.', {
+      ref: String(input.selectedManifest || input.manifestReference || ''),
+      qualification: selected.qualification
+    }));
+    return finalResult({ selected: selected.material, materialIndex, findings });
+  }
+
+  const contracts = input.contracts || {};
+  if (!contracts.semanticPackage || !contracts.schemaTransitionCompanion || !contracts.transitionDefinition) {
+    findings.push(portableFinding('error', 'portable.semantic-package.contracts.missing', 'Semantic package compilation requires compiled canonical contracts for Semantic Package Manifest, Schema Transition Companion, and Transition Definition.', { ref: selected.material.path || '' }));
+    return finalResult({ selected: selected.material, materialIndex, findings });
+  }
+
+  const graph = compileSemanticPackageGraph({
+    selectedManifest: selected.material,
+    materialIndex,
+    compiledContract: contracts.semanticPackage,
+    resolvers: input.resolvers || {}
+  });
+  findings.push(...graph.findings);
+
+  const schemaResolution = compileSemanticPackageSchemaResolution({ nodes: graph.nodes, materialIndex });
+  findings.push(...schemaResolution.findings);
+
+  const transitionRegistry = new Map();
+  const registryContext = Object.freeze({
+    nodes: graph.nodes,
+    materialIndex,
+    transitionContract: contracts.transitionDefinition,
+    resolvers: input.resolvers || {},
+    schemaResolutionIndex: schemaResolution.index,
+    resolveSchemaConstraint: input.resolveSchemaConstraint
+  });
+
+  for (const node of graph.nodes) {
+    for (const key of node.localTransitionKeys) {
+      ensureTransitionRegistryEntry(transitionRegistry, materialIndex.byKey.get(key), node, 'distributed-.transitions', registryContext);
+    }
+  }
+
+  const companions = compileCompanions({
+    nodes: graph.nodes,
+    materialIndex,
+    contract: contracts.schemaTransitionCompanion,
+    resolvers: input.resolvers || {},
+    transitionRegistry,
+    registryContext,
+    findings
+  });
+
+  const companionConflicts = detectCompanionConflicts(companions, findings);
+  const attachmentStates = compileAttachmentStates(graph.nodes, companions, companionConflicts, materialIndex);
+  const registry = finalizeTransitionRegistry(transitionRegistry);
+  appendRegistryQualificationFindings(registry, findings);
+
+  return finalResult({
+    selected: selected.material,
+    materialIndex,
+    packageGraph: projectPackageGraph(graph.nodes, graph.edges),
+    schemaResolutions: projectSchemaResolutions(schemaResolution.index),
+    companions,
+    registry,
+    attachmentStates,
+    findings
+  });
+}
+
+function compileCompanions(input) {
+  const companions = [];
+  for (const node of input.nodes) {
+    for (const key of node.localCompanionKeys) {
+      const material = input.materialIndex.byKey.get(key);
+      const compiled = compilePortableSchemaTransitionCompanion({
+        material,
+        compiledContract: input.contract,
+        resolvers: input.resolvers,
+        resolveSchemaReference: ({ target, fromMaterial }) => resolveCompanionSchemaReference(node, fromMaterial, target, { materialIndex: input.materialIndex }),
+        resolveTransitionReference: ({ target, fromMaterial }) => resolvePackageTransitionReference(node, fromMaterial, target, { materialIndex: input.materialIndex, nodes: input.nodes }),
+        qualifyParticipation: ({ schemaBinding, transitionMaterial }) => qualifyAttachmentParticipation({
+          ...input.registryContext,
+          schemaBinding,
+          transitionMaterial,
+          packageNode: node,
+          transitionRegistry: input.transitionRegistry
+        })
+      });
+      const projected = Object.freeze({ ...compiled, packageKey: node.manifestKey, packagePath: node.manifestPath });
+      companions.push(projected);
+      input.findings.push(...compiled.findings);
+      attachCompanionProvenance(projected, node, input);
+    }
+  }
+  return Object.freeze(companions.sort((a, b) => compare(a.representationKey, b.representationKey)));
+}
+
+function attachCompanionProvenance(compiled, node, input) {
+  for (const attachment of compiled.attachmentSet.attachments || []) {
+    if (attachment.referenceQualification !== 'resolved' || !attachment.transitionRepresentationKey) continue;
+    const target = input.materialIndex.byKey.get(attachment.transitionRepresentationKey);
+    const entry = ensureTransitionRegistryEntry(input.transitionRegistry, target, node, 'companion-attachment-reference', input.registryContext);
+    const containingPackageKey = packageContainingMaterial(target.representationKey, input.nodes);
+    entry.attachmentProvenance.push(Object.freeze({
+      companionRepresentationKey: compiled.representationKey,
+      companionPath: compiled.path,
+      companionSource: compiled.source || Object.freeze({}),
+      boundSchemaRepresentationKey: compiled.schemaBinding?.representationKey || '',
+      boundSchemaReference: compiled.schemaBinding?.reference || '',
+      boundSchemaReferenceTarget: compiled.schemaBinding?.referenceTarget || '',
+      attachmentName: attachment.name,
+      transitionReference: attachment.reference,
+      transitionReferenceTarget: attachment.referenceTarget,
+      transitionContainingPackageKey: containingPackageKey,
+      attachmentSource: attachment.source || null,
+      packageKey: node.manifestKey,
+      participationQualification: attachment.participation?.qualification || 'unresolved'
+    }));
+  }
+}
+
+function appendRegistryQualificationFindings(registry, findings) {
+  for (const entry of registry) {
+    if (entry.representationQualification === 'contradictory' || entry.representationQualification === 'structurally-invalid') {
+      findings.push(portableFinding('error', 'portable.semantic-package.transition.representation.invalid', 'A discovered Transition Definition representation is not canonically qualified.', { ref: entry.path, transitionRepresentationKey: entry.representationKey }));
+    } else if (entry.representationQualification !== 'valid') {
+      findings.push(portableFinding('warning', 'portable.semantic-package.transition.representation.unresolved', 'A discovered Transition Definition representation is not fully qualified.', { ref: entry.path, transitionRepresentationKey: entry.representationKey, qualification: entry.representationQualification }));
+    }
+  }
+}
+
+function finalResult(input = {}) {
+  const summary = summarizePortableFindings(input.findings || []);
+  const status = summary.counts.error ? 'invalid' : summary.counts.warning ? 'unresolved' : 'valid';
+  return Object.freeze({
+    schema: PORTABLE_SEMANTIC_PACKAGE_COMPILATION_SCHEMA_ID,
+    status,
+    selectedManifest: input.selected ? Object.freeze({ representationKey: input.selected.representationKey, path: input.selected.path, schemaId: input.selected.schemaId }) : null,
+    packageGraph: input.packageGraph || Object.freeze({ nodes: Object.freeze([]), edges: Object.freeze([]) }),
+    schemaResolutions: input.schemaResolutions || Object.freeze([]),
+    companions: input.companions || Object.freeze([]),
+    schemaAttachments: input.attachmentStates || Object.freeze([]),
+    transitionRegistry: input.registry || Object.freeze([]),
+    materialCount: input.materialIndex?.materials?.length || 0,
+    findings: Object.freeze([...(input.findings || [])]),
+    findingSummary: summary,
+    limitations: Object.freeze([
+      'Package discovery is bounded to explicitly supplied material and explicit package/reference routes; no repository-global fallback exists.',
+      'Package locality is discovery/provenance only and is not Transition identity or applicability authority.',
+      'Schema assignability and implicit companion inheritance are not inferred.',
+      'Attachment participation is read-only qualification and never creates participation or execution authority.'
+    ])
+  });
+}
+
+function compare(a = '', b = '') { const left = String(a); const right = String(b); return left < right ? -1 : left > right ? 1 : 0; }