Skip to main content

Sync Protocol

How Workloom moves packages from the registry to local workspaces.

Design principles​

  • HTTPS only — no rsync, no SSH, no shell-based transport
  • Content-addressed — files identified by SHA-256 hash
  • Whole-object transfer — no block deltas or rolling checksums
  • Deterministic — same inputs always produce the same plan
  • Atomic writes — temp file + rename to prevent partial writes

Why not rsync​

Workloom explicitly rejects rsync as a transport mechanism:

  • Windows reliability and installation burden
  • SSH setup and key management overhead
  • Path semantics differ between platforms
  • Enterprise proxy and SSO friction
  • No clean integration with API auth

For mostly .md and .json assets, whole-object transfer over HTTPS is simpler and more reliable.

Object model​

Every file in a package is stored as a content object:

file content → normalize → SHA-256 hash → store by hash

The registry deduplicates objects across versions and packages. Downloading a package means downloading only the objects that are not already cached locally.

Pull flow​

wl pull
  1. Read .loom/binding.toml → workspace ID
  2. Fetch workspace current revision from API
  3. Compare against .loom/lock.json
  4. Download missing package objects
  5. Verify SHA-256 of each object
  6. Update .loom/lock.json with resolved versions

Render + apply flow​

wl sync
  1. Load workspace revision from lock
  2. Load package assets from local cache
  3. Resolve provider capability matrix per target
  4. Build deterministic render plan
  5. Run trust/privacy gates
  6. Require local approval where needed
  7. Write only approved Workloom-owned files
  8. Update .loom/state.json with render plan + drift baseline

Push flow​

wl push --draft ./path/to/assets
  1. Read selected asset source files
  2. Validate asset schemas
  3. Compute SHA-256 for each file
  4. Upload missing objects to registry
  5. Create draft package version referencing hashes

Drift check flow​

wl sync --check
  1. Recompute render plan from lock
  2. Compare local files to expected hashes
  3. Compare policy and provider metadata
  4. Exit 0 only if clean
  5. Print machine-readable diagnostics if drifted

Path normalization​

All paths in manifests and render plans use forward slashes and are workspace-relative:

.claude/skills/security-review/SKILL.md    ← correct
C:\Users\dev\.claude\skills\...            ← rejected
../outside-workspace/file.md               ← rejected

The sync engine rejects absolute paths, drive letters, and .. traversal.

Cross-platform requirements​

  • Normalize all manifest paths to forward-slash workspace-relative paths
  • Reject absolute paths, .. traversal, and drive letters
  • Detect case collisions (Agent.md vs agent.md)
  • Use atomic temp-file writes in the same directory
  • Retry or report locked files cleanly
  • Prefer LF output for deterministic generated files
  • Do not write outside the bound workspace

Future transport​

Phase 2 adds an HTTPS registry API with:

  • Authorized object upload/download
  • Signed URLs for large assets
  • Batch object planning (request only missing objects)
  • Resumable uploads for unreliable connections