@tiinex/core 0.1.1

package/src/tooling/portable/handoff/workspaceCarrier.manufacture.js

@@ -0,0 +1,93 @@
+import { finalizeFile } from '../../../export/package.fileMap.js';
+import { exportFileMapZipUint8Array } from '../../../export/package.zip.js';
+import { summarizePortableFindings } from '../findings.js';
+import { inspectPortableToolingBootstrap } from './toolingBootstrap.js';
+import { qualifyDirectWorkspaceForArchive, indexWorkspaceTargetDeclarations } from './materialClosure.archiveV2.workspace.js';
+import { renderRecipientV2Pointer } from './recipientV2.artifacts.js';
+import { RECIPIENT_V2_READ_PATH, RECIPIENT_V2_FORMAT_ID } from './recipientV2.topology.js';
+import { recipientV2WorkspaceEntryCurrentRead } from './recipientV2.entryContract.js';
+import { recipientV2TransportFacts } from './recipientV2.transportManifest.js';
+import { buildRecipientV2BootstrapCarrier, recipientV2ParentAuthority } from './recipientV2.topology.workspaces.js';
+import { safeToken, finding } from './recipientV2.topology.materials.js';
+import { RECIPIENT_V2_PACKAGE_V1_ROOT_PATH, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET } from './recipientV2.packageV1.constants.js';
+import { renderHandoffPackageV1, WORKSPACE_PACKAGE_ROLE } from './recipientV2.packageV1.contract.js';
+import { exactFile, workspaceSchemaTarget, deepFreeze } from './recipientV2.packageV1.shared.js';
+import { inspectRecipientFacingV2Topology, roundTripRecipientFacingV2Topology } from './recipientV2.inspect.js';
+
+export function manufactureRecipientRelativeWorkspacePackage(input = {}) {
+  const findings = [];
+  const targetByWorkspace = indexWorkspaceTargetDeclarations(input.workspaceTargets || []);
+  const workspaces = [...(input.workspaceMaterializations || [])].sort((a, b) => String(a.id || '').localeCompare(String(b.id || '')));
+  const plans = [];
+  for (const [index, raw] of workspaces.entries()) {
+    const id = String(raw.id || '').trim();
+    const wrapper = Object.freeze({ ...raw, materialization: String(raw.state || ''), qualification: 'qualified', correlationStatus: 'qualified' });
+    const qualified = qualifyDirectWorkspaceForArchive(wrapper, raw, targetByWorkspace.get(id) || [], []);
+    findings.push(...(qualified.findings || []));
+    if (qualified.status !== 'qualified' || !qualified.target) continue;
+    const prefix = `001-${index + 3}`;
+    const slug = safeToken(id);
+    const archiveData = exportFileMapZipUint8Array((qualified.entries || []).map((entry) => ({ path: entry.path, data: entry.data })), 'portable.workspace-carrier.workspace-archive.path.invalid');
+    const workspacePath = `${prefix}-${slug}.workspace.md`;
+    const archivePath = `${prefix}-${slug}.workspace.zip`;
+    const workspaceFile = exactFile(workspacePath, qualified.target.data, 'recipient-v2-package-v1-exact-workspace-artifact', 'text/markdown');
+    const archiveFile = exactFile(archivePath, archiveData, 'recipient-v2-package-v1-complete-workspace-snapshot', 'application/zip');
+    plans.push(Object.freeze({ id, raw, qualified, workspaceFile, archiveFile, projection: Object.freeze({ workspaceId: id, workspacePath, archivePath, sourceWorkspaceTargetInnerPath: qualified.target.path, sourceWorkspaceTargetSha256: workspaceFile.sha256, archiveSha256: archiveFile.sha256, archiveBytes: archiveFile.bytes, coverage: 'complete' }) }));
+  }
+  if (!plans.length || findings.some((item) => item.severity === 'error')) return blocked(findings);
+  const createdAt = String(input.createdAt || '1970-01-01 00:00:00');
+  const bootstrapSource = (input.additionalTransportFiles || []).filter((file) => String(file.path || '').startsWith('tiinex.bootstrap/'));
+  const packageFile = finalizeFile({
+    path: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH,
+    kind: 'tiinex-handoff-package-artifact',
+    logicalKind: 'recipient-v2-package-v1-root',
+    mediaType: 'text/markdown',
+    content: renderHandoffPackageV1({ createdAt, packageRole: WORKSPACE_PACKAGE_ROLE, workspaces: plans.map((plan) => plan.projection), carrierLineage: input.carrierLineage || {}, carrierProfile: input.carrierProfile || null, startPath: RECIPIENT_V2_READ_PATH, bootstrapPath: bootstrapSource.length ? '001-2-bootstrap.trace.md' : '' })
+  });
+  const packageParent = recipientV2ParentAuthority(packageFile, RECIPIENT_V2_PACKAGE_V1_SCHEMA_ID, RECIPIENT_V2_PACKAGE_V1_SCHEMA_TARGET, createdAt);
+  const files = [packageFile, ...plans.flatMap((plan) => [plan.workspaceFile, plan.archiveFile])];
+  let bootstrap = null;
+  if (bootstrapSource.length) {
+    bootstrap = buildRecipientV2BootstrapCarrier(bootstrapSource, createdAt, findings, packageParent);
+    if (bootstrap) files.push(bootstrap.artifact, bootstrap.payload);
+  }
+  const readFacts = recipientV2TransportFacts('recovery-orientation', {
+    format: 'tiinex-recipient-facing-handoff-package-v1',
+    packageRole: WORKSPACE_PACKAGE_ROLE,
+    packageRootPath: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH,
+    entryArtifactPath: RECIPIENT_V2_READ_PATH,
+    artifactSurface: 'tiinex.handoff.package.v1-plus-exact-complete-workspace-snapshots',
+    routeAuthority: 'none', routeSelectionAuthority: 'none', siblingRouteInference: false,
+    carrierLineage: input.carrierLineage || null, pathParentProjection: true, pathAuthority: false
+  });
+  const readFile = finalizeFile({
+    path: RECIPIENT_V2_READ_PATH, kind: 'handoff-recovery-pointer', logicalKind: 'recipient-v2-package-v1-workspace-recovery-orientation', mediaType: 'text/markdown', transportFacts: readFacts,
+    content: renderRecipientV2Pointer({ createdAt, parent: packageParent, role: 'recovery-orientation', title: 'READ BEFORE PROCEEDING — Tiinex Workspace Carrier', summary: 'Qualified recovery/orientation Pointer for the pointerless package-v1 Workspace carrier.', prose: 'Read this Start artifact first and qualify the declared Tooling bootstrap. This carrier intentionally exposes no Handoff route or Continue-from Pointer; do not infer semantic Handoff state from Workspace carriage.', currentRead: [...recipientV2WorkspaceEntryCurrentRead(), { label: 'Package Artifact', value: `[Workspace Package](${RECIPIENT_V2_PACKAGE_V1_ROOT_PATH})` }, { label: 'Carrier Dimension', value: `\`${String(input.carrierLineage?.dimension || '001')}\`` }], destinations: [{ label: 'Workspace Package contract', target: RECIPIENT_V2_PACKAGE_V1_ROOT_PATH }, ...(bootstrap ? [{ label: 'Portable Tooling bootstrap', target: bootstrap.projection.artifactPath }] : []), ...plans.map((plan) => ({ label: `Workspace ${plan.id}`, target: plan.projection.workspacePath }))], facts: readFacts })
+  });
+  files.push(readFile);
+  const sortedFiles = Object.freeze([...files].sort((a, b) => String(a.path || '').localeCompare(String(b.path || ''))));
+  const bundle = deepFreeze({ status: 'ready', files: sortedFiles, handoffClosure: null, transportFormat: RECIPIENT_V2_FORMAT_ID, boundary: 'Pointerless recipient-facing Workspace carrier. Exact carried Workspace source bytes retain authority; carrier placement creates no Handoff semantics.' });
+  const inspection = inspectRecipientFacingV2Topology(bundle);
+  const roundtrip = input.verifyRoundtrip === false ? null : roundTripRecipientFacingV2Topology(bundle, inspection);
+  const toolingBootstrapInspection = inspection.bootstrapInspection || inspectPortableToolingBootstrap({ files: bootstrapSource });
+  const allFindings = [...findings, ...(inspection.findings || []), ...(roundtrip?.findings || [])];
+  const ready = inspection.status === 'valid' && (!roundtrip || roundtrip.status === 'passed') && toolingBootstrapInspection.status === 'valid' && !allFindings.some((item) => item.severity === 'error');
+  const carrierProjection = inspection.carrierProjection || workspaceProjection(plans, input.carrierLineage || {});
+  return deepFreeze({
+    schema: 'tiinex.portable.handoff-manufacturing.v2', status: ready ? 'ready' : 'blocked', executable: ready, transportExecutable: ready,
+    verification: Object.freeze({ baselineManufacture: 'ready', manufacturePath: 'direct-qualified-workspace-to-pointerless-package-v1', packageInspection: inspection.status, closureInspection: 'not-applicable', carrierInspection: inspection.status, selectedHandoffConformance: 'not-applicable', pointerEntrypointInspection: 'not-applicable', coldConsumerEntrypointInspection: inspection.status, companionInspection: 'not-applicable', roundtrip: roundtrip?.status || 'not-requested', toolingBootstrap: toolingBootstrapInspection.status }),
+    plan: Object.freeze({ status: ready ? 'ready' : 'blocked', requiredClosureReady: true, semanticHandoffStatus: 'not-declared', workspaceMaterializations: Object.freeze(workspaces), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]) }) }),
+    bundle, inspection, carrierProjection, roundtrip, toolingBootstrapInspection, toolingBootstrap: input.toolingBootstrap || null, carrierLineage: input.carrierLineage || carrierProjection.lineage || null, manufacturingEvidence: input.manufacturingEvidence || null,
+    findings: Object.freeze(allFindings), findingSummary: summarizePortableFindings(allFindings), operationBoundary: Object.freeze({ sourceMutation: false, remoteWrite: false, handoffSemantics: false }),
+    boundary: 'Canonical pointerless Workspace-carrier manufacture only. No route, Handoff, Role, current-work, transfer, participation, acceptance, completion, or publication authority is created.'
+  });
+}
+
+function workspaceProjection(plans, lineage) {
+  const workspaces = plans.map((plan) => Object.freeze({ id: plan.id, title: String(plan.raw.title || plan.id), slug: safeToken(plan.id), qualification: 'qualified' }));
+  return deepFreeze({ schema: 'tiinex.portable.handoff-carrier-projection.v1', version: 1, status: 'ready', mode: 'workspace', lineage, workspaces: Object.freeze(workspaces), workspace: workspaces[0] || Object.freeze({ id: '', title: '', slug: '', qualification: 'unresolved' }), selection: Object.freeze({ policy: 'none', qualifiedRouteCount: 0, implicitRouteId: '', packageRole: WORKSPACE_PACKAGE_ROLE }), routes: Object.freeze([]), authority: Object.freeze({ semanticAuthority: 'none', filenameAuthority: false, dimensionalParentAuthority: false, routeSelectionAuthority: 'none' }), findings: Object.freeze([]) });
+}
+function blocked(findings = []) {
+  const all = findings.length ? findings : [finding('error', 'portable.workspace-carrier.manufacture.blocked', 'Pointerless Workspace carrier manufacture failed closed.')];
+  return deepFreeze({ schema: 'tiinex.portable.handoff-manufacturing.v2', status: 'blocked', executable: false, transportExecutable: false, verification: Object.freeze({ manufacturePath: 'direct-qualified-workspace-to-pointerless-package-v1' }), plan: Object.freeze({ status: 'blocked', workspaceMaterializations: Object.freeze([]), requirements: Object.freeze({ required: Object.freeze([]), reference: Object.freeze([]) }) }), bundle: null, inspection: null, carrierProjection: Object.freeze({ schema: 'tiinex.portable.handoff-carrier-projection.v1', status: 'blocked', mode: 'workspace', workspaces: Object.freeze([]), routes: Object.freeze([]), findings: Object.freeze(all) }), findings: Object.freeze(all), findingSummary: summarizePortableFindings(all), boundary: 'Failed closed before emitting pointerless Workspace carrier bytes.' });
+}

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

