@tiinex/core 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiinex/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Shared host-neutral Tiinex implementation core for artifacts, schemas, validation, lineage, grounding, Handoffs, provenance and deterministic workflows.",
   "type": "module",
   "sideEffects": true,
@@ -167,12 +167,12 @@
     "type": "git",
     "url": "git+https://github.com/Tiinex/core.git"
   },
-  "gitHead": "6a139559c7cb3d809b2ecf0482d0ae42243aa609",
+  "gitHead": "3a1efbac38c1cabc1a0d85746ccaab8149d6162e",
   "tiinexRelease": {
     "policy": "tiinex.master-npm-release.v1",
-    "sourceCommit": "6a139559c7cb3d809b2ecf0482d0ae42243aa609",
-    "sourceTree": "ec876301e7b78eaf85e8cbf9aba91dba873c2b3b",
+    "sourceCommit": "3a1efbac38c1cabc1a0d85746ccaab8149d6162e",
+    "sourceTree": "8c1449869841737fb7b120b69d00b4854cfff334",
     "repository": "Tiinex/core",
-    "previousVersion": "0.7.0"
+    "previousVersion": "0.9.0"
   }
 }

package/src/lineage/parentRecoveryReference.js

@@ -0,0 +1,49 @@
+export function parseWorkspaceQualifiedRecoveryReference(value = '') {
+  const rawValue = normalizedReferenceText(value);
+  const match = rawValue.match(/^([A-Za-z0-9._-]+)::(.+)$/);
+  if (!match) return null;
+  const rawPath = referencePathPart(match[2]);
+  if (!rawPath || rawPath.startsWith('/') || rawPath.startsWith('\\') || /^[A-Za-z]:[\\/]/.test(rawPath)) return null;
+  const parts = rawPath.replace(/\\/g, '/').split('/');
+  if (parts.some((part) => !part || part === '..' || hasControlCharacters(part))) return null;
+  const path = parts.filter((part) => part !== '.').join('/');
+  return path ? Object.freeze({ workspaceId: match[1], path, reference: `${match[1]}::${path}` }) : null;
+}
+
+export function classifyParentRecoveryReference(value = '') {
+  const raw = normalizedReferenceText(value);
+  if (!raw) return Object.freeze({ kind: 'empty', raw: '', workspaceQualified: null });
+  const workspaceQualified = parseWorkspaceQualifiedRecoveryReference(raw);
+  if (workspaceQualified) return Object.freeze({ kind: 'workspace-qualified', raw, workspaceQualified });
+  if (isNetworkOrSchemeReference(raw)) return Object.freeze({ kind: 'external', raw, workspaceQualified: null });
+  if (raw.includes('::')) return Object.freeze({ kind: 'malformed-workspace-qualified', raw, workspaceQualified: null });
+  return Object.freeze({ kind: 'local-relative', raw, workspaceQualified: null });
+}
+
+export function isMalformedWorkspaceQualifiedRecoveryReference(value = '') {
+  return classifyParentRecoveryReference(value).kind === 'malformed-workspace-qualified';
+}
+
+export function isExternalRecoveryReference(value = '') {
+  return classifyParentRecoveryReference(value).kind === 'external';
+}
+
+function normalizedReferenceText(value = '') {
+  return String(value || '').trim();
+}
+
+function referencePathPart(value = '') {
+  let decoded;
+  try { decoded = decodeURIComponent(String(value || '').split('#')[0].split('?')[0]); }
+  catch { return ''; }
+  return decoded;
+}
+
+function isNetworkOrSchemeReference(value = '') {
+  const text = String(value || '');
+  return /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(text) || text.startsWith('//') || (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(text) && !text.includes('::'));
+}
+
+function hasControlCharacters(value = '') {
+  return /[\u0000-\u001f]/.test(String(value || ''));
+}

package/src/schemas/creation.renderer.js

@@ -3,6 +3,7 @@ import { schemaIdForRecord } from './schema.identity.js';
 import { canonicalRootCreatedAt } from './creation.rootMetadata.js';
 import { renderSchemaReference } from './schema.reference.js';
 import { C14N_V2_METHOD_ID, renderIntegrityMethodReference } from '../integrity/integrity.methodReference.js';
+import { parseWorkspaceQualifiedRecoveryReference } from '../lineage/parentRecoveryReference.js';
 
 export const GENERIC_ARTIFACT_CREATION_RENDERER_ID = 'tiinex.site.generic-artifact-creation-renderer.v1';
 
@@ -194,11 +195,16 @@ function parentEnvelope(record = {}, childPath = '') {
   const recoveryMode = normalizeParentRecoveryMode(record.recoveryMode || record.parentRecoveryMode || 'local-relative');
   const published = normalizePublishedReference(record.publishedReference || record.browseGitReference || record.browseGit || '');
   const publishedReference = published.state === 'qualified' ? published.target : '';
-  const relativeReference = recoveryMode === 'external-versioned' ? '' : String(record.relativeReference || relativePath(dirname(child), parentPath)).trim();
+  const relativeReference = recoveryMode === 'external-versioned'
+    ? ''
+    : recoveryMode === 'workspace-qualified'
+      ? String(record.relativeReference || parentPath).trim()
+      : String(record.relativeReference || relativePath(dirname(child), parentPath)).trim();
   const traceReference = recoveryMode === 'external-versioned' ? publishedReference : relativeReference;
   const schemaReferenceAuthority = normalizeParentSchemaReferenceAuthority(record.schemaReferenceAuthority || record.parentSchemaReferenceAuthority, schemaId);
   if (!schemaId || !parentPath || !child || !traceReference) throw new Error('creation-parent-identity-incomplete');
   if (recoveryMode === 'external-versioned' && !publishedReference) throw new Error('creation-parent-external-versioned-reference-required');
+  if (recoveryMode === 'workspace-qualified' && !parseWorkspaceQualifiedRecoveryReference(relativeReference)) throw new Error('creation-parent-workspace-qualified-reference-invalid');
   const parentSelf = validatedC14nV2PrimarySelfDigest(record.markdown || '');
   if (parentSelf.state !== 'verified') throw new Error(`creation-parent-primary-self-${parentSelf.reason || parentSelf.state}`);
   const integrityTarget = publishedReference || relativeReference;
@@ -217,7 +223,12 @@ function parentEnvelope(record = {}, childPath = '') {
   });
 }
 
-function normalizeParentRecoveryMode(value = '') { return String(value || '').trim() === 'external-versioned' ? 'external-versioned' : 'local-relative'; }
+function normalizeParentRecoveryMode(value = '') {
+  const mode = String(value || '').trim();
+  if (mode === 'external-versioned') return 'external-versioned';
+  if (mode === 'workspace-qualified') return 'workspace-qualified';
+  return 'local-relative';
+}
 function normalizePublishedReference(value) {
   if (typeof value === 'string') return Object.freeze({ target: value, state: value ? 'unresolved' : 'unavailable' });
   return Object.freeze({ target: String(value?.target || value?.url || ''), state: String(value?.state || value?.resolutionState || 'unresolved') });

package/src/schemas/tiinex.root.v1.validate.js

@@ -1,3 +1,5 @@
+import { isMalformedWorkspaceQualifiedRecoveryReference } from '../lineage/parentRecoveryReference.js';
+
 export function rootValidate(artifact) {
   const findings = [];
   const envelope = artifact?.envelope || {};
@@ -20,6 +22,13 @@ export function rootValidate(artifact) {
     const labels = originEntries.map((entry) => String(entry?.label || '').trim()).filter(Boolean);
     const duplicateLabels = [...new Set(labels.filter((label, index) => labels.indexOf(label) !== index))];
     for (const label of duplicateLabels) findings.push(error('root.parent.origin.label.duplicate', `Parent Origin recovery label is duplicated: ${label}.`));
+    const recoveryReferences = [
+      Object.freeze({ field: 'Trace', target: String(parent.trace || '').trim() }),
+      ...originEntries.map((entry) => Object.freeze({ field: `Origin:${String(entry?.label || '').trim() || 'unlabelled'}`, target: String(entry?.target || '').trim() }))
+    ].filter((entry) => entry.target);
+    for (const reference of recoveryReferences) {
+      if (isMalformedWorkspaceQualifiedRecoveryReference(reference.target)) findings.push(error('root.parent.recovery.workspace-qualified.malformed', `Parent ${reference.field} contains a malformed Workspace-qualified recovery locator: ${reference.target}.`));
+    }
   }
   if (envelope.repairsDeclared) findings.push(info('root.repairs.declared', 'Envelope declares repair notes; validators should preserve unknown repair fields.'));
   if (!findings.some((finding) => finding.severity === 'error')) findings.push(info('root.envelope.readable', 'Root envelope is readable at current validation depth.'));

package/src/tooling/portable/adapters/cli/cli.common-author.js

@@ -9,6 +9,7 @@ import { resolveSchemaModule } from '../../../../schemas/resolver.js';
 import { loadNodePortableInput } from '../../input/node.input.js';
 import { runPortableOperation } from '../../operation.catalog.js';
 import { allocateContinuationPath, allocateDirectoryArtifactPath } from '../../../../transitions/record.transitions.js';
+import { classifyParentRecoveryReference } from '../../../../lineage/parentRecoveryReference.js';
 
 const STATE_RELATIVE_PATH = '.tiinex/continuation.json';
 
@@ -137,11 +138,18 @@ async function parentRecordFromArtifact(parentPath, parentRelativePath, context
     currentCreatedAt: String(current.createdAt || ''),
     createdAt: String(current.createdAt || ''),
     markdown,
-    recoveryMode: 'local-relative',
+    recoveryMode: parentRecoveryMode(parentRelativePath),
     schemaReferenceAuthority
   });
 }
 
+export function parentRecoveryMode(reference = '') {
+  const classification = classifyParentRecoveryReference(reference);
+  if (classification.kind === 'workspace-qualified') return 'workspace-qualified';
+  if (classification.kind === 'malformed-workspace-qualified') throw new Error('portable.cli.author.parent.workspace-qualified.malformed');
+  return 'local-relative';
+}
+
 function exactDeclaredSchemaReferenceAuthority(schemaId, schemaTarget) {
   return Object.freeze({
     schemaId,

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

@@ -85,7 +85,8 @@ export async function prepareHandoffManufactureCliCommand(parsed = {}, runtime =
       parentPackagePath: resolvedParent,
       parentPackageSha256: provisionalLineage.parentPackageSha256,
       parentDimension: provisionalLineage.parentDimension,
-      enabled: !flags['package-major'] && Boolean(flags.output || flags['output-dir'])
+      enabled: !flags['package-major'] && Boolean(flags.output || flags['output-dir']),
+      siblingIndex: flags['package-sibling-index']
     });
     carrierLineage = flags['package-major'] ? provisionalLineage : carrierLineageFromCliParent({
       bundle: parentBundle,

package/src/tooling/portable/adapters/cli/cli.handoff-sibling-allocation.js

@@ -1,10 +1,12 @@
-import { mkdir, open } from 'node:fs/promises';
+import { mkdir, open, readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 const MAX_SIBLING_INDEX = 9999;
 
-export async function reserveHandoffSiblingIndex({ parentPackagePath = '', parentPackageSha256 = '', parentDimension = '', enabled = true } = {}) {
-  if (!enabled) return Object.freeze({ state: 'not-reserved', siblingIndex: 1, allocationPath: '' });
+export async function reserveHandoffSiblingIndex({ parentPackagePath = '', parentPackageSha256 = '', parentDimension = '', enabled = true, siblingIndex = null } = {}) {
+  const requestedSiblingIndex = normalizeSiblingIndex(siblingIndex);
+  if (!enabled) return Object.freeze({ state: 'not-reserved', siblingIndex: requestedSiblingIndex || 1, allocationPath: '', coordinationRequired: Boolean(requestedSiblingIndex) });
+  if (!requestedSiblingIndex) throw new Error('portable.cli.handoff-carrier.sibling-allocation.explicit-index-required');
   const parentPath = path.resolve(String(parentPackagePath || ''));
   const digest = String(parentPackageSha256 || '').trim().toLowerCase();
   const dimension = String(parentDimension || '').trim();
@@ -12,20 +14,42 @@ export async function reserveHandoffSiblingIndex({ parentPackagePath = '', paren
   const allocationDir = path.join(path.dirname(parentPath), '.tiinex-handoff-sibling-allocations');
   await mkdir(allocationDir, { recursive: true });
   const key = `${digest.slice(0, 24)}-${dimension.replace(/[^0-9-]/g, '')}`;
-  for (let siblingIndex = 1; siblingIndex <= MAX_SIBLING_INDEX; siblingIndex += 1) {
-    const allocationPath = path.join(allocationDir, `${key}-${siblingIndex}.allocation`);
-    try {
-      const handle = await open(allocationPath, 'wx');
-      try {
-        await handle.writeFile(`${JSON.stringify({ parentPackageSha256: digest, parentDimension: dimension, siblingIndex, childDimension: `${dimension}-${siblingIndex}` })}\n`, 'utf8');
-      } finally {
-        await handle.close();
-      }
-      return Object.freeze({ state: 'reserved', siblingIndex, allocationPath });
-    } catch (error) {
-      if (error?.code === 'EEXIST') continue;
-      throw error;
-    }
+  const allocationPath = path.join(allocationDir, `${key}-${requestedSiblingIndex}.allocation`);
+  const record = Object.freeze({
+    parentPackageSha256: digest,
+    parentDimension: dimension,
+    siblingIndex: requestedSiblingIndex,
+    childDimension: `${dimension}-${requestedSiblingIndex}`,
+    allocationAuthority: 'explicit-caller-coordination'
+  });
+  try {
+    const handle = await open(allocationPath, 'wx');
+    try { await handle.writeFile(`${JSON.stringify(record)}\n`, 'utf8'); }
+    finally { await handle.close(); }
+    return Object.freeze({ state: 'reserved-explicit', siblingIndex: requestedSiblingIndex, allocationPath, coordinationRequired: true });
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    const prior = await readAllocation(allocationPath);
+    if (!sameAllocation(prior, record)) throw new Error('portable.cli.handoff-carrier.sibling-allocation.existing-reservation-conflict');
+    return Object.freeze({ state: 'reused-explicit', siblingIndex: requestedSiblingIndex, allocationPath, coordinationRequired: true });
   }
-  throw new Error('portable.cli.handoff-carrier.sibling-allocation.exhausted');
+}
+
+function normalizeSiblingIndex(value) {
+  if (value === null || value === undefined || value === '') return 0;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_SIBLING_INDEX) throw new Error('portable.cli.handoff-carrier.sibling-allocation.index-invalid');
+  return parsed;
+}
+
+async function readAllocation(allocationPath) {
+  try { return JSON.parse(await readFile(allocationPath, 'utf8')); }
+  catch { throw new Error('portable.cli.handoff-carrier.sibling-allocation.existing-reservation-invalid'); }
+}
+
+function sameAllocation(left = {}, right = {}) {
+  return String(left.parentPackageSha256 || '') === String(right.parentPackageSha256 || '')
+    && String(left.parentDimension || '') === String(right.parentDimension || '')
+    && Number(left.siblingIndex || 0) === Number(right.siblingIndex || 0)
+    && String(left.childDimension || '') === String(right.childDimension || '');
 }

package/src/tooling/portable/adapters/cli/cli.help.js

@@ -70,7 +70,7 @@ function commonCommandHelp(command, surfaceCommand) {
     '',
     `${command} handoff <workspace-dir>`,
     '',
-    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent as carrier-lineage evidence, canonical projected filename, and return output directory. It does not implicitly carry sibling Workspaces from the received package; advanced manufacture must select exact reusable parent snapshots with `--package-parent-workspaces <id,...|all>`. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
+    'Infers the latest qualified authored Handoff, selected Workspace identity/target, received package parent as carrier-lineage evidence, canonical projected filename, and return output directory. A non-major continuation that writes a carrier must supply an explicitly coordinated `--package-sibling-index <1..9999>`; Tooling will not silently discover the next sibling because isolated runtimes cannot prove a globally unique reservation. Distinct explicit sibling indexes preserve same-Major parallelism, while byte-identical duplicate transport at one exact output path is idempotent and divergent bytes fail closed. It does not implicitly carry sibling Workspaces from the received package; advanced manufacture must select exact reusable parent snapshots with `--package-parent-workspaces <id,...|all>`. The default receipt keeps output identity, routing text, closure/workspace qualification, verification, and actionable findings compact; add `--full` for the complete manufacture receipt. Normal operator completion is exactly one Handoff package plus the adjacent exact routing text. In markdown-capable hosts render that routing in a fenced code block; do not emit canonical Workspace Evidence/Handoff markdown as additional loose transport files. Runtime-only `.tiinex` state is excluded from canonical manufacture.',
     '',
     `Advanced/internal catalog: ${command} operations`
   ];

package/src/tooling/portable/adapters/node/handoff.manufacture.requirements.js

@@ -273,7 +273,7 @@ function resolveCarriedWorkspaceQualifiedReference(target = '', workspaceRuntime
 
 export function resolveRelativeWorkspaceTarget(sourcePath = '', target = '') {
   const raw = safeDecodeURIComponent(String(target || '').split('#')[0].split('?')[0]);
-  if (!raw || path.posix.isAbsolute(raw) || raw.startsWith('\\')) return '';
+  if (!raw || path.posix.isAbsolute(raw) || raw.startsWith('\\') || raw.includes('::')) return '';
   const base = normalizeRelativePath(sourcePath).split('/').slice(0, -1);
   for (const part of raw.replace(/\\/g, '/').split('/')) {
     if (!part || part === '.') continue;

package/src/tooling/portable/handoff/carrierProjection.routeQualification.js

@@ -4,6 +4,7 @@ import { projectHandoffMaterialRequirements, projectParticipantRoleRequirements
 import { qualifySelectedHandoffArtifact } from './routeArtifactConformance.js';
 import { listHandoffWorkspaceEntries, resolveHandoffWorkspaceEntry } from './workspaceByteProvider.js';
 import { parseWorkspaceQualifiedReference, SHARED_ROUTE_REQUIRED_CONTEXT_BOUNDARY } from './workspaceQualifiedReference.js';
+import { classifyParentRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
 import { decodeUtf8, deepFreeze, findFile, normalizeWorkspacePath } from './carrierProjection.shared.js';
 
 export function qualifyRoute(bundle, descriptor, byteProvider, workspace, spec = {}, options = {}) {
@@ -132,13 +133,27 @@ function resolveDescriptorMaterial(bundle, descriptor, byteProvider, target = ''
 }
 
 function resolveRouteParent(bundle, descriptor, byteProvider, workspace, routePath, parent = {}, targetEntry = {}) {
-  const localTargets = [];
-  if (parent.trace && !isExternalReference(parent.trace)) localTargets.push(String(parent.trace));
+  const recoveryTargets = [];
+  if (parent.trace) recoveryTargets.push(String(parent.trace));
   for (const entry of parent.originEntries || []) {
-    if (String(entry?.label || '').trim() === 'relative' && entry?.target && !isExternalReference(entry.target)) localTargets.push(String(entry.target));
+    if (String(entry?.label || '').trim() === 'relative' && entry?.target) recoveryTargets.push(String(entry.target));
   }
   const candidates = new Map();
-  for (const target of localTargets) {
+  for (const target of [...new Set(recoveryTargets)]) {
+    const classification = classifyParentRecoveryReference(target);
+    if (classification.kind === 'malformed-workspace-qualified') return Object.freeze({ state: 'unavailable', reason: 'parent-workspace-qualified-reference-malformed' });
+    if (classification.kind === 'external' || classification.kind === 'empty') continue;
+    if (classification.kind === 'workspace-qualified') {
+      const qualified = classification.workspaceQualified;
+      const resolved = resolveHandoffWorkspaceEntry(byteProvider, qualified.workspaceId, qualified.path);
+      if (resolved.state !== 'qualified') continue;
+      const data = packageFileBytes({ data: resolved.data });
+      if (Number(resolved.bytes || 0) !== data.byteLength || String(resolved.sha256 || '') !== sha256Hex(data)) continue;
+      const markdown = decodeUtf8(data);
+      if (!markdown) continue;
+      candidates.set(`${qualified.workspaceId}\u0000${qualified.path}`, Object.freeze({ state: 'qualified', markdown, basis: 'parent-workspace-qualified-reference', workspaceId: qualified.workspaceId, workspaceRelativePath: qualified.path, packagePath: String(resolved.packagePath || ''), sha256: sha256Hex(data) }));
+      continue;
+    }
     const resolvedPath = resolveWorkspaceReference(routePath, target);
     if (!resolvedPath) continue;
     const resolved = resolveHandoffWorkspaceEntry(byteProvider, workspace.id, resolvedPath);
@@ -192,7 +207,7 @@ function packageParentCandidates(bundle = {}, descriptor = {}, byteProvider = {}
 
 function resolveWorkspaceReference(routePath, target) {
   const raw = safeDecodeURIComponent(String(target || '').split('#')[0].split('?')[0]);
-  if (!raw || raw.startsWith('/') || raw.startsWith('\\')) return '';
+  if (!raw || raw.startsWith('/') || raw.startsWith('\\') || raw.includes('::')) return '';
   const base = normalizeWorkspacePath(routePath).split('/').slice(0, -1);
   for (const part of raw.replace(/\\/g, '/').split('/')) {
     if (!part || part === '.') continue;

package/src/tooling/portable/handoff/recipientV2.artifactFirst.closure.js

@@ -3,6 +3,7 @@ import { validatedC14nV2PrimarySelfDigest } from '../../../integrity/integrity.c
 import { projectHandoffMaterialRequirements } from './materialClosure.requirements.js';
 import { deepFreeze, finding, normalizeRoutePath, sectionText, fieldValue, decodeUtf8 } from './recipientV2.artifactFirst.shared.js';
 import { parseWorkspaceQualifiedReference } from './workspaceQualifiedReference.js';
+import { classifyParentRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
 
 export function qualifyRecipientV2ArtifactFirstPhase1RequiredContextClosure(input = {}) {
   return qualifyPhase1RequiredContextClosure(input);
@@ -71,7 +72,23 @@ export function qualifyPhase1RequiredContextClosure({ markdown = '', routePath =
 export function resolveArchiveParent(routePath = '', entries = [], parent = {}, targetEntry = {}, parentCandidates = []) {
   const refs = [String(parent.trace || ''), ...(parent.originEntries || []).map((item) => String(item.target || '')), String(targetEntry.towards || '')].filter(Boolean);
   for (const ref of refs) {
-    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(ref)) continue;
+    const classification = classifyParentRecoveryReference(ref);
+    if (classification.kind === 'malformed-workspace-qualified') return Object.freeze({ state: 'unresolved', reason: 'parent-workspace-qualified-reference-malformed' });
+    if (classification.kind === 'external' || classification.kind === 'empty') continue;
+    if (classification.kind === 'workspace-qualified') {
+      const qualified = classification.workspaceQualified;
+      const matches = (parentCandidates || []).filter((candidate) => String(candidate.workspaceId || '') === qualified.workspaceId && String(candidate.workspaceRelativePath || '') === qualified.path);
+      if (matches.length > 1) return Object.freeze({ state: 'ambiguous', reason: 'multiple-parent-workspace-qualified-reference-candidates' });
+      if (matches.length === 1) {
+        const candidate = matches[0];
+        const data = packageFileBytes({ data: candidate.data });
+        if (data.byteLength && Number(candidate.bytes || data.byteLength) === data.byteLength && (!candidate.sha256 || String(candidate.sha256) === sha256Hex(data))) {
+          const markdown = decodeUtf8(data);
+          if (markdown) return Object.freeze({ state: 'qualified', markdown, basis: 'artifact-first-workspace-qualified-reference', workspaceId: qualified.workspaceId, workspaceRelativePath: qualified.path, archiveEntry: String(candidate.archiveEntry || ''), sha256: sha256Hex(data) });
+        }
+      }
+      continue;
+    }
     const resolved = resolveRelativeWorkspacePath(routePath, ref);
     if (!resolved) continue;
     const matches = entries.filter((entry) => String(entry.path || '') === resolved);
@@ -115,7 +132,7 @@ export function phase1CacheParentCandidates(cacheQualifications = []) {
 
 export function resolveRelativeWorkspacePath(fromPath = '', ref = '') {
   const value = String(ref || '').split('#')[0].replace(/\\/g, '/');
-  if (!value || value.startsWith('/') || /^[A-Za-z]:\//.test(value)) return '';
+  if (!value || value.startsWith('/') || /^[A-Za-z]:\//.test(value) || value.includes('::')) return '';
   const base = String(fromPath || '').replace(/\\/g, '/').split('/'); base.pop();
   const parts = value.startsWith('./') || value.startsWith('../') ? [...base, ...value.split('/')] : [...base, ...value.split('/')];
   const out = [];

package/src/tooling/portable/handoff/recipientV2.packageV1.inspect.js

@@ -284,7 +284,7 @@ function qualifyParentBoundaryCacheRequirementIds(caches = [], workspaceByteProv
 function resolveRelativeWorkspacePath(sourcePath = '', target = '') {
   let raw;
   try { raw = decodeURIComponent(String(target || '').split('#')[0].split('?')[0]); } catch { return ''; }
-  if (!raw || raw.startsWith('/') || raw.startsWith('\\') || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('//')) return '';
+  if (!raw || raw.startsWith('/') || raw.startsWith('\\') || raw.includes('::') || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('//')) return '';
   const parts = normalizeWorkspacePath(sourcePath).split('/').slice(0, -1);
   for (const part of raw.replace(/\\/g, '/').split('/')) {
     if (!part || part === '.') continue;

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

@@ -1,10 +1,8 @@
+import { parseWorkspaceQualifiedRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
+
 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;
+  const parsed = parseWorkspaceQualifiedRecoveryReference(value);
+  return parsed ? Object.freeze({ workspaceId: parsed.workspaceId, path: parsed.path }) : null;
 }

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

@@ -1,5 +1,6 @@
 import { validatedC14nV2PrimarySelfDigest } from '../../../integrity/integrity.c14nV2.js';
 import { qualifyTiinexRouteArtifact } from './routeArtifactConformance.js';
+import { classifyParentRecoveryReference } from '../../../lineage/parentRecoveryReference.js';
 
 export const HANDOFF_WORKSPACE_TARGET_CONFORMANCE_SCHEMA_ID = 'tiinex.portable.handoff-workspace-target-conformance.v1';
 
@@ -48,7 +49,10 @@ function resolveWorkspaceParent({ entries = [], parentCandidates = [], targetPat
   const indexed = indexEntries(entries);
   const recoveryIndexed = indexEntries(parentCandidates);
   const localCandidates = new Map();
-  for (const reference of parentLocalReferences(parent)) {
+  for (const reference of parentRecoveryReferences(parent)) {
+    const classification = classifyParentRecoveryReference(reference);
+    if (classification.kind === 'malformed-workspace-qualified') return Object.freeze({ state: 'unavailable', reason: 'parent-workspace-qualified-reference-malformed' });
+    if (classification.kind !== 'local-relative') continue;
     const resolvedPath = resolveRelativeReference(targetPath, reference);
     if (!resolvedPath) continue;
     const entry = indexed.get(resolvedPath);
@@ -87,18 +91,18 @@ function indexEntries(entries = []) {
   return out;
 }
 
-function parentLocalReferences(parent = {}) {
+function parentRecoveryReferences(parent = {}) {
   const out = [];
-  if (parent.trace && !isExternalReference(parent.trace)) out.push(String(parent.trace));
+  if (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));
+    if (String(entry?.label || '').trim() === 'relative' && 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 '';
+  if (!base || !reference || isExternalReference(reference) || String(reference).includes('::')) 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 '';

package/src/tooling/portable/output/recipientV2.zip.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { packageFileBytes } from '../../../export/package.bytes.js';
 import { inspectRecipientFacingV2Topology } from '../handoff/recipientV2.inspect.js';
@@ -38,10 +38,10 @@ export async function writeRecipientFacingV2PackageZip(bundle = {}, outputPath =
   if (!target.toLowerCase().endsWith('.zip')) throw new Error('portable.recipient-v2.zip.output.extension');
   await mkdir(path.dirname(target), { recursive: true });
   const buffer = recipientFacingV2PackageZipBuffer(bundle, options);
-  await writeFile(target, buffer);
+  const exactWrite = await writeExactRecipientTransportBytes(target, buffer);
   return Object.freeze({
     schema: 'tiinex.portable.recipient-facing-v2.zip-write.v1',
-    status: 'written',
+    status: exactWrite.status,
     path: target,
     bytes: buffer.length,
     transportFormat: RECIPIENT_V2_FORMAT_ID,
@@ -49,6 +49,20 @@ export async function writeRecipientFacingV2PackageZip(bundle = {}, outputPath =
   });
 }
 
+export async function writeExactRecipientTransportBytes(outputPath = '', data = new Uint8Array()) {
+  const target = path.resolve(String(outputPath || '').trim());
+  const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  try {
+    await writeFile(target, buffer, { flag: 'wx' });
+    return Object.freeze({ status: 'written', path: target, bytes: buffer.length });
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    const existing = await readFile(target);
+    if (!existing.equals(buffer)) throw new Error('portable.recipient-v2.zip.output-collision-divergent');
+    return Object.freeze({ status: 'reused-identical', path: target, bytes: buffer.length });
+  }
+}
+
 function bufferViewOfPackageFile(file = {}) {
   const value = file.data;
   if (Buffer.isBuffer(value)) return value;