pijul-sparse-skills

Sparsity-preserving skill versioning where changes are stored as morphisms, not materialized states.

Trit: 0 (ERGODIC) - Coordinator role for projection gate decisions

---

Philosophy

Default: SPARSE Mode

┌─────────────────────────────────────────────────────────┐
│  SPARSE (default)                                       │
│  - Changes stored as patches (morphisms)                │
│  - No materialization unless required                   │
│  - Lazy evaluation of skill state                       │
│  - Minimal storage footprint                            │
└─────────────────────────────────────────────────────────┘

Projection Only When:

Trigger	Description	GF(3)
--materialize	Explicit flag	Any
trit == 0	ERGODIC coordination point	0
--archive	Explicit archive	Any
Conflict	Resolution requires full state	Any

---

Categorical Foundation

Patches as Morphisms in Cat(Skills)

Ob(C) = { skill states }
Mor(C) = { patches transforming states }

For patches p, q:
  p ⊥ q (independent) ⟹ p;q = q;p (commute)

Sparsity via Lazy Evaluation

# Sparse representation (default)
struct SparseSkill
    base_hash::UInt64      # Root state reference
    patches::Vector{Patch}  # Morphism chain, not applied
end

# Materialized only on demand
function materialize(s::SparseSkill)
    foldl(apply, s.patches; init=load(s.base_hash))
end

---

GF(3) Projection Gates

Gate Logic

function should_project(skill::Skill, flags::Flags)::Bool
    # Explicit materialization requested
    flags.materialize && return true
    
    # ERGODIC trit forces coordination checkpoint
    skill.trit == 0 && return true
    
    # Explicit archive
    flags.archive && return true
    
    # Conflict requires full state
    has_conflicts(skill) && return true
    
    # Otherwise: stay sparse
    return false
end

Trit-Based Behavior

trit = -1 (MINUS/Validator):
  → Verify patch integrity without materializing
  → Check commutativity conditions
  → Validate GF(3) conservation
  
trit = 0 (ERGODIC/Coordinator):
  → PROJECT: Create materialized checkpoint
  → Coordinate merge points
  → Synchronize distributed states
  
trit = +1 (PLUS/Generator):
  → Generate new patches
  → Create without materializing target
  → Lazy forward references

---

Workflow Examples

Record Skill Change (Sparse)

cd .agents/skills/my-skill

# Edit SKILL.md
echo "new content" >> SKILL.md

# Record as patch (NOT materialized)
pijul record -m "Add GF(3) section"
# Stores: Patch{add_lines: [...], hash: 0x...}

Sync Skills (Sparse Pull)

# Pull only patch metadata
pijul pull --partial origin

# View pending patches without applying
pijul log --pending

# Apply lazily (on access)
cat SKILL.md  # Materializes only this file

Force Materialization (ERGODIC Gate)

# Explicit checkpoint
pijul reset --materialize

# Or via trit-aware tool
skill-checkpoint my-skill --trit 0

---

Integration Patterns

With flox-mcp

;; Install pijul via flox MCP
(flox-install "pijul")

;; Record skill change
(shell "pijul" "record" "-m" (str "Update " skill-name))

;; Sparse pull from upstream
(shell "pijul" "pull" "--partial" upstream-url)

With structured-decomp

# Tree decomposition of skill graph
tree = decompose(skill_graph)

# Each bag gets sparse representation
for bag in tree.bags
    bag.skills = map(to_sparse, bag.skills)
end

# Sheaf gluing respects sparsity
glue!(tree)  # Only materializes at boundaries

With Gay.jl Colors

using Gay

# Patch hash → color for visual diff
function patch_color(patch::Patch)
    seed = reinterpret(UInt64, patch.hash)
    Gay.color_at(seed, 1)
end

# GF(3) conservation across patch chain
function verify_chain(patches::Vector{Patch})
    trits = [patch.trit for patch in patches]
    sum(trits) % 3 == 0
end

---

Delta-State CRDT Bridge

Patches as Delta-States

Pijul Patch ≅ Delta-CRDT Update

Both:
  - Commutative when independent
  - Compose via join semilattice
  - Support partial replication

Merkle Search Tree Index

skills/
├── .pijul/
│   ├── patches/       # Merkle tree of patches
│   ├── sparse-index/  # Hash → patch mapping
│   └── projection-log # When/why materialized

---

Commands

Check Sparsity Status

pijul-sparse status
# Output:
#   my-skill: SPARSE (3 pending patches)
#   other-skill: MATERIALIZED (checkpoint 2024-01-07)

Force Projection

pijul-sparse project my-skill --reason "coordination checkpoint"

Verify Conservation

pijul-sparse verify-gf3
# Output:
#   Chain: patch_a(-1) + patch_b(0) + patch_c(+1) = 0 ✓

---

References

• pijul skill - Core VCS operations
• flox-mcp skill - Environment management
• structured-decomp skill - Tree decompositions
• Mimram/Di Giusto: Categorical Patch Theory
• Almeida et al: Delta-State CRDTs
• Merkle Search Trees (Auvolat/Taïani)
• Irmin/MRDTs (Tarides)

---

Triadic Composition

pijul-sparse-skills (0) + pijul (-1) + skill-creator (+1) = 0 ✓
     Coordinator          Validator      Generator

This skill coordinates the projection decision while pijul validates patches and skill-creator generates new content.