Vivarium.Changeset

Vivarium.Changeset — .NET reference SDK

Construct, canonicalize, fingerprint, and validate Vivarium Changeset documents. Contains no apply logic — appliers (e.g. vivarium-stage) are consumers of this format, not part of this SDK.

No runtime dependencies beyond the BCL. Targets .NET 10. Same surface as the TypeScript reference SDK; fingerprints are byte-identical across the two (proven by the shared conformance fixtures, including the interop-jcs-edges vector).

Usage

using System.Text.Json.Nodes;
using Vivarium.Changeset;

// the artifact's current source, and the source the agent proposes
var currentSource = "export function LoanScreen() { /* current */ }";
var nextSource = "export function LoanScreen() { /* renders dueDate */ }";

var doc = new ChangesetBuilder(
        intent: "Add a due-date to the loan screen",
        producedBy: "my-agent",
        createdAt: DateTimeOffset.UtcNow.ToString("o")) // caller supplies the clock
    .AddSchemaOp((JsonObject)JsonNode.Parse("""
        { "op": "field.add", "entity": "loan",
          "field": { "name": "dueDate", "type": "date" },
          "explanation": "Stores the loan's due date" }
        """)!)
    .AddUiPatch(
        artifactId: "screen-loans",
        baseContent: currentSource, // null for creation
        newContent: nextSource,     // review diff + base fingerprint are derived, never hand-written
        explanation: "Renders the due-date field")
    .Finalize();                    // validates, stamps fingerprint — or throws with structured errors

Verifying on the consuming side. Unlike Finalize, these APIs report — they do not throw; a conforming applier checks the results and refuses on failure (spec §7):

var result = ChangesetValidator.Validate(doc);  // spec §8 — structure, vocabulary, diff consistency
if (!result.Valid)
    throw new InvalidOperationException($"refusing changeset: {string.Join(", ", result.Errors.Select(e => e.Path))}");

if (!ChangesetFingerprint.Verify(doc))          // spec §6 — content-addressed integrity
    throw new InvalidOperationException("refusing changeset: fingerprint mismatch");

Surface

Conformance

dotnet test runs the unit suite plus the shared spec/fixtures/ corpus — the same vectors the TypeScript SDK runs. The fixtures are generated by the TypeScript reference implementation; this SDK reproduces them exactly.