@@ -0,0 +1,142 @@
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { parseWorkspaceEntrypoints, normalizeRepositoryIdentity } from './workspaceSourceIdentity.js';
+
+export const PORTABLE_WORKSPACE_LANDING_PLAN_SCHEMA_ID = 'tiinex.portable.workspace-landing-plan.v1';
+
+export function projectPortableWorkspaceLandingPlan(input = {}) {
+  const inspection = inspectRecipientFacingV2Topology(input.bundle || input.package || input);
+  const findings = [];
+  if (String(inspection.status || '') !== 'valid') {
+    findings.push(finding('error', 'portable.workspace-landing.package-unqualified', 'Workspace landing planning requires one independently qualified recipient Handoff package.'));
+    return result('blocked', inspection, [], findings, input);
+  }
+  const repositories = normalizeRepositories(input.repositories || []);
+  const selections = normalizeSelections(input.selections || {});
+  const requestedIds = new Set([...(input.workspaceIds || input.selectedWorkspaceIds || [])].map(normalizeId).filter(Boolean));
+  const providerById = new Map((inspection.workspaceByteProvider?.workspaces || []).map((provider) => [normalizeId(provider.id), provider]));
+  const plans = [];
+  for (const workspace of inspection.workspaces || []) {
+    const id = normalizeId(workspace.workspaceId);
+    if (requestedIds.size && !requestedIds.has(id)) continue;
+    plans.push(planWorkspace({ workspace, provider: providerById.get(id), repositories, selectionId: selections[id] || '', explicit: requestedIds.size > 0 }, findings));
+  }
+  if (requestedIds.size) {
+    for (const id of requestedIds) if (!plans.some((item) => item.workspaceId === id)) findings.push(finding('error', 'portable.workspace-landing.workspace-unresolved', 'An explicitly requested Workspace is not present in the qualified carrier.', { workspaceId: id }));
+  }
+  const affected = plans.filter((item) => item.state === 'ready');
+  const blocking = findings.some((item) => item.severity === 'error');
+  if (!affected.length) findings.push(finding('error', 'portable.workspace-landing.no-qualified-targets', 'No qualified local repository target is ready for landing.'));
+  return result(blocking || !affected.length ? 'blocked' : 'ready', inspection, plans, findings, input);
+}
+
+function planWorkspace({ workspace = {}, provider = null, repositories = [], selectionId = '', explicit = false } = {}, findings = []) {
+  const workspaceId = normalizeId(workspace.workspaceId);
+  const base = {
+    workspaceId,
+    title: String(workspace.title || workspaceId),
+    coverage: String(workspace.coverage || ''),
+    archivePackagePath: String(workspace.workspaceArchivePath || provider?.archive?.packagePath || ''),
+    archiveBytes: Number(provider?.archive?.bytes || 0),
+    archiveSha256: String(provider?.archive?.digest?.value || ''),
+    workspaceArtifactInnerPath: String(workspace.sourceWorkspaceTargetInnerPath || '')
+  };
+  if (!provider || provider.state !== 'qualified' || provider.mode !== 'archive') {
+    if (explicit) findings.push(finding('error', 'portable.workspace-landing.workspace-provider-unqualified', 'Requested Workspace lacks a qualified archive byte provider.', { workspaceId }));
+    return freeze({ ...base, state: 'unavailable', source: null, repository: null, reasons: ['workspace-provider-unqualified'] });
+  }
+  const target = (provider.entries || []).find((entry) => String(entry.path || '') === base.workspaceArtifactInnerPath);
+  if (!target?.data) {
+    if (explicit) findings.push(finding('error', 'portable.workspace-landing.workspace-target-unavailable', 'Requested Workspace durable source artifact bytes are unavailable.', { workspaceId }));
+    return freeze({ ...base, state: 'unavailable', source: null, repository: null, reasons: ['workspace-target-unavailable'] });
+  }
+  let markdown = '';
+  try { markdown = new TextDecoder('utf-8', { fatal: true }).decode(byteView(target.data)); }
+  catch {
+    findings.push(finding('error', 'portable.workspace-landing.workspace-target-nontext', 'Qualified Workspace target could not be decoded as UTF-8 Markdown.', { workspaceId }));
+    return freeze({ ...base, state: 'unavailable', source: null, repository: null, reasons: ['workspace-target-nontext'] });
+  }
+  const sources = parseWorkspaceEntrypoints(markdown);
+  const repoSources = sources.filter((source) => normalizeRepositoryIdentity(source.repository));
+  const sourceIdentities = [...new Set(repoSources.map((source) => normalizeRepositoryIdentity(source.repository)))];
+  if (sourceIdentities.length !== 1) {
+    if (explicit) findings.push(finding('error', sourceIdentities.length ? 'portable.workspace-landing.workspace-repository-ambiguous' : 'portable.workspace-landing.workspace-repository-missing', 'Requested Workspace must expose exactly one explicit repository identity before it can target a local Git repository.', { workspaceId, count: sourceIdentities.length }));
+    return freeze({ ...base, state: 'not-targetable', source: repoSources[0] || null, repository: null, reasons: [sourceIdentities.length ? 'workspace-repository-ambiguous' : 'workspace-repository-missing'] });
+  }
+  const source = repoSources.find((item) => normalizeRepositoryIdentity(item.repository) === sourceIdentities[0]) || repoSources[0];
+  const matches = repositories.filter((repo) => repo.repositoryIdentity === sourceIdentities[0]);
+  let selected = selectionId ? repositories.find((repo) => repo.id === selectionId) || null : matches.length === 1 ? matches[0] : null;
+  if (selectionId && (!selected || selected.repositoryIdentity !== sourceIdentities[0])) {
+    findings.push(finding('error', 'portable.workspace-landing.selection-identity-mismatch', 'Explicit local repository selection does not match the qualified Workspace repository identity.', { workspaceId, selectionId, repository: source.repository }));
+    selected = null;
+  }
+  if (!selected) {
+    if (matches.length > 1) findings.push(finding('error', 'portable.workspace-landing.local-repository-ambiguous', 'Multiple local repositories match the same qualified Workspace repository identity; explicit selection is required.', { workspaceId, repository: source.repository, count: matches.length }));
+    else if (explicit || selectionId) findings.push(finding('error', 'portable.workspace-landing.local-repository-unmatched', 'Requested Workspace has no matching local Git repository.', { workspaceId, repository: source.repository }));
+    return freeze({ ...base, state: matches.length > 1 ? 'ambiguous' : 'unmatched', source, repository: null, candidateRepositoryIds: matches.map((item) => item.id), reasons: [matches.length > 1 ? 'local-repository-ambiguous' : 'local-repository-unmatched'] });
+  }
+  const reasons = [];
+  if (selected.clean !== true) {
+    reasons.push(selected.clean === false ? 'dirty-worktree' : 'clean-state-unresolved');
+    findings.push(finding('error', selected.clean === false ? 'portable.workspace-landing.local-repository-dirty' : 'portable.workspace-landing.local-repository-clean-state-unresolved', 'Landing requires a clean target worktree except ignored local material.', { workspaceId, repositoryId: selected.id }));
+  }
+  const declaredRef = String(source.ref || '').trim();
+  const branch = String(selected.branch || '').trim();
+  if (declaredRef && branch && declaredRef !== branch) {
+    reasons.push('ref-branch-mismatch');
+    findings.push(finding('error', 'portable.workspace-landing.ref-branch-mismatch', 'Local repository branch differs from the qualified Workspace source ref safety constraint.', { workspaceId, repositoryId: selected.id, declaredRef, branch }));
+  }
+  return freeze({
+    ...base,
+    state: reasons.length ? 'blocked' : 'ready',
+    source,
+    repository: freeze({ id: selected.id, root: selected.root, repository: selected.repository, repositoryIdentity: selected.repositoryIdentity, branch, clean: selected.clean }),
+    reasons
+  });
+}
+
+function result(status, inspection, workspaces, findings, input) {
+  const affected = workspaces.filter((item) => item.state === 'ready');
+  const untouched = workspaces.filter((item) => item.state !== 'ready');
+  return freeze({
+    schema: PORTABLE_WORKSPACE_LANDING_PLAN_SCHEMA_ID,
+    status,
+    packageQualification: String(inspection.status || 'invalid'),
+    selectionMode: (input.workspaceIds || input.selectedWorkspaceIds || []).length ? 'explicit-workspace-set' : 'qualified-repository-match-discovery',
+    workspaces: freeze(workspaces),
+    affected: freeze(affected),
+    unaffected: freeze(untouched),
+    confirmation: freeze({
+      required: affected.length > 0,
+      repositoryCount: affected.length,
+      repositoryRoots: freeze(affected.map((item) => String(item.repository?.root || '')).filter(Boolean)),
+      statement: affected.length ? `Replace qualified non-ignored Workspace source in ${affected.length} local Git repositor${affected.length === 1 ? 'y' : 'ies'}; preserve .git and unrelated ignored local material; do not commit or push.` : '',
+      authority: 'explicit-human-host-confirmation-only'
+    }),
+    operationBoundary: freeze({ sourceMutation: false, remoteWrite: false, commit: false, push: false, acceptance: false }),
+    findings: freeze(findings),
+    boundary: 'Planning-only projection from one qualified Handoff package plus explicit local Git repository facts. Repository/ref matching is an operational safety constraint, not semantic authority. The plan does not extract, write, commit, push, accept, or complete any Workspace.'
+  });
+}
+
+function normalizeRepositories(value = []) {
+  const list = Array.isArray(value) ? value : value?.repositories || [];
+  return freeze(list.map((item, index) => {
+    const repository = String(item?.repository || item?.remote || item?.remoteUrl || '').trim();
+    return freeze({
+      id: String(item?.id || `repo-${index + 1}`),
+      root: String(item?.root || item?.path || ''),
+      repository,
+      repositoryIdentity: normalizeRepositoryIdentity(repository),
+      branch: String(item?.branch || ''),
+      clean: item?.clean === true ? true : item?.clean === false ? false : null
+    });
+  }));
+}
+function normalizeSelections(value = {}) {
+  const source = value?.selections && typeof value.selections === 'object' ? value.selections : value;
+  return Object.fromEntries(Object.entries(source || {}).map(([key, selected]) => [normalizeId(key), String(selected || '')]).filter(([key, selected]) => key && selected));
+}
+function normalizeId(value = '') { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''); }
+function byteView(value) { if (value instanceof Uint8Array) return value; if (ArrayBuffer.isView(value)) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength); if (value instanceof ArrayBuffer) return new Uint8Array(value); throw new Error('portable.workspace-landing.bytes-unavailable'); }
+function finding(severity, code, message, context = {}) { return freeze({ severity, code, message, context: freeze({ ...context }) }); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map((item) => freeze(item))); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }

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

