@tiinex/core 0.1.1

package/src/tooling/portable/grounding/grounding.workContext.js

@@ -0,0 +1,72 @@
+import { posix } from 'node:path';
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+
+const MAX_PARENT_DEPTH = 6;
+const CONTEXT_HEADINGS = Object.freeze([
+  Object.freeze({ kind: 'project', headings: Object.freeze(['Project Identity', 'Project Context']) }),
+  Object.freeze({ kind: 'organization', headings: Object.freeze(['Organization Identity', 'Organization Context']) })
+]);
+
+export function projectQualifiedWorkTargetContext(target = {}, byPath = new Map()) {
+  const start = String(target.resolvedPath || '');
+  const chain = qualifiedContextChain(start, byPath);
+  const contexts = [];
+  for (let distance = 0; distance < chain.length; distance += 1) {
+    const record = chain[distance];
+    for (const definition of CONTEXT_HEADINGS) {
+      for (const heading of definition.headings) {
+        const text = section(record.markdown || '', heading);
+        if (!text) continue;
+        contexts.push(Object.freeze({
+          kind: definition.kind,
+          state: 'qualified-carried',
+          label: field(text, 'Name') || String(record.title || ''),
+          path: String(record.path || ''),
+          schemaId: String(record.schemaId || ''),
+          description: compact(field(text, 'Description') || text, 220),
+          declaredBoundary: compact(field(text, 'Boundary'), 180),
+          basis: Object.freeze({ kind: 'explicit-qualified-context-section', heading, targetPath: start, parentDistance: distance }),
+          membershipClaim: false
+        }));
+        break;
+      }
+    }
+  }
+  const project = contexts.find((item) => item.kind === 'project') || unresolved('project-context-unresolved', 'No explicit qualified project identity/context section was recoverable from the work target or its qualified direct Parent context.');
+  const organization = contexts.find((item) => item.kind === 'organization') || unresolved('organization-context-unresolved', 'No explicit qualified organization identity/context section was recoverable from the work target or its qualified direct Parent context.');
+  const qualifiedCount = Number(project.state === 'qualified-carried') + Number(organization.state === 'qualified-carried');
+  return Object.freeze({
+    state: qualifiedCount === 2 ? 'qualified' : qualifiedCount === 1 ? 'qualified-partial' : 'unresolved',
+    project,
+    organization,
+    contexts: Object.freeze(contexts),
+    boundary: 'Direct Parent continuity may be followed only to inspect already-declared qualified context. Parent is not reinterpreted as work provenance, project membership, organization membership, responsibility transfer, or controlling-work authority.'
+  });
+}
+
+function qualifiedContextChain(startPath = '', byPath = new Map()) {
+  const out = [];
+  let path = startPath;
+  const seen = new Set();
+  for (let depth = 0; depth < MAX_PARENT_DEPTH && path && !seen.has(path); depth += 1) {
+    seen.add(path);
+    const matches = byPath.get(path) || [];
+    if (matches.length !== 1) break;
+    const record = matches[0];
+    if (!record.hasContinuityContext || !record.hasIntegrity) break;
+    out.push(record);
+    let parsed;
+    try { parsed = parseArtifactMarkdown(record.markdown || ''); } catch { break; }
+    const parent = String(parsed?.envelope?.parent?.trace || '').trim();
+    if (!parent || /^[a-z][a-z0-9+.-]*:\/\//i.test(parent)) break;
+    path = resolvePath(parent, record.path || '');
+  }
+  return out;
+}
+function resolvePath(reference = '', ownerPath = '') { const raw = String(reference || '').split('#')[0].trim(); const cross = raw.match(/^([^:/\\]+)::(.+)$/); const candidate = cross ? `${cross[1]}/${cross[2].replace(/^\/+/, '')}` : raw.startsWith('/') ? raw.slice(1) : posix.join(posix.dirname(String(ownerPath || '')), raw); const normalized = posix.normalize(candidate).replace(/^\.\//, ''); return !normalized || normalized === '..' || normalized.startsWith('../') ? '' : normalized; }
+function unresolved(code, detail) { return Object.freeze({ state: 'unresolved', code, detail, membershipClaim: false }); }
+function section(markdown = '', heading = '') { const escaped = escape(heading); return String(markdown || '').match(new RegExp(`(?:^|\\n)##\\s+${escaped}\\s*\\r?\\n([\\s\\S]*?)(?=\\n##\\s+|\\n#\\s+Continuity Integrity|$)`, 'i'))?.[1]?.trim() || ''; }
+function field(markdown = '', label = '') { const escaped = escape(label); return strip(String(markdown || '').match(new RegExp(`^\\s*-\\s+${escaped}:\\s*(.+)$`, 'mi'))?.[1] || ''); }
+function strip(value = '') { return String(value || '').replace(/^\[([^\]]+)\]\([^)]+\)$/, '$1').replace(/[`*_]/g, '').trim(); }
+function compact(value = '', limit = 220) { const text = strip(String(value || '').replace(/\s+/g, ' ')); return text.length > limit ? `${text.slice(0, limit - 1).trimEnd()}…` : text; }
+function escape(value = '') { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/tooling/portable/grounding/grounding.workProvenance.js

@@ -0,0 +1,153 @@
+import { posix } from 'node:path';
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { relationValidate } from '../../../schemas/core/relation/tiinex.relation.v1.validate.js';
+import { projectQualifiedWorkTargetContext } from './grounding.workContext.js';
+
+const FAMILY = 'work-provenance';
+const MAX_EDGES = 12;
+
+export function projectWorkProvenance({ records = [], topology = {} } = {}) {
+  const byPath = recordIndex(records);
+  const edges = records.filter(isCandidate).map((record) => relationEdge(record, byPath)).filter(Boolean).slice(0, MAX_EDGES);
+  const frontierPaths = new Set((topology.currentFrontier || []).map((item) => String(item.path || '')).filter(Boolean));
+  const relevantPaths = new Set([
+    ...(topology.relevantPaths || []),
+    ...(topology.currentTasks || []).map((item) => String(item.path || '')),
+    ...frontierPaths
+  ].filter(Boolean));
+  const exactQualified = edges.filter((edge) => edge.state === 'qualified' && frontierPaths.has(edge.source.resolvedPath));
+  const lineageQualified = exactQualified.length ? [] : edges.filter((edge) => edge.state === 'qualified' && relevantPaths.has(edge.source.resolvedPath));
+  const selected = exactQualified.length ? exactQualified : lineageQualified;
+  const selectionState = exactQualified.length ? 'qualified' : lineageQualified.length ? 'qualified-relevant' : 'unresolved';
+  const unresolved = [];
+
+  if (!frontierPaths.size) unresolved.push(issue('organizational-work-provenance', 'current-work-anchor-unresolved', 'No current work frontier.'));
+  else if (!selected.length) {
+    const candidates = edges.filter((edge) => relevantPaths.has(edge.source.resolvedPath));
+    unresolved.push(issue('organizational-work-provenance', 'organizational-work-provenance-unresolved', candidates.length ? 'Declared work-provenance material on the selected lineage exists, but source/target qualification is unresolved.' : 'No qualified declared edge on current lineage.'));
+  } else {
+    if (!selected.some((edge) => edge.context?.project?.state === 'qualified-carried')) unresolved.push(issue('project-context', 'project-context-unresolved', 'Qualified work provenance is available, but no explicit qualified project identity/context is recoverable from its target context.'));
+    if (!selected.some((edge) => edge.context?.organization?.state === 'qualified-carried')) unresolved.push(issue('organization-context', 'organization-context-unresolved', 'Qualified work provenance is available, but no explicit qualified organization identity/context is recoverable from its target context.'));
+  }
+
+  if (!edges.length) return Object.freeze({
+    state: 'unresolved',
+    current: Object.freeze({ state: 'unresolved', sourceAnchors: Object.freeze([...frontierPaths]), relationSourceAnchors: Object.freeze([]), edges: Object.freeze([]) }),
+    context: Object.freeze({ state: 'unresolved', items: Object.freeze([]) }),
+    unresolved: Object.freeze(unresolved)
+  });
+
+  return Object.freeze({
+    state: selectionState,
+    current: Object.freeze({
+      state: exactQualified.length ? 'qualified' : lineageQualified.length ? 'qualified-via-selected-lineage' : 'unresolved',
+      sourceAnchors: Object.freeze([...frontierPaths]),
+      relationSourceAnchors: Object.freeze(selected.map((edge) => edge.source.resolvedPath)),
+      edges: Object.freeze(selected),
+      basis: selected.length ? (exactQualified.length ? 'exact-qualified-frontier-source' : 'qualified-declared-relation-source-on-selected-parent-lineage') : 'unresolved'
+    }),
+    edges: Object.freeze(edges),
+    reverseDiscovery: reverseIndex(edges.filter((edge) => edge.state === 'qualified')),
+    context: contextProjection(selected, selectionState),
+    unresolved: Object.freeze(unresolved),
+    boundary: 'Declared qualified edges only; selected Parent lineage may establish relevance but never creates or redirects an edge; reverse discovery is the same edge.'
+  });
+}
+
+function isCandidate(record = {}) {
+  return String(record.schemaId || '') === 'tiinex.relation.v1' && field(section(record.markdown, 'Relation Declaration'), 'Relation Family').toLowerCase() === FAMILY;
+}
+
+function relationEdge(record, byPath) {
+  const markdown = String(record.markdown || '');
+  let parsed;
+  try { parsed = parseArtifactMarkdown(markdown); } catch { return null; }
+  const findings = relationValidate(parsed);
+  const declaration = section(markdown, 'Relation Declaration');
+  const sourceRef = reference(section(markdown, 'Relation Source'), 'Source');
+  const targetRef = reference(section(markdown, 'Relation Target'), 'Target');
+  const source = resolveReference(sourceRef, record.path, byPath);
+  const target = resolveReference(targetRef, record.path, byPath);
+  const contractQualified = Boolean(record.hasContinuityContext && record.hasIntegrity && !findings.some((item) => item.severity === 'error'));
+  const state = contractQualified && source.state === 'qualified-carried' && target.state === 'qualified-carried' ? 'qualified' : 'unresolved';
+  const context = target.state === 'qualified-carried'
+    ? projectQualifiedWorkTargetContext(target, byPath)
+    : Object.freeze({ state: 'unresolved', project: unresolvedContext('project-context-unresolved'), organization: unresolvedContext('organization-context-unresolved'), contexts: Object.freeze([]), boundary: 'Target context is unavailable until the declared relation target is qualified-carried.' });
+  return Object.freeze({
+    state,
+    relationFamily: FAMILY,
+    relationType: field(declaration, 'Relation Type'),
+    direction: field(declaration, 'Relation Direction'),
+    scope: field(declaration, 'Relation Scope'),
+    source,
+    target,
+    context,
+    basis: Object.freeze({ relationArtifact: String(record.path || ''), schemaId: String(record.schemaId || ''), contractState: contractQualified ? 'qualified-carried-contract' : 'unqualified', integrityPresent: Boolean(record.hasIntegrity) })
+  });
+}
+
+function contextProjection(edges = [], state = 'unresolved') {
+  return Object.freeze({
+    state: edges.length ? (edges.every((edge) => edge.context?.state === 'qualified') ? 'qualified' : edges.some((edge) => edge.context?.state !== 'unresolved') ? 'qualified-partial' : 'unresolved') : 'unresolved',
+    selectionState: state,
+    items: Object.freeze(edges.map((edge) => Object.freeze({
+      relationType: edge.relationType,
+      targetPath: edge.target.resolvedPath,
+      project: edge.context?.project || unresolvedContext('project-context-unresolved'),
+      organization: edge.context?.organization || unresolvedContext('organization-context-unresolved'),
+      basis: edge.basis
+    }))),
+    boundary: 'Project/organization context requires explicit qualified target context; names/paths/Parent/chat do not manufacture membership.'
+  });
+}
+
+function resolveReference(ref = {}, ownerPath = '', byPath = new Map()) {
+  const target = String(ref.target || '').trim();
+  if (!target) return Object.freeze({ state: 'unresolved-missing-reference', label: ref.label || '', reference: '', resolvedPath: '' });
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) return Object.freeze({ state: 'external-not-loaded', label: ref.label || '', reference: target, resolvedPath: '' });
+  const path = resolvePath(target, ownerPath);
+  if (!path) return Object.freeze({ state: 'unresolved-reference', label: ref.label || '', reference: target, resolvedPath: '' });
+  const matches = byPath.get(path) || [];
+  if (matches.length !== 1) return Object.freeze({ state: matches.length ? 'ambiguous-carried-target' : 'not-carried', label: ref.label || '', reference: target, resolvedPath: path });
+  const record = matches[0];
+  const qualified = Boolean(record.hasContinuityContext && record.hasIntegrity);
+  return Object.freeze({ state: qualified ? 'qualified-carried' : 'present-unqualified', label: ref.label || record.title || '', reference: target, resolvedPath: path, title: String(record.title || ''), schemaId: String(record.schemaId || ''), summary: compact(record.summary || '', 180) });
+}
+
+function reverseIndex(edges = []) {
+  const groups = new Map();
+  for (const edge of edges) {
+    const key = edge.target.resolvedPath;
+    if (!groups.has(key)) groups.set(key, { target: edge.target, spawned: [] });
+    groups.get(key).spawned.push(Object.freeze({ source: edge.source, relationType: edge.relationType, direction: edge.direction, scope: edge.scope, basis: edge.basis }));
+  }
+  return Object.freeze([...groups.values()].map((entry) => Object.freeze({ target: entry.target, spawned: Object.freeze(entry.spawned) })));
+}
+
+function recordIndex(records = []) {
+  const map = new Map();
+  for (const record of records) { const key = String(record.path || ''); if (!map.has(key)) map.set(key, []); map.get(key).push(record); }
+  return map;
+}
+
+function resolvePath(reference = '', ownerPath = '') {
+  const raw = String(reference || '').split('#')[0].trim();
+  const cross = raw.match(/^([^:/\\]+)::(.+)$/);
+  const candidate = cross ? `${cross[1]}/${cross[2].replace(/^\/+/, '')}` : raw.startsWith('/') ? raw.slice(1) : posix.join(posix.dirname(String(ownerPath || '')), raw);
+  const normalized = posix.normalize(candidate).replace(/^\.\//, '');
+  return !normalized || normalized === '..' || normalized.startsWith('../') ? '' : normalized;
+}
+
+function reference(markdown = '', label = '') {
+  const raw = rawField(markdown, label);
+  const link = raw.match(/^\[([^\]]+)\]\(([^)]+)\)$/);
+  return Object.freeze({ label: link ? strip(link[1]) : strip(raw), target: link ? link[2].trim() : strip(raw) });
+}
+function section(markdown = '', heading = '') { const e = escape(heading); return String(markdown || '').match(new RegExp(`(?:^|\\n)##\\s+${e}\\s*\\r?\\n([\\s\\S]*?)(?=\\n##\\s+|\\n#\\s+Continuity Integrity|$)`, 'i'))?.[1]?.trim() || ''; }
+function rawField(markdown = '', label = '') { const e = escape(label); return String(markdown || '').match(new RegExp(`^\\s*-\\s+${e}:\\s*(.+)$`, 'mi'))?.[1]?.trim() || ''; }
+function field(markdown = '', label = '') { return strip(rawField(markdown, label)); }
+function strip(value = '') { return String(value || '').replace(/^\[([^\]]+)\]\([^)]+\)$/, '$1').replace(/[`*_]/g, '').trim(); }
+function compact(value = '', limit = 180) { const text = strip(String(value || '').replace(/\s+/g, ' ')); return text.length > limit ? `${text.slice(0, limit - 1).trimEnd()}…` : text; }
+function escape(value = '') { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function issue(slot, code, detail) { return Object.freeze({ slot, state: 'unresolved', code, detail }); }
+function unresolvedContext(code) { return Object.freeze({ state: 'unresolved', code, membershipClaim: false }); }

package/src/tooling/portable/handoff/carrierLineage.js

@@ -0,0 +1,214 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { canonicalC14nV2SelfState } from '../../../integrity/integrity.c14nV2.js';
+import { parseHandoffPackageV1, validatePackageFields } from './recipientV2.packageV1.contract.js';
+import { RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID } from './recipientV2.packageV1.constants.js';
+import { currentSchemaId } from './recipientV2.packageV1.shared.js';
+import { recipientV2FactsIndex } from './recipientV2.transportManifest.js';
+import { handoffCarrierProfileFromPackageContract, normalizeHandoffCarrierProfile } from './carrierProfile.js';
+
+export const HANDOFF_CARRIER_LINEAGE_SCHEMA_ID = 'tiinex.portable.handoff-carrier-lineage.v1';
+
+export function initialHandoffCarrierLineage() {
+  return freezeLineage({ mode: 'root', dimension: '001', parentDimension: '', parentPackageSha256: '', parentPackageFilename: '', major: '001', majorReason: 'initial carrier root', checkpointKind: 'major' });
+}
+
+export function continueHandoffCarrierLineage(parent = {}, siblingIndex = 1) {
+  const normalized = normalizeParentLineage(parent);
+  if (!normalized.dimension) throw new Error('portable.handoff-carrier-lineage.parent.unresolved');
+  const childIndex = normalizeSiblingIndex(siblingIndex);
+  return freezeLineage({
+    mode: 'continue',
+    dimension: `${normalized.dimension}-${childIndex}`,
+    parentDimension: normalized.dimension,
+    parentPackageSha256: normalized.packageSha256,
+    parentPackageFilename: normalized.packageFilename,
+    major: majorSegment(normalized.dimension),
+    majorReason: '',
+    checkpointKind: 'progression'
+  });
+}
+
+export function advanceHandoffCarrierMajor(parent = {}, reason = '') {
+  const normalized = normalizeParentLineage(parent);
+  if (!normalized.dimension) throw new Error('portable.handoff-carrier-lineage.parent.unresolved');
+  const majorReason = String(reason || '').trim();
+  if (!majorReason) throw new Error('portable.handoff-carrier-lineage.major-reason.required');
+  const currentMajor = Number.parseInt(majorSegment(normalized.dimension), 10);
+  if (!Number.isFinite(currentMajor) || currentMajor < 1 || currentMajor >= 999) throw new Error('portable.handoff-carrier-lineage.major.invalid');
+  const nextMajor = String(currentMajor + 1).padStart(3, '0');
+  return freezeLineage({
+    mode: 'major',
+    dimension: nextMajor,
+    parentDimension: normalized.dimension,
+    parentPackageSha256: normalized.packageSha256,
+    parentPackageFilename: normalized.packageFilename,
+    major: nextMajor,
+    majorReason,
+    checkpointKind: 'major'
+  });
+}
+
+export function normalizeHandoffCarrierLineage(value = null) {
+  if (!value || typeof value !== 'object') return initialHandoffCarrierLineage();
+  const dimension = normalizeDimension(value.dimension || '');
+  if (!dimension) return initialHandoffCarrierLineage();
+  const mode = ['root', 'continue', 'major'].includes(String(value.mode || '')) ? String(value.mode) : dimension.includes('-') ? 'continue' : 'root';
+  return freezeLineage({
+    mode,
+    dimension,
+    parentDimension: normalizeDimension(value.parentDimension || ''),
+    parentPackageSha256: normalizeSha256(value.parentPackageSha256 || ''),
+    parentPackageFilename: String(value.parentPackageFilename || ''),
+    major: majorSegment(dimension),
+    majorReason: String(value.majorReason || ''),
+    checkpointKind: String(value.checkpointKind || (mode === 'continue' ? 'progression' : 'major'))
+  });
+}
+
+export function parentHandoffCarrierLineageFromBundle(bundle = {}, options = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const factsIndex = recipientV2FactsIndex({ ...bundle, files });
+  if (factsIndex.transport?.state === 'invalid') throw new Error('portable.handoff-carrier-lineage.parent.transport-invalid');
+  const roots = [];
+  for (const file of files) {
+    if (!/\.md$/i.test(String(file.path || ''))) continue;
+    const facts = factsIndex.map.get(String(file.path || '')) || null;
+    if (facts?.role === 'package-root') roots.push({ file, facts });
+  }
+  let lineage = null;
+  if (roots.length === 1 && roots[0].facts.carrierLineage) lineage = normalizeHandoffCarrierLineage(roots[0].facts.carrierLineage);
+  if (!lineage) lineage = packageV1CarrierLineage(files);
+  if (!lineage) {
+    const dimensions = [...new Set((options.routeDimensions || []).map(normalizeDimension).filter(Boolean))];
+    if (dimensions.length === 1) lineage = normalizeHandoffCarrierLineage({ mode: dimensions[0].includes('-') ? 'continue' : 'root', dimension: dimensions[0] });
+  }
+  if (!lineage) throw new Error('portable.handoff-carrier-lineage.parent.unresolved');
+  return Object.freeze({
+    ...lineage,
+    packageSha256: normalizeSha256(options.packageSha256 || ''),
+    packageFilename: String(options.packageFilename || '')
+  });
+}
+
+export function parentHandoffCarrierProfileFromBundle(bundle = {}) {
+  const files = Array.isArray(bundle.files) ? bundle.files : [];
+  const candidates = files.filter((file) => {
+    if (!/\.md$/i.test(String(file.path || ''))) return false;
+    return currentSchemaId(decodeUtf8(packageFileBytes(file))) === RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID;
+  });
+  if (candidates.length !== 1) return normalizeHandoffCarrierProfile(null);
+  const file = candidates[0];
+  if (!/^\d{3}-tiinex-handoff-package\.trace\.md$/.test(String(file.path || ''))) return normalizeHandoffCarrierProfile(null);
+  const markdown = decodeUtf8(packageFileBytes(file));
+  if (canonicalC14nV2SelfState(markdown).state !== 'verified') return normalizeHandoffCarrierProfile(null);
+  const contract = parseHandoffPackageV1(markdown);
+  const findings = [];
+  validatePackageFields(contract, findings);
+  if (findings.some((item) => item.severity === 'error' && !String(item.code || '').includes('major-carrier-profile'))) return normalizeHandoffCarrierProfile(null);
+  return handoffCarrierProfileFromPackageContract(contract);
+}
+
+function packageV1CarrierLineage(files = []) {
+  const candidates = files.filter((file) => {
+    if (!/\.md$/i.test(String(file.path || ''))) return false;
+    return currentSchemaId(decodeUtf8(packageFileBytes(file))) === RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID;
+  });
+  if (candidates.length !== 1) return null;
+  const file = candidates[0];
+  if (!/^\d{3}-tiinex-handoff-package\.trace\.md$/.test(String(file.path || ''))) return null;
+  const markdown = decodeUtf8(packageFileBytes(file));
+  if (canonicalC14nV2SelfState(markdown).state !== 'verified') return null;
+  const contract = parseHandoffPackageV1(markdown);
+  const findings = [];
+  validatePackageFields(contract, findings);
+  if (findings.some((item) => item.severity === 'error')) return null;
+  return normalizeHandoffCarrierLineage({
+    mode: contract.carrierCheckpoint === 'major' ? 'major' : (contract.parentCarrierDimension ? 'continue' : 'root'),
+    dimension: contract.carrierDimension,
+    parentDimension: contract.parentCarrierDimension,
+    checkpointKind: contract.carrierCheckpoint,
+    majorReason: contract.majorReason
+  });
+}
+
+export function qualifyMajorCarrierReadiness(input = {}, lineage = {}) {
+  const profile = normalizeHandoffCarrierProfile(input.carrierProfile || null);
+  if (String(lineage.checkpointKind || '') !== 'major') return Object.freeze({
+    state: 'not-applicable',
+    profile,
+    completeWorkspaceCount: 0,
+    workspaceCount: 0,
+    requiredWorkspaceIds: profile.requiredMajorWorkspaceIds,
+    missingWorkspaceIds: Object.freeze([]),
+    reason: ''
+  });
+  const workspaces = [...(input.workspaceMaterializations || [])];
+  const requiredWorkspaceIds = profile.requiredMajorWorkspaceIds;
+  const completeWorkspaceIds = new Set(workspaces
+    .filter((workspace) => String(workspace.state || '') === 'complete' && String(workspace.completenessEvidence?.state || '') === 'qualified')
+    .map((workspace) => String(workspace.id || workspace.workspaceId || '').trim().toLowerCase())
+    .filter(Boolean));
+  const missingWorkspaceIds = Object.freeze(requiredWorkspaceIds.filter((workspaceId) => !completeWorkspaceIds.has(workspaceId)));
+  const complete = workspaces.filter((workspace) => String(workspace.state || '') === 'complete' && String(workspace.completenessEvidence?.state || '') === 'qualified').length;
+  const profileReady = profile.state === 'qualified';
+  const ready = workspaces.length > 0 && complete === workspaces.length && missingWorkspaceIds.length === 0;
+  return Object.freeze({
+    state: ready ? 'qualified' : 'blocked',
+    profile,
+    workspaceCount: workspaces.length,
+    completeWorkspaceCount: complete,
+    requiredWorkspaceIds,
+    missingWorkspaceIds,
+    reason: ready
+      ? (profileReady ? 'major-carrier-satisfies-explicit-carrier-profile' : 'major-carrier-has-complete-carried-workspaces-without-named-profile-requirements')
+      : 'major-carrier-requires-complete-carried-and-profile-declared-workspaces',
+    semanticClosure: lineage.mode === 'major' ? 'explicit-major-reason-caller-declared' : 'initial-root'
+  });
+}
+
+export function carrierLineageFromCliParent({ bundle = {}, parentPath = '', parentBytes = null, routeDimensions = [], qualifiedParentLineage = null, major = false, majorReason = '', siblingIndex = 1 } = {}) {
+  const bytes = parentBytes ? packageFileBytes({ data: parentBytes }) : new Uint8Array();
+  const packageIdentity = Object.freeze({
+    packageSha256: bytes.byteLength ? sha256Hex(bytes) : '',
+    packageFilename: parentPath ? portableBasename(parentPath) : ''
+  });
+  const qualifiedDimension = normalizeDimension(qualifiedParentLineage?.dimension || '');
+  const parent = qualifiedDimension
+    ? Object.freeze({ ...normalizeHandoffCarrierLineage(qualifiedParentLineage), ...packageIdentity })
+    : parentHandoffCarrierLineageFromBundle(bundle, { routeDimensions, ...packageIdentity });
+  return major ? advanceHandoffCarrierMajor(parent, majorReason) : continueHandoffCarrierLineage(parent, siblingIndex);
+}
+
+function normalizeSiblingIndex(value = 1) {
+  const number = Number.parseInt(value, 10);
+  if (!Number.isFinite(number) || number < 1 || number > 9999) throw new Error('portable.handoff-carrier-lineage.sibling-index.invalid');
+  return number;
+}
+
+function freezeLineage(value = {}) {
+  return Object.freeze({
+    schema: HANDOFF_CARRIER_LINEAGE_SCHEMA_ID,
+    version: 1,
+    mode: String(value.mode || ''),
+    dimension: normalizeDimension(value.dimension || ''),
+    major: majorSegment(value.dimension || ''),
+    parentDimension: normalizeDimension(value.parentDimension || ''),
+    parentPackageSha256: normalizeSha256(value.parentPackageSha256 || ''),
+    parentPackageFilename: String(value.parentPackageFilename || ''),
+    checkpointKind: String(value.checkpointKind || ''),
+    majorReason: String(value.majorReason || ''),
+    authority: 'human-progress-projection-only',
+    boundary: 'Carrier lineage is a compact human progress/retention projection. It never replaces artifact Parent/Trace/Origin, Handoff authority, or source truth. Major checkpoints require complete carried Workspace snapshots and explicit semantic closure intent.'
+  });
+}
+function normalizeParentLineage(value = {}) {
+  const explicitDimension = String(value?.dimension || '').trim();
+  if (explicitDimension && !normalizeDimension(explicitDimension)) return Object.freeze({ dimension: '', packageSha256: normalizeSha256(value.packageSha256 || value.parentPackageSha256 || ''), packageFilename: String(value.packageFilename || value.parentPackageFilename || '') });
+  const lineage = normalizeHandoffCarrierLineage(value);
+  return Object.freeze({ ...lineage, packageSha256: normalizeSha256(value.packageSha256 || value.parentPackageSha256 || ''), packageFilename: String(value.packageFilename || value.parentPackageFilename || '') });
+}
+function normalizeDimension(value = '') { const v = String(value || '').trim(); return /^\d{3}(?:-\d+)*$/.test(v) ? v : ''; }
+function majorSegment(value = '') { return normalizeDimension(value).split('-')[0] || ''; }
+function portableBasename(value = '') { return String(value || '').replace(/\\/g, '/').split('/').filter(Boolean).pop() || ''; }
+function normalizeSha256(value = '') { const v = String(value || '').trim().toLowerCase(); return /^[a-f0-9]{64}$/.test(v) ? v : ''; }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }

package/src/tooling/portable/handoff/carrierProfile.js

@@ -0,0 +1,54 @@
+export const HANDOFF_CARRIER_PROFILE_SCHEMA_ID = 'tiinex.portable.handoff-carrier-profile.v1';
+
+export function normalizeHandoffCarrierProfile(value = null, options = {}) {
+  const raw = value && typeof value === 'object' ? value : {};
+  const id = String(raw.id || raw.profileId || raw.name || '').trim();
+  const requiredMajorWorkspaceIds = normalizeWorkspaceIds(
+    raw.requiredMajorWorkspaceIds
+      || raw.requiredWorkspaceIds
+      || raw.majorRequiredWorkspaceIds
+      || []
+  );
+  const source = String(raw.source || options.source || '').trim();
+  const state = id ? 'qualified' : 'unresolved';
+  return Object.freeze({
+    schema: HANDOFF_CARRIER_PROFILE_SCHEMA_ID,
+    state,
+    id,
+    requiredMajorWorkspaceIds,
+    source,
+    boundary: 'Carrier profile data is explicit project/operator/package policy. Workspace identifiers have no universal meaning in generic Handoff mechanics.'
+  });
+}
+
+export function handoffCarrierProfileFromPackageContract(contract = {}) {
+  return normalizeHandoffCarrierProfile({
+    id: contract.carrierProfileId || '',
+    requiredMajorWorkspaceIds: contract.requiredMajorWorkspaceIds || [],
+    source: contract.carrierProfileId ? 'declared-package-contract' : ''
+  });
+}
+
+export function normalizeWorkspaceIds(value = []) {
+  if (!Array.isArray(value) && String(value || '').trim().toLowerCase() === 'none') return Object.freeze([]);
+  const list = Array.isArray(value)
+    ? value
+    : String(value || '').split(',');
+  const seen = new Set();
+  const out = [];
+  for (const entry of list) {
+    const id = normalizeWorkspaceId(entry);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return Object.freeze(out);
+}
+
+function normalizeWorkspaceId(value = '') {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}