Rendering Pipeline

The rendering pipeline transforms canonical packages into provider-specific files. It's the heart of Workloom—where packages become Claude settings, Codex agents, and Cursor rules.

Render Plan Computation

A render plan is a computed diff between the desired state (what should be on disk) and the current state (what's actually on disk).

Workspace Manifest
(packages + versions)
        ↓
Load Canonical Packages
(from package registry)
        ↓
Validate Packages
(schema check, trust classification)
        ↓
Provider Adapter
(Claude, Codex, etc.)
        ↓
Desired State
(what files should exist + content)
        ↓
Current State
(what's actually on disk)
        ↓
Compute Diff
(render plan)
        ↓
Apply Render Plan
(write or update files)

Deterministic Rendering

Workloom guarantees: same input = byte-identical output, every time.

This is enforced through:

1. Canonical ordering. Multi-package merges use alphabetical ordering.
2. Deterministic serialization. JSON, TOML, and Markdown output is formatted consistently.
3. Content addressing. Each input is identified by SHA-256 hash.
4. Contract testing. Renderers are tested against fixtures to ensure determinism.

Multi-Package Merge Strategy

When a workspace includes multiple packages, Workloom merges them deterministically.

Merge Order

1. By target. Each workspace target resolves packages independently.
2. Alphabetically. Multiple packages at the same target merge in alphabetical order by scope + name.
3. Section separators. Each package's content is marked with a comment.

Ownership State Machine

Every Workloom-owned file is in one of five states:

State	Meaning	Action on wl sync
owned_clean	File matches last applied version	Safe to update
owned_missing	File was deleted	Recreate from desired state
owned_locally_modified	Developer edited the file	Fail — requires explicit resolution
owned_conflict	Both local and desired state changed	Fail — requires diff review
user_owned	Not managed by Workloom	Never touched

Drift Detection

Drift detection happens in multiple passes:

1. Hash Mismatch — Compare current hash to expected
2. Missing Files — Check file existence
3. Unknown Files — Scan for unexpected Workloom files
4. Provider Mismatch — Verify providers match config

Next Steps

• Learn about drift detection in practice
• Set up multi-package merges
• Understand trust gates