merge: C# render engine (MetaObjects.Render) [FR-004 Plan #2, phase 1]

dmealing · dmealing · commit 12e4cae85e71 · 2026-05-23T12:43:43.000-04:00
C# render engine renders the shared render-conformance corpus byte-identical to TS.
First C# codegen/runtime-tier component; CLAUDE.md scope reconciled.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -17,7 +17,7 @@ Equal weight. Three ship per-language today; the fourth is committed for 7.0.0:
 
 ## Status
 
-TypeScript reference implementation is **published to npm at `0.5.0`** (11 `@metaobjectsdev/*` packages on the `latest` tag; `cli` at `0.5.1`) — Projects D–G shipped end-to-end with 2124+ tests passing. Java port is in progress: H3a (loader restructure) shipped 2026-05-19; H3b (conformance harness) is active. **C# loader + conformance shipped** (loader, canonical serializer, and a `dotnet test` conformance runner that runs the full shared corpus; codegen + runtime remain out of scope for C#). Python is planned post-H3.
+TypeScript reference implementation is **published to npm at `0.5.0`** (11 `@metaobjectsdev/*` packages on the `latest` tag; `cli` at `0.5.1`) — Projects D–G shipped end-to-end with 2124+ tests passing. Java port is in progress: H3a (loader restructure) shipped 2026-05-19; H3b (conformance harness) is active. **C# loader + conformance shipped** (loader, canonical serializer, and a `dotnet test` conformance runner that runs the full shared corpus; metadata layer fully caught up — empty expected-failures ledger, incl. `template.*` + `origin.collection`). C# is now also growing the FR-004 codegen/runtime tier: the **render engine (`MetaObjects.Render`) ships** and renders the shared `fixtures/render-conformance` corpus byte-identical to TS; payload-VO codegen + `verify` are in progress. (This supersedes the earlier "codegen + runtime out of scope for C#" boundary, which dated from when C# was the stale laggard.) Python is planned post-H3.
 
 The 7.0.0 line is specced: FR-003 brings the Java OMDB persistence engine, metadata-driven schema migration, and dynamic projections onto current core; FR-004 builds the fourth pillar (cross-language prompt construction) on top of FR-003's projections. Both are design-stage plan-of-record (`docs/superpowers/specs/2026-05-22-fr-003-*` and `*-fr-004-*`), not yet implemented.
 
diff --git a/server/csharp/MetaObjects.Render.Tests/JsonPayload.cs b/server/csharp/MetaObjects.Render.Tests/JsonPayload.cs
@@ -0,0 +1,45 @@
+using System.Text.Json;
+
+namespace MetaObjects.Render.Tests;
+
+/// <summary>
+/// Converts a payload.json document into the plain object graph the render engine
+/// (Stubble) consumes: objects -> Dictionary&lt;string, object&gt;, arrays ->
+/// List&lt;object&gt;, integral numbers -> long (so "2" renders as "2", not "2.0"),
+/// fractional -> double, plus string/bool/null.
+/// </summary>
+public static class JsonPayload
+{
+    public static object? Parse(string json)
+    {
+        using var doc = JsonDocument.Parse(json);
+        return Convert(doc.RootElement);
+    }
+
+    private static object? Convert(JsonElement el) => el.ValueKind switch
+    {
+        JsonValueKind.Object => ToDict(el),
+        JsonValueKind.Array  => ToList(el),
+        JsonValueKind.String => el.GetString(),
+        JsonValueKind.Number => el.TryGetInt64(out var l) ? l : el.GetDouble(),
+        JsonValueKind.True   => true,
+        JsonValueKind.False  => false,
+        _                    => null,
+    };
+
+    private static Dictionary<string, object> ToDict(JsonElement el)
+    {
+        var d = new Dictionary<string, object>(StringComparer.Ordinal);
+        foreach (var p in el.EnumerateObject())
+            d[p.Name] = Convert(p.Value)!;
+        return d;
+    }
+
+    private static List<object> ToList(JsonElement el)
+    {
+        var list = new List<object>();
+        foreach (var e in el.EnumerateArray())
+            list.Add(Convert(e)!);
+        return list;
+    }
+}
diff --git a/server/csharp/MetaObjects.Render.Tests/MetaObjects.Render.Tests.csproj b/server/csharp/MetaObjects.Render.Tests/MetaObjects.Render.Tests.csproj
@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="../MetaObjects.Render/MetaObjects.Render.csproj" />
+  </ItemGroup>
+</Project>
diff --git a/server/csharp/MetaObjects.Render.Tests/RenderConformanceTests.cs b/server/csharp/MetaObjects.Render.Tests/RenderConformanceTests.cs
@@ -0,0 +1,87 @@
+using System.Text.Json;
+using Xunit;
+
+namespace MetaObjects.Render.Tests;
+
+/// <summary>
+/// Render-conformance corpus runner — the cross-language render guarantee.
+/// Each fixture dir under fixtures/render-conformance/ holds:
+///   meta.json          { "format": "&lt;RenderFormat&gt;" }
+///   template.mustache  the entry template
+///   partials/*.mustache  optional partials, referenced as `partials/&lt;name&gt;`
+///   payload.json       the render payload (pre-formatted primitives)
+///   expected.txt       byte-exact expected output
+/// The same shared corpus is rendered byte-for-byte identically by TS and C#.
+/// Mirrors typescript/packages/render/test/render-conformance.test.ts.
+/// </summary>
+public class RenderConformanceTests
+{
+    private static string CorpusRoot()
+    {
+        string root = AppContext.BaseDirectory;
+        while (!Directory.Exists(Path.Combine(root, "fixtures", "render-conformance")))
+        {
+            var parent = Directory.GetParent(root)?.FullName;
+            if (parent is null || parent == root)
+                throw new InvalidOperationException("fixtures/render-conformance not found");
+            root = parent;
+        }
+        return Path.Combine(root, "fixtures", "render-conformance");
+    }
+
+    public static IEnumerable<object[]> Fixtures()
+    {
+        var corpus = CorpusRoot();
+        foreach (var dir in Directory.GetDirectories(corpus).OrderBy(d => d, StringComparer.Ordinal))
+            yield return new object[] { Path.GetFileName(dir) };
+    }
+
+    private static InMemoryProvider ProviderFromPartials(string dir)
+    {
+        var map = new Dictionary<string, string>(StringComparer.Ordinal);
+        var pdir = Path.Combine(dir, "partials");
+        if (Directory.Exists(pdir))
+        {
+            foreach (var f in Directory.GetFiles(pdir, "*.mustache"))
+            {
+                var name = Path.GetFileNameWithoutExtension(f);
+                map[$"partials/{name}"] = File.ReadAllText(f);
+            }
+        }
+        return new InMemoryProvider(map);
+    }
+
+    [Theory]
+    [MemberData(nameof(Fixtures))]
+    public void RenderMatchesExpected(string name)
+    {
+        var dir = Path.Combine(CorpusRoot(), name);
+
+        var metaRaw = File.ReadAllText(Path.Combine(dir, "meta.json"));
+        var format = JsonDocument.Parse(metaRaw).RootElement.GetProperty("format").GetString()!;
+        var template = File.ReadAllText(Path.Combine(dir, "template.mustache"));
+        var payload = JsonPayload.Parse(File.ReadAllText(Path.Combine(dir, "payload.json")));
+        var expected = File.ReadAllText(Path.Combine(dir, "expected.txt"));
+        var provider = ProviderFromPartials(dir);
+
+        var actual = Renderer.Render(new RenderRequest
+        {
+            Template = template,
+            Payload = payload,
+            Provider = provider,
+            Format = format,
+        });
+
+        Assert.Equal(expected, actual);
+
+        // Determinism: identical across runs.
+        var again = Renderer.Render(new RenderRequest
+        {
+            Template = template,
+            Payload = payload,
+            Provider = provider,
+            Format = format,
+        });
+        Assert.Equal(actual, again);
+    }
+}
diff --git a/server/csharp/MetaObjects.Render.Tests/RenderTests.cs b/server/csharp/MetaObjects.Render.Tests/RenderTests.cs
@@ -0,0 +1,112 @@
+using Xunit;
+
+namespace MetaObjects.Render.Tests;
+
+/// <summary>
+/// Core render-engine unit tests, mirroring the engine block of
+/// typescript/packages/render/test/render.test.ts. (The verify-on-resolve guard
+/// tests are deferred to Phase 3 with the verify port.)
+/// </summary>
+public class RenderTests
+{
+    private static InMemoryProvider P(Dictionary<string, string>? m = null) =>
+        new(m ?? new Dictionary<string, string>(StringComparer.Ordinal));
+
+    private static string Render(string format, object? payload, IProvider provider,
+        string? template = null, string? @ref = null) =>
+        Renderer.Render(new RenderRequest
+        {
+            Template = template,
+            Ref = @ref,
+            Payload = payload,
+            Provider = provider,
+            Format = format,
+        });
+
+    private static Dictionary<string, object> Obj(params (string k, object? v)[] kv)
+    {
+        var d = new Dictionary<string, object>(StringComparer.Ordinal);
+        foreach (var (k, v) in kv) d[k] = v!;
+        return d;
+    }
+
+    [Fact]
+    public void Renders_a_variable_text_raw() =>
+        Assert.Equal("Hi Ada.", Render("text", Obj(("name", "Ada")), P(), template: "Hi {{name}}."));
+
+    [Fact]
+    public void Resolves_a_template_by_2layer_ref() =>
+        Assert.Equal("Hi Ada.", Render("text", Obj(("name", "Ada")),
+            P(new() { ["g/main"] = "Hi {{name}}." }), @ref: "g/main"));
+
+    [Fact]
+    public void Iterates_arrays_in_order() =>
+        Assert.Equal("a,b,c,", Render("text", Obj(("xs", new List<object> { "a", "b", "c" })), P(),
+            template: "{{#xs}}{{.}},{{/xs}}"));
+
+    [Fact]
+    public void Inverted_section_when_empty() =>
+        Assert.Equal("none", Render("text", Obj(("xs", new List<object>())), P(),
+            template: "{{^xs}}none{{/xs}}"));
+
+    [Fact]
+    public void Resolves_partials_through_the_provider() =>
+        Assert.Equal("A [z] B", Render("text", Obj(("x", "z")),
+            P(new() { ["g/main"] = "A {{> g/frag }} B", ["g/frag"] = "[{{x}}]" }), @ref: "g/main"));
+
+    [Fact]
+    public void Renders_a_partial_once_per_loop_iteration_in_item_context() =>
+        Assert.Equal("<1><2>", Render("text",
+            Obj(("items", new List<object> { Obj(("n", 1L)), Obj(("n", 2L)) })),
+            P(new() { ["g/main"] = "{{#items}}{{> g/row }}{{/items}}", ["g/row"] = "<{{n}}>" }),
+            @ref: "g/main"));
+
+    [Fact]
+    public void Detects_partial_cycles()
+    {
+        var ex = Assert.Throws<RenderException>(() =>
+            Render("text", Obj(), P(new() { ["g/a"] = "{{> g/b }}", ["g/b"] = "{{> g/a }}" }), @ref: "g/a"));
+        Assert.Contains("cycle", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public void Html_format_escapes_markup() =>
+        Assert.Equal("&lt;b&gt;&amp;", Render("html", Obj(("x", "<b>&")), P(), template: "{{x}}"));
+
+    [Fact]
+    public void Text_format_does_not_escape() =>
+        Assert.Equal("<b>&", Render("text", Obj(("x", "<b>&")), P(), template: "{{x}}"));
+
+    [Fact]
+    public void Triple_mustache_bypasses_escaping() =>
+        Assert.Equal("<b>", Render("html", Obj(("x", "<b>")), P(), template: "{{{x}}}"));
+
+    [Fact]
+    public void Csv_format_neutralizes_formula_injection() =>
+        Assert.Equal("'=cmd()", Render("csv", Obj(("x", "=cmd()")), P(), template: "{{x}}"));
+
+    [Fact]
+    public void Csv_format_quotes_values_with_commas() =>
+        Assert.Equal("\"a,b\"", Render("csv", Obj(("x", "a,b")), P(), template: "{{x}}"));
+
+    [Fact]
+    public void Spreadsheet_format_xml_escapes_and_guards_injection() =>
+        Assert.Equal("'=1&lt;2", Render("spreadsheet", Obj(("x", "=1<2")), P(), template: "{{x}}"));
+
+    [Fact]
+    public void Throws_on_unresolved_ref()
+    {
+        var ex = Assert.Throws<RenderException>(() => Render("text", Obj(), P(), @ref: "g/missing"));
+        Assert.Contains("unresolved", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public void Deterministic_same_inputs_identical_output()
+    {
+        var payload = Obj(("xs", new List<object> { 1L, 2L, 3L }));
+        var a = Render("text", payload, P(), template: "{{#xs}}{{.}}|{{/xs}}");
+        var b = Render("text", payload, P(), template: "{{#xs}}{{.}}|{{/xs}}");
+        Assert.Equal(a, b);
+        Assert.Equal("1|2|3|", a);
+    }
+}
diff --git a/server/csharp/MetaObjects.Render/Escapers.cs b/server/csharp/MetaObjects.Render/Escapers.cs
@@ -0,0 +1,95 @@
+// Format-driven escaping (FR-004 R7/R8). The render engine OWNS escaping (it does
+// not rely on the Mustache lib's HTML-only default), so behavior is identical
+// across language ports. `{{var}}` is escaped per format; `{{{var}}}` is raw.
+//
+// RenderFormat values are kept independent of the metadata package's
+// TEMPLATE_FORMATS to keep this engine a zero-core-dependency module. The two
+// sets are kept in lock-step by the render-conformance corpus.
+//
+// Ported from typescript/packages/render/src/escapers.ts.
+
+using System.Text;
+
+namespace MetaObjects.Render;
+
+/// <summary>Format-keyed escaper registry. Engine-owned; identical across ports.</summary>
+public static class Escapers
+{
+    public const string FORMAT_TEXT        = "text";
+    public const string FORMAT_HTML        = "html";
+    public const string FORMAT_XML         = "xml";
+    public const string FORMAT_CSV         = "csv";
+    public const string FORMAT_JSON        = "json";
+    public const string FORMAT_MARKDOWN    = "markdown";
+    public const string FORMAT_SPREADSHEET = "spreadsheet";
+
+    private static string Raw(string s) => s;
+
+    private static string Xml(string s) =>
+        s.Replace("&", "&amp;")
+         .Replace("<", "&lt;")
+         .Replace(">", "&gt;")
+         .Replace("\"", "&quot;")
+         .Replace("'", "&#39;");
+
+    // OWASP CSV/Excel formula-injection guard: neutralize a leading active char.
+    private static string InjectionGuard(string s) =>
+        s.Length > 0 && "=+-@\t\r".IndexOf(s[0]) >= 0 ? "'" + s : s;
+
+    private static string Csv(string s)
+    {
+        var v = InjectionGuard(s);
+        return v.IndexOfAny(['"', ',', '\n', '\r']) >= 0
+            ? "\"" + v.Replace("\"", "\"\"") + "\""
+            : v;
+    }
+
+    // Mirrors JS JSON.stringify(s).slice(1, -1): escape ", \, and control chars;
+    // nothing else (no HTML-safety escaping of < > &).
+    private static string Json(string s)
+    {
+        var sb = new StringBuilder(s.Length + 8);
+        foreach (char c in s)
+        {
+            switch (c)
+            {
+                case '"': sb.Append("\\\""); break;
+                case '\\': sb.Append("\\\\"); break;
+                case '\b': sb.Append("\\b"); break;
+                case '\f': sb.Append("\\f"); break;
+                case '\n': sb.Append("\\n"); break;
+                case '\r': sb.Append("\\r"); break;
+                case '\t': sb.Append("\\t"); break;
+                default:
+                    if (c < 0x20) sb.Append("\\u").Append(((int)c).ToString("x4"));
+                    else sb.Append(c);
+                    break;
+            }
+        }
+        return sb.ToString();
+    }
+
+    private static readonly Dictionary<string, Func<string, string>> Registry = new(StringComparer.Ordinal)
+    {
+        [FORMAT_TEXT]     = Raw,
+        [FORMAT_MARKDOWN] = Raw,
+        [FORMAT_HTML]     = Xml,
+        [FORMAT_XML]      = Xml,
+        [FORMAT_JSON]     = Json,
+        [FORMAT_CSV]      = Csv,
+        // XML-escape the content first, then guard — so the guard's leading quote is a
+        // literal apostrophe in the XML (which is what tells Excel "treat as text"),
+        // not itself escaped to &#39;.
+        [FORMAT_SPREADSHEET] = s => InjectionGuard(Xml(s)),
+    };
+
+    /// <summary>
+    /// The escaper for a format. Unknown formats throw (callers pass a value from
+    /// the closed TEMPLATE_FORMATS set). Defaults are not silently applied here —
+    /// the Renderer applies "text" when no format is given.
+    /// </summary>
+    public static Func<string, string> For(string format) =>
+        Registry.TryGetValue(format, out var fn)
+            ? fn
+            : throw new ArgumentException($"unknown render format \"{format}\"", nameof(format));
+}
diff --git a/server/csharp/MetaObjects.Render/MetaObjects.Render.csproj b/server/csharp/MetaObjects.Render/MetaObjects.Render.csproj
@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <LangVersion>12</LangVersion>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <RootNamespace>MetaObjects.Render</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Stubble.Core" Version="1.10.8" />
+  </ItemGroup>
+</Project>
diff --git a/server/csharp/MetaObjects.Render/Provider.cs b/server/csharp/MetaObjects.Render/Provider.cs
diff --git a/server/csharp/MetaObjects.Render/Renderer.cs b/server/csharp/MetaObjects.Render/Renderer.cs
diff --git a/server/csharp/MetaObjects.sln b/server/csharp/MetaObjects.sln
