Rendering

Rendering is the process of transforming canonical package assets into provider-specific files. It is the core mechanism that makes Workloom provider-agnostic.

The rendering pipeline

Canonical package assets
  ↓
Workspace revision (selected packages + targets + providers)
  ↓
Render plan (deterministic, reviewable)
  ↓
Provider-specific projected files
  ↓
Local apply with ownership tracking

Render plans

A render plan is a deterministic description of what files should exist. Given the same workspace revision and package versions, the same render plan is always produced.

The plan includes:

• File path — workspace-relative, forward-slash normalized
• Content hash — SHA-256 of the rendered content
• Ownership — which package owns this file
• Projection policy — how this file should be managed locally
• Write mode — create, replace-owned, or manual-review

Dry-run

wl render --dry-run

Produces a render plan without writing files. Use this to preview what wl sync would do.

Ownership headers

Every generated file includes an ownership header:

<!--
Generated by wl.
Workspace: wksp_platform_api_01
Package: @acme/security-review@1.4.2
Object: sha256:abc123...
Do not edit directly unless you intend to create a local override.
-->

For files that cannot include comments (e.g., JSON), ownership metadata is stored in .loom/state.json.

Merging shared files

Some providers use shared config files. For example, multiple packages may contribute entries to .claude/settings.json. Workloom merges these deterministically:

1. Collect all assets targeting the same output file
2. Sort by package name for stable ordering
3. Deep-merge objects (settings) or concatenate arrays (hooks)
4. Write the merged result with combined ownership metadata

Projection policies

Policy	Behavior
generated_local	Generated locally, typically gitignored
committed_projection	Must be committed to the repo (e.g., Copilot instructions)
user_local	Written to user home dir (deferred to later phases)
manual_review	Requires human review before apply
approval_required	Requires explicit approval in the approval ledger
forbidden	Blocked entirely by policy