@@ -0,0 +1,105 @@
+import { parseArtifactMarkdown } from '../../../artifacts/artifact.parse.js';
+import { auditPortableRecord } from '../audit/audit.capability.js';
+import { normalizeRepositoryIdentity, parseWorkspaceEntrypoints } from './workspaceSourceIdentity.js';
+import { sha256Hex, utf8Bytes } from '../../../export/package.bytes.js';
+
+export const PORTABLE_WORKSPACE_PACKAGE_SOURCES_SCHEMA_ID = 'tiinex.portable.workspace-package-sources.v1';
+
+export function projectQualifiedWorkspacePackageSources(input = {}) {
+  const records = normalizeRecords(input);
+  const findings = [];
+  const candidates = [];
+  const repositories = normalizeRepositories(input.repositories || input.localRepositories || []);
+  for (const record of records) {
+    let parsed;
+    try { parsed = parseArtifactMarkdown(record.markdown); } catch { continue; }
+    if (String(parsed.envelope?.current?.schema?.id || '') !== 'tiinex.workspace.v1') continue;
+    const audit = auditPortableRecord({ ...record, title: parsed.title || '', schemaId: 'tiinex.workspace.v1', currentSchemaId: 'tiinex.workspace.v1', parent: parsed.envelope?.parent || null });
+    if (audit.status !== 'readable' || audit.qualification?.exact !== true || (audit.findings || []).some((item) => item.severity === 'error')) {
+      findings.push(finding('warning', 'portable.workspace-package-source.unqualified', 'A local Workspace artifact was ignored because exact shared audit did not qualify it.', { path: record.path }));
+      continue;
+    }
+    const entrypoints = parseWorkspaceEntrypoints(record.markdown);
+    const repositorySources = entrypoints.filter((item) => normalizeRepositoryIdentity(item.repository));
+    const localDirectorySources = entrypoints.filter((item) => String(item.sourceKind || '').trim().toLowerCase() === 'local-directory' && !normalizeRepositoryIdentity(item.repository));
+    const identities = [...new Set(repositorySources.map((item) => normalizeRepositoryIdentity(item.repository)).filter(Boolean))];
+    let source = null;
+    let repositoryIdentity = '';
+    let localMatches = [];
+    if (identities.length === 1) {
+      repositoryIdentity = identities[0];
+      source = repositorySources.find((item) => normalizeRepositoryIdentity(item.repository) === repositoryIdentity) || repositorySources[0];
+      localMatches = repositories.filter((item) => item.repositoryIdentity === repositoryIdentity);
+      if (repositories.length && localMatches.length !== 1) {
+        findings.push(finding('warning', localMatches.length ? 'portable.workspace-package-source.local-repository-ambiguous' : 'portable.workspace-package-source.local-repository-unmatched', 'A qualified Workspace package source was not exposed because explicit local Git facts did not produce exactly one repository-identity match.', { path: record.path, repositoryIdentity, matchCount: localMatches.length }));
+        continue;
+      }
+    } else if (identities.length > 1) {
+      findings.push(finding('warning', 'portable.workspace-package-source.repository-ambiguous', 'A qualified Workspace package source must not expose multiple repository identities for one package snapshot.', { path: record.path, count: identities.length }));
+      continue;
+    } else if (localDirectorySources.length === 1) {
+      source = localDirectorySources[0];
+      localMatches = repositories.length === 1 ? repositories : [];
+    } else {
+      findings.push(finding('warning', localDirectorySources.length ? 'portable.workspace-package-source.local-directory-ambiguous' : 'portable.workspace-package-source.source-missing', 'A qualified Workspace package source must expose exactly one repository-backed snapshot or one explicit local-directory snapshot.', { path: record.path, repositoryCount: identities.length, localDirectoryCount: localDirectorySources.length }));
+      continue;
+    }
+    const workspaceTargetPath = norm(record.path || record.id || '');
+    candidates.push({
+      baseWorkspaceId: semanticWorkspaceArtifactId(workspaceTargetPath),
+      workspaceTargetPath,
+      title: String(parsed.title || ''),
+      qualification: 'qualified-exact',
+      repository: String(source?.repository || ''),
+      repositoryIdentity,
+      ref: String(source?.ref || ''),
+      rootPath: String(source?.rootPath || '.'),
+      sourceKind: String(source?.sourceKind || ''),
+      localRepository: localMatches.length === 1 ? localMatches[0] : null
+    });
+  }
+  const qualifiedCandidates = disambiguateWorkspaceIds(candidates);
+  return freeze({
+    schema: PORTABLE_WORKSPACE_PACKAGE_SOURCES_SCHEMA_ID,
+    status: 'ready',
+    candidates: qualifiedCandidates,
+    findings,
+    operationBoundary: { sourceMutation: false, remoteWrite: false, manufacture: false },
+    boundary: 'Projects exact qualified local Workspace artifacts into package-builder source candidates. A Workspace may declare one repository-backed snapshot or one explicit local-directory snapshot; workspaceId remains a stable package-local label derived from the qualified Workspace artifact identity, independently of any physical repository identity. Host Git facts are operational context only and create no semantic Workspace authority.'
+  });
+}
+
+function normalizeRepositories(value = []) {
+  return (Array.isArray(value) ? value : []).map((item) => freeze({
+    id: String(item?.id || item?.root || ''),
+    root: String(item?.root || ''),
+    repository: String(item?.repository || ''),
+    repositoryIdentity: normalizeRepositoryIdentity(item?.repository || item?.repositoryIdentity || ''),
+    branch: String(item?.branch || ''),
+    clean: item?.clean === true
+  })).filter((item) => item.repositoryIdentity);
+}
+function semanticWorkspaceArtifactId(workspaceTargetPath = '') {
+  const basename = norm(workspaceTargetPath).split('/').filter(Boolean).at(-1) || 'workspace.workspace.md';
+  const raw = basename.replace(/\.workspace\.md$/i, '').replace(/^tiinex-/i, '') || 'workspace';
+  const token = raw.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return token || 'workspace';
+}
+function disambiguateWorkspaceIds(candidates = []) {
+  const counts = new Map();
+  for (const candidate of candidates) counts.set(candidate.baseWorkspaceId, (counts.get(candidate.baseWorkspaceId) || 0) + 1);
+  return candidates.map((candidate) => {
+    const collided = (counts.get(candidate.baseWorkspaceId) || 0) > 1;
+    const suffix = collided ? sha256Hex(utf8Bytes(candidate.workspaceTargetPath)).slice(0, 8) : '';
+    const workspaceId = collided ? `${candidate.baseWorkspaceId}--${suffix}` : candidate.baseWorkspaceId;
+    const { baseWorkspaceId, ...rest } = candidate;
+    return freeze({ workspaceId, ...rest });
+  });
+}
+function normalizeRecords(input = {}) {
+  if (Array.isArray(input.records)) return input.records;
+  return (Array.isArray(input.files) ? input.files : []).filter((item) => typeof item?.content === 'string').map((item) => ({ id: String(item.path || ''), path: String(item.path || ''), markdown: String(item.content || ''), sourceMode: item.sourceMode || '' }));
+}
+function norm(value = '') { return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, ''); }
+function finding(severity, code, message, context = {}) { return freeze({ severity, code, message, context }); }
+function freeze(value) { if (Array.isArray(value)) return Object.freeze(value.map(freeze)); if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, freeze(item)]))); }

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

@@ -0,0 +1,10 @@
+export const SHARED_ROUTE_REQUIRED_CONTEXT_BOUNDARY = 'Shared-route recipient grounding proof only. Every Required Context item must resolve to exact carried package bytes; Reference Context is intentionally excluded from this blocking projection.';
+
+export function parseWorkspaceQualifiedReference(value = '') {
+  const match = String(value || '').trim().match(/^([a-zA-Z0-9._-]+)::(.+)$/);
+  if (!match) return null;
+  const raw = String(match[2] || '').split('#')[0].split('?')[0].replace(/\\/g, '/');
+  if (!raw || raw.startsWith('/') || raw.split('/').some((part) => part === '..')) return null;
+  const path = raw.split('/').filter((part) => part && part !== '.').join('/');
+  return path ? Object.freeze({ workspaceId: match[1], path }) : null;
+}

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

@@ -0,0 +1,52 @@
+export function parseWorkspaceEntrypoints(markdown = '') {
+  const body = section(markdown, 'Workspace Entrypoints');
+  if (!body) return Object.freeze([]);
+  const chunks = body.split(/(?=^###\s+)/m).map((item) => item.trim()).filter(Boolean);
+  const out = [];
+  for (const chunk of chunks) {
+    const heading = chunk.match(/^###\s+(.+)$/m)?.[1]?.trim() || '';
+    const sourceKind = field(chunk, 'Source Kind');
+    const repository = field(chunk, 'Repository');
+    const ref = field(chunk, 'Ref');
+    const rootPath = field(chunk, 'Root Path');
+    if (!heading && !sourceKind && !repository && !ref && !rootPath) continue;
+    out.push(Object.freeze({
+      label: heading,
+      sourceKind,
+      repository,
+      ref,
+      rootPath,
+      remoteState: 'not-checked',
+      basis: 'qualified-durable-workspace-entrypoint'
+    }));
+  }
+  return Object.freeze(out);
+}
+
+export function normalizeRepositoryIdentity(value = '') {
+  let text = String(value || '').trim().replace(/\\/g, '/');
+  if (!text) return '';
+  text = text.replace(/^git\+/, '').replace(/\.git$/i, '').replace(/\/+$/, '');
+  const scp = text.match(/^[^@\s]+@[^:\s]+:(.+)$/);
+  if (scp) text = scp[1];
+  else {
+    try {
+      const url = new URL(text);
+      text = url.pathname.replace(/^\/+/, '');
+    } catch {
+      text = text.replace(/^https?:\/\/[^/]+\//i, '').replace(/^ssh:\/\/[^/]+\//i, '');
+    }
+  }
+  return text.replace(/^\/+/, '').replace(/\.git$/i, '').toLowerCase();
+}
+
+function section(markdown = '', heading = '') {
+  const escaped = escapeRe(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 = escapeRe(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 escapeRe(value = '') { return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

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

@@ -0,0 +1,134 @@
+import { validatedC14nV2PrimarySelfDigest } from '../../../integrity/integrity.c14nV2.js';
+import { qualifyTiinexRouteArtifact } from './routeArtifactConformance.js';
+
+export const HANDOFF_WORKSPACE_TARGET_CONFORMANCE_SCHEMA_ID = 'tiinex.portable.handoff-workspace-target-conformance.v1';
+
+export function qualifyHandoffWorkspaceTarget(input = {}) {
+  const targetPath = normalizeInnerPath(input.targetPath || input.path || '');
+  const markdown = decodeUtf8(input.targetData || input.data || new Uint8Array());
+  if (!targetPath || !markdown) return blockedTarget(targetPath, ['workspace-target-artifact-unreadable']);
+  let conformance;
+  try {
+    conformance = qualifyTiinexRouteArtifact({
+      markdown,
+      expectedSchemaId: 'tiinex.workspace.v1',
+      requireExactContract: true,
+      resolveParent: ({ parent, targetEntry }) => resolveWorkspaceParent({ entries: input.entries || [], parentCandidates: input.parentCandidates || input.recoveryEntries || [], targetPath, parent, targetEntry })
+    });
+  } catch (error) {
+    return blockedTarget(targetPath, ['workspace-target-artifact-conformance-error'], String(error?.message || error || 'workspace-target-artifact-conformance-error'));
+  }
+  const reasons = conformanceReasons(conformance);
+  const selfIntegrity = Object.freeze({
+    state: String(conformance.selfIntegrity?.state || ''),
+    value: String(conformance.selfIntegrity?.computedValue || conformance.selfIntegrity?.declaredValue || '')
+  });
+  return deepFreeze({
+    schema: HANDOFF_WORKSPACE_TARGET_CONFORMANCE_SCHEMA_ID,
+    state: reasons.length ? 'blocked' : 'qualified',
+    targetPath,
+    selfIntegrity,
+    conformance,
+    reasons: Object.freeze(reasons),
+    boundary: 'Exact Workspace artifact bytes must qualify through the existing Root/registered-schema/self-integrity/Parent-target authority. Workspace filename, package placement, and matching stored descriptor state cannot create qualification.'
+  });
+}
+
+function conformanceReasons(conformance = {}) {
+  const reasons = [];
+  if (String(conformance.observedSchemaId || '') !== 'tiinex.workspace.v1') reasons.push('workspace-target-schema-unqualified');
+  const selfState = String(conformance.selfIntegrity?.state || '');
+  if (selfState !== 'verified') reasons.push(selfState === 'mismatch' ? 'workspace-target-self-integrity-mismatch' : 'workspace-target-self-integrity-unverified');
+  if (conformance.parentContinuity?.parentDeclared && String(conformance.parentContinuity?.state || '') !== 'qualified') reasons.push('workspace-target-parent-continuity-unqualified');
+  if (String(conformance.status || '') !== 'qualified') reasons.push('workspace-target-artifact-conformance-unqualified');
+  return [...new Set(reasons)];
+}
+
+function resolveWorkspaceParent({ entries = [], parentCandidates = [], targetPath = '', parent = {}, targetEntry = {} } = {}) {
+  const indexed = indexEntries(entries);
+  const recoveryIndexed = indexEntries(parentCandidates);
+  const localCandidates = new Map();
+  for (const reference of parentLocalReferences(parent)) {
+    const resolvedPath = resolveRelativeReference(targetPath, reference);
+    if (!resolvedPath) continue;
+    const entry = indexed.get(resolvedPath);
+    const markdown = entry ? decodeUtf8(entry.data) : '';
+    if (!entry || !markdown) continue;
+    localCandidates.set(resolvedPath, Object.freeze({ state: 'qualified', markdown, basis: 'workspace-parent-local-reference', workspaceRelativePath: resolvedPath, sha256: String(entry.sha256 || '') }));
+  }
+  if (localCandidates.size === 1) return [...localCandidates.values()][0];
+  if (localCandidates.size > 1) return Object.freeze({ state: 'ambiguous', reason: 'multiple-parent-local-reference-candidates' });
+
+  const expectedDigest = String(targetEntry?.value || '').trim();
+  if (!expectedDigest) return Object.freeze({ state: 'unavailable', reason: 'parent-target-digest-missing' });
+  const digestCandidates = new Map();
+  for (const [candidateSet, basis] of [[indexed, 'workspace-parent-target-digest-candidate'], [recoveryIndexed, 'detached-parent-target-digest-candidate']]) {
+    for (const entry of candidateSet.values()) {
+      const markdown = decodeUtf8(entry.data);
+      if (!markdown) continue;
+      const self = validatedC14nV2PrimarySelfDigest(markdown);
+      if (self.state !== 'verified' || self.value !== expectedDigest) continue;
+      const key = `${entry.path}\u0000${entry.sha256 || ''}`;
+      digestCandidates.set(key, Object.freeze({ state: 'qualified', markdown, basis, workspaceRelativePath: entry.path, sha256: String(entry.sha256 || '') }));
+    }
+  }
+  if (digestCandidates.size === 1) return [...digestCandidates.values()][0];
+  if (digestCandidates.size > 1) return Object.freeze({ state: 'ambiguous', reason: 'multiple-parent-target-digest-candidates' });
+  return Object.freeze({ state: 'unavailable', reason: 'parent-representation-not-carried' });
+}
+
+function indexEntries(entries = []) {
+  const out = new Map();
+  for (const raw of entries) {
+    const entryPath = normalizeInnerPath(raw?.path || raw?.innerPath || '');
+    if (!entryPath || out.has(entryPath)) continue;
+    out.set(entryPath, Object.freeze({ ...raw, path: entryPath }));
+  }
+  return out;
+}
+
+function parentLocalReferences(parent = {}) {
+  const out = [];
+  if (parent.trace && !isExternalReference(parent.trace)) out.push(String(parent.trace));
+  for (const entry of parent.originEntries || []) {
+    if (String(entry?.label || '').trim() === 'relative' && entry?.target && !isExternalReference(entry.target)) out.push(String(entry.target));
+  }
+  return [...new Set(out)];
+}
+
+function resolveRelativeReference(fromPath = '', reference = '') {
+  const base = normalizeInnerPath(fromPath);
+  if (!base || !reference || isExternalReference(reference)) return '';
+  let clean;
+  try { clean = decodeURIComponent(String(reference).split('#')[0].split('?')[0]); } catch { return ''; }
+  if (!clean || clean.startsWith('/') || clean.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(clean)) return '';
+  const parts = base.split('/').slice(0, -1);
+  for (const part of clean.replace(/\\/g, '/').split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') { if (!parts.length) return ''; parts.pop(); continue; }
+    if (/^[\u0000-\u001f]+$/.test(part)) return '';
+    parts.push(part);
+  }
+  return normalizeInnerPath(parts.join('/'));
+}
+
+function normalizeInnerPath(value = '') {
+  const raw = String(value || '');
+  if (!raw || raw.includes('\u0000') || /[\u0000-\u001f]/.test(raw)) return '';
+  const slashed = raw.replace(/\\/g, '/');
+  if (slashed.startsWith('/') || slashed.startsWith('//') || /^[A-Za-z]:\//.test(slashed)) return '';
+  const parts = [];
+  for (const part of slashed.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') return '';
+    parts.push(part);
+  }
+  return parts.join('/');
+}
+
+function blockedTarget(targetPath = '', reasons = [], error = '') {
+  return deepFreeze({ schema: HANDOFF_WORKSPACE_TARGET_CONFORMANCE_SCHEMA_ID, state: 'blocked', targetPath, selfIntegrity: Object.freeze({ state: '', value: '' }), conformance: null, reasons: Object.freeze(reasons), error, boundary: 'Workspace target qualification failed closed before semantic binding.' });
+}
+function isExternalReference(value = '') { return /^[a-z][a-z0-9+.-]*:/i.test(String(value || '')) || String(value || '').startsWith('//'); }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }