Versioning Concepts

SkillMeat automatically tracks every change to your artifacts through an immutable versioning system. This guide explains the core concepts behind how SkillMeat manages versions and why this design matters for your workflows.

What Are Versions?

A version is a complete snapshot of an artifact at a point in time. Every modification creates a new version:

• When you save changes — Update artifact content
• When you sync from upstream — Pull changes from your collection
• When you import artifacts — Add from marketplace or GitHub
• When you restore a previous version — Creates a new version with restored content

Each version is immutable — once created, it never changes. This creates a complete audit trail of your artifact's evolution.

How SkillMeat Tracks Changes

Every Change Creates a Version

Unlike traditional version control where you manually create commits, SkillMeat automatically creates a version for every operation:

Timeline of artifact "canvas-utils"

v1.0.0 (Base version)
  ↓ [You add new feature]
v1.1.0 (Local modification)
  ↓ [Upstream releases improvement]
v1.2.0 (Sync pulls upstream)
  ↓ [You customize for your project]
v1.3.0 (Local modification)
  ↓ [You restore v1.1.0 for testing]
v1.4.0 (Restore creates new version with v1.1.0's content)

Change Attribution

Every version tracks where each change originated with three categories:

Upstream Changes (Blue Badge) - Changes pulled from your collection or upstream source - Safe to apply, represents improvements from maintainers - Example: Bug fix in a skill pulled from GitHub

Local Modifications (Amber Badge) - Changes made locally in your project - Your customizations and project-specific adjustments - Example: Configuration parameter you added for your use case

Conflicting Changes (Red Badge) - Both upstream and local versions modified the same area - Requires manual decision when merging - Example: You added error logging, but upstream also modified error handling

Version Hash Semantics

Content-Addressed Versions

SkillMeat uses content hashing to identify versions. The version hash is derived from the artifact's content:

• Deterministic — Same content always produces the same hash
• Immutable — Hash never changes because content never changes
• Unique identifier — Each version has exactly one hash
• Linkable — Parent/child relationships tracked through hashes

Why This Matters

Content-addressed versioning provides several benefits:

No Confusion: Two identical versions have identical hashes. You know exactly what you're getting.

Integrity: If content changes, the hash changes. You can't accidentally get corrupted versions.

Deduplication: Identical versions aren't duplicated in storage.

Safe Restores: Restoring v1.2.0 always gives you exactly the same content, even if it happened months ago.

Example: Version Hashes

Version: v1.2.0
Content Hash: abc123def456789...
Files:
  - utils.py (modified)
  - config.yml (added)
  - README.md (unchanged)

→ Any change to any file produces a different hash
→ This hash is the permanent identifier for v1.2.0

Automatic Version Tracking

Save Operations

When you save changes to an artifact:

1. SkillMeat computes the new content hash
2. Creates a new version entry with that hash
3. Records who made the change (collection, project, or user)
4. Stores timestamp and change summary
5. Previous version remains unchanged for recovery

Sync Operations

When you sync with upstream:

1. SkillMeat detects new versions in your collection
2. Creates version entry for each change pulled
3. Attributes changes as "upstream" origin
4. Preserves local modifications if merged
5. Creates new version with merged content

Import Operations

When you import from marketplace or GitHub:

1. SkillMeat fetches the artifact
2. Creates initial version entry
3. Records source (GitHub URL, marketplace ID)
4. Stores any metadata from source
5. Sets up upstream tracking for future syncs

Restore Operations

When you restore a previous version:

1. SkillMeat retrieves the target version's content
2. Creates a new version (non-destructive)
3. New version has restored content but new hash
4. Original version remains in history
5. Creates version entry with "restored" origin

This is crucial: restoring is not reverting. You're not going backwards in the timeline — you're creating a new forward entry that matches an old version's content.

Version Relationships

Versions form a graph where each version can have a parent version:

v1.0.0 (initial import from GitHub)
  ↓
v1.1.0 (sync pulled v1.1.0 from upstream)
  ├─→ v1.2.0 (you customized locally)
  │     ↓
  │   v1.3.0 (sync merged upstream v1.1.5 with your v1.2.0)
  │
  └─→ v1.1.5 (alternative: you restored v1.1.0, then synced again)

Parent-Child Relationships

• Parent: The previous version before a change
• Child: The new version created by the change
• Common Ancestor: Shared base version when comparing branches

These relationships enable: - Showing version history as a timeline - Three-way merging (base + your changes + upstream changes) - Understanding divergence between versions - Recovering from mistakes by finding common ancestors

Immutability & Safety

Why Immutability Matters

Once a version is created, it never changes:

Auditability: You can trust the historical record. No version is accidentally modified later.

Recovery: Restoring v1.2.0 always gives you exactly what was there when v1.2.0 was created.

Collaboration: Multiple people can reference the same version ID and know they're talking about identical content.

Safety: You can't corrupt old versions. Every operation creates new versions, leaving old ones pristine.

Safe Restore Pattern

Restoring a version is always safe because it creates a new version:

# Before restore
v1.0 → v1.1 → v1.2 (current)

# Command: restore v1.0

# After restore
v1.0 → v1.1 → v1.2 → v1.3 (restored copy of v1.0)
                    ↑ new version, preserves v1.2

You never lose work. The "restore" is really a "create new version with old content."

Version History for Recovery

Scenarios Where Versioning Helps

Accidental Sync - Synced upstream when you meant to keep local changes - Restore your previous version → Creates new version with your content - Old version still there in history

Unwanted Merge - Merged conflicting changes incorrectly - Restore the pre-merge version → Creates new version - Review merge again with correct strategy

Corruption or Corruption Detection - Artifact was corrupted (detected by hash mismatch) - Restore last good version → Creates new version from uncorrupted content - Root cause investigation preserved in history

Exploration & Rollback - Testing an upstream change that didn't work - Restore previous version → Creates new version reverting the test - Keeps both test version and revert in history

Related Topics

For hands-on usage of versioning features:

• Version History & Restore — How to view, compare, and restore versions in the UI
• Syncing Changes — How syncing creates versions through upstream changes
• Enterprise Version Management — Advanced version features for teams

Key Takeaways

1. Every change is tracked — Saves, syncs, imports, and restores all create versions
2. Versions are immutable — Once created, never modified
3. Content-addressed — Versions identified by content hash, ensuring integrity
4. Non-destructive restore — Restoring creates new version, preserves current work
5. Complete audit trail — Full history with change origins and timestamps
6. Safe by design — No operation can corrupt previous versions