design_ledger.hpp

Go to the documentation of this file.

#pragma once
 
// pulp::design — project design ledger.
//
// A DesignLedger is the small, CLI-maintained record of what a design/import
// project has produced and where it stands: each emitted artifact as a named,
// versioned asset with its source provenance, viewport, bound design system(s),
// and a review status. It is the resumability + audit substrate for multi-day,
// multi-agent design sessions — the answer to "which of these five ui.js
// revisions did the human approve" lives in the ledger, not in chat.
//
// Discipline (borrowed intentionally): only the CLI writes the ledger; skills
// and agents READ it (on resume, load the bound system's binding prompt without
// re-asking; never silently regenerate an approved version). Keeping writes on
// one path is what keeps the record trustworthy.
//
// This module is pure: parsing, serialization, and the in-memory operations
// carry no file IO. The CLI supplies the bytes and, for reconciliation, a
// predicate that answers whether an asset's file still exists on disk — so the
// core stays unit-testable and the "ledger vs reality" policy lives in one place.
//
// The serialized form is deterministic: assets are sorted by (name, version)
// and emitted in a fixed key order, so the ledger diffs cleanly in review.
 
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace pulp::design {

inline constexpr std::string_view kDesignLedgerVersion = "2026.07-design-ledger-v1";

enum class ReviewStatus { needs_review, approved, changes_requested };

const char* review_status_name(ReviewStatus status);

std::optional<ReviewStatus> review_status_from_name(std::string_view name);

struct LedgerAsset {
    std::string name;     
    std::string version;  
    std::string path;     
    std::string inherit_from;  
    std::string source;        
    std::string viewport;      
    std::vector<std::string> design_systems;  
    ReviewStatus status = ReviewStatus::needs_review;
};

struct DesignLedger {
    std::string ledger_version;       
    std::vector<LedgerAsset> assets;  
};

DesignLedger parse_ledger(const std::string& json);

std::string ledger_to_json(const DesignLedger& ledger);

LedgerAsset& upsert_asset(DesignLedger& ledger, const LedgerAsset& incoming);

std::vector<std::string> remove_asset(DesignLedger& ledger, const std::string& selector);

std::vector<std::string> reconcile(DesignLedger& ledger,
                                   const std::function<bool(const std::string& path)>& exists);
 
}  // namespace pulp::design