Replace mirrored _vendor/ with symlinks for single source of truth

[kyamagu]

Summary

Replace the mirrored src/layerd/_vendor/ directories with symlinks to vendor/ to establish a single source of truth and prevent accidental edits that aren't synced.

Background

Currently, LayerD maintains vendored dependencies in two locations:

• vendor/: Source of truth for git subtree operations
• src/layerd/_vendor/: Mirrored copy for distribution

This requires manual syncing via tools/sync-vendor.sh after updating vendored dependencies, which can lead to divergence if developers forget to sync.

Proposed Solution

Replace the mirrored directories with symlinks:

cd src/layerd/_vendor
rm -rf simple_lama_inpainting cr_renderer

# Create symlinks
ln -s ../../../vendor/simple-lama-inpainting/simple_lama_inpainting simple_lama_inpainting
ln -s ../../../vendor/cr-renderer/src/cr_renderer cr_renderer

Why This Works

Testing confirms that Hatchling automatically materializes symlinks into real files when building wheels:

1. ✅ Wheel building - Symlinks are followed and content is copied into the wheel as real files
2. ✅ Editable installs - Python correctly follows symlinks during development
3. ✅ No wheel changes - The distributed wheel contains actual files, not symlinks

This is the desired behavior: symlinks during development, materialized files in distribution.

Benefits

1. Single source of truth - Edit only in vendor/, changes immediately reflected in _vendor/
2. No manual syncing - Eliminates need for tools/sync-vendor.sh
3. Prevents divergence - Cannot accidentally edit _vendor/ without changing vendor/
4. Simpler workflow - One less step in the development process

Implementation Checklist

• Remove mirrored directories from src/layerd/_vendor/
• Create symlinks from src/layerd/_vendor/ → vendor/
• Add .gitattributes for Windows compatibility:

  src/layerd/_vendor/simple_lama_inpainting symlink
  src/layerd/_vendor/cr_renderer symlink
  

• Test wheel building: uv build --wheel && unzip -l dist/layerd-*.whl | grep _vendor
• Test editable installs: uv sync && uv run python -c "from layerd._vendor.simple_lama_inpainting import SimpleLama"
• Run full test suite: uv run pytest
• Update documentation:
  • docs/architecture.md - Update "Dual Directory Structure" section
  • docs/development.md - Remove/update "Vendored Dependencies" section
  • Add Windows setup notes (git symlink configuration)
• Remove tools/sync-vendor.sh script
• Update CHANGELOG.md with migration notes

Potential Issues

Windows Compatibility

Issue: Git on Windows may not handle symlinks by default.

Solutions:

1. Document that Windows developers need: git config core.symlinks true
2. Use .gitattributes to mark symlinks explicitly
3. Provide fallback instructions if symlinks don't work

ZIP Downloads

Issue: GitHub's "Download ZIP" doesn't preserve symlinks.

Solution: Document that development requires git clone, not ZIP download (already best practice).

Existing Clones

Issue: Developers with existing clones will have directories, not symlinks.

Solution: Add migration instructions:

# After pulling the symlink changes
cd src/layerd/_vendor
rm -rf simple_lama_inpainting cr_renderer
git checkout HEAD -- simple_lama_inpainting cr_renderer

Testing Evidence

Created a minimal test package with symlinked vendored dependencies:

• Hatchling successfully built wheel with materialized content
• unzip -l confirmed wheel contains real files, not symlinks
• Editable installs work correctly with symlinks

References

• PEP 778 – Supporting Symlinks in Wheels (deferred, but confirms current behavior is materialization)
• Current implementation: docs/architecture.md#bundled-dependencies
• Sync script: tools/sync-vendor.sh