What a generated type promises that the type itself cannot say

The exemplar's first two sections each end with two static_asserts, and both
acceptance tests stripped them. The document recorded that as an open question:
they are an assertion about a generated type rather than something the schema
asked for, and where they belong was undecided.

They belong in the AST, and the decision turns on something already settled.
SourceFile.Imports are the one part of the AST that does not translate -- a C++
include path, a C# namespace and a Python module are different kinds of thing
that share a position, so each is carried as text for the language the file is
for. A compile-time predicate is the same shape of problem:
std::is_trivially_copyable_v<T> has no equivalent anywhere else, so there is no
shared idea underneath it to model. CompileTimeAssertion.Condition is therefore
text, which makes it consistent with an existing rule rather than a new special
case.

Only C++ has anything checked before the program runs. The other three write a
comment saying what was asserted, because a file that quietly loses a guarantee
looks exactly like one that still makes it.

The message goes on its own line. These are long by nature -- the predicate says
what is false and the message says why anyone cared -- and a compiler quoting
the whole declaration back is easier to read as two lines than as one very wide
one.

Both acceptance tests now assert the document's sections in full. That is the
point of this change: sections 1 and 2 are byte-identical to the specification
rather than byte-identical to it less two lines each.

Getting there needed the blank-line rule in one more place. A namespace and a
file separated every member unconditionally, which split the two assertions
about one type into two paragraphs. They now follow the same rule the members of
a type do, hoisted to a virtual on the base: always separate, unless a language
says otherwise, and C++ says two of a kind that say nothing about themselves
stay together.

485 tests pass, 477 before and 8 new, with 0 warnings across the solution.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AhoPJ5AbxP8QEBNxPQYEPk

Author: claude

CLAUDE.md

@@ -68,6 +68,11 @@ source in four target languages. The solution uses:
   one that cannot be assigned at all; a language without an initialiser list assigns at the top of
   the constructor instead. `ConstructionExpression` is the one expression that needs a type rather
   than a name, which is why it could not exist before `TypeReference` did.
+- `Coder/Ast/CompileTimeAssertion.cs` — what a generated type promises that the type itself cannot
+  say. Its `Condition` is text for the same reason `SourceFile.Imports` are: a compile-time predicate
+  is language-specific in a way most of the AST is not, and there is no shared idea underneath
+  `std::is_trivially_copyable_v<T>` to model. Only C++ has one; the others write a comment, because a
+  file that quietly loses a guarantee looks like one that still makes it.
 - `Coder/Languages/LanguageGeneratorBase.cs` — the emitters every generator shares.
 - `Coder/Languages/StandardLanguageGenerator.cs` — owns the node dispatch, so a derived
   generator supplies only the syntax its language does not share. `CSharpGenerator` deliberately

Coder.Graph/AstFields.cs

@@ -165,6 +165,12 @@ public static IReadOnlyList<AstField> Of(AstNode node)
 				new(ValueField, AstFieldKind.Text, enumMember.Value ?? string.Empty),
 			],
 
+			CompileTimeAssertion assertion =>
+			[
+				new("Condition", AstFieldKind.Text, assertion.Condition ?? string.Empty),
+				new("Message", AstFieldKind.Text, assertion.Message ?? string.Empty),
+			],
+
 			UsingAlias usingAlias =>
 			[
 				new("Name", AstFieldKind.Text, usingAlias.Name ?? string.Empty),
@@ -361,6 +367,9 @@ private static bool TryWriteDeclaration(AstNode node, string fieldName, string v
 			(EnumMember enumMember, "Name") => Assign(() => enumMember.Name = OrNull(value)),
 			(EnumMember enumMember, ValueField) => Assign(() => enumMember.Value = OrNull(value)),
 
+			(CompileTimeAssertion assertion, "Condition") => Assign(() => assertion.Condition = OrNull(value)),
+			(CompileTimeAssertion assertion, "Message") => Assign(() => assertion.Message = OrNull(value)),
+
 			(UsingAlias usingAlias, "Name") => Assign(() => usingAlias.Name = OrNull(value)),
 			(UsingAlias usingAlias, "AliasedType") => Assign(() => usingAlias.AliasedType = OrNull(value)),
 			(UsingAlias usingAlias, VisibilityField) =>

Coder.Graph/AstSchema.cs

@@ -434,7 +434,8 @@ public static bool Accepts(AstSlot slot, AstNode candidate)
 			// running at one, so it belongs to a class or to the document rather than inside a body.
 			AstSlotKind.Statement => candidate is not (Parameter or EntryPoint),
 			AstSlotKind.Member => candidate is FunctionDeclaration or VariableDeclaration or FieldDeclaration
-				or ClassDeclaration or EnumDeclaration or NamespaceDeclaration or UsingAlias or EntryPoint,
+				or ClassDeclaration or EnumDeclaration or NamespaceDeclaration or UsingAlias
+				or CompileTimeAssertion or EntryPoint,
 			AstSlotKind.EnumMember => candidate is EnumMember,
 			_ => false,
 		};

Coder.Test/Ast/CompileTimeAssertionTests.cs

@@ -0,0 +1,153 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace ktsu.Coder.Test.Ast;
+
+using ktsu.Coder.Ast;
+using ktsu.Coder.Graph;
+using ktsu.Coder.Languages;
+using ktsu.Coder.Serialization;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+/// <summary>
+/// Tests for <see cref="CompileTimeAssertion"/>: what a generated type promises that the type itself
+/// cannot say.
+/// </summary>
+/// <remarks>
+/// Only C++ has anything checked before the program runs, so this is the clearest case of the rule
+/// the whole AST follows — say what is true, and let each language say as much of it as it can. The
+/// other three write a comment rather than dropping it, because a file that quietly loses a
+/// guarantee looks exactly like one that still makes it.
+/// </remarks>
+[TestClass]
+public class CompileTimeAssertionTests
+{
+	/// <summary>
+	/// C++ writes the assertion, with the message on its own line.
+	/// </summary>
+	[TestMethod]
+	public void Cpp_WritesTheAssertion()
+	{
+		CompileTimeAssertion assertion = new(
+			"std::is_trivially_copyable_v<RigidBody>",
+			"RigidBody must be trivially copyable: it crosses the C# boundary and the wire as bytes");
+
+		Assert.AreEqual(
+			"static_assert(std::is_trivially_copyable_v<RigidBody>,\n"
+			+ "    \"RigidBody must be trivially copyable: it crosses the C# boundary and the wire as bytes\");\n",
+			new CppGenerator().Generate(assertion).ReplaceLineEndings("\n"));
+	}
+
+	/// <summary>
+	/// An assertion with nothing to say when it fails is still an assertion.
+	/// </summary>
+	[TestMethod]
+	public void Cpp_WritesAnAssertionWithNoMessage()
+	{
+		Assert.AreEqual(
+			"static_assert(sizeof(Handle) == 8);\n",
+			new CppGenerator().Generate(new CompileTimeAssertion("sizeof(Handle) == 8")).ReplaceLineEndings("\n"));
+	}
+
+	/// <summary>
+	/// A message with a quote in it is escaped rather than ending the string early.
+	/// </summary>
+	[TestMethod]
+	public void Cpp_EscapesTheMessage()
+	{
+		CompileTimeAssertion assertion = new("sizeof(T) == 8", "a \"T\" is eight bytes");
+
+		Assert.Contains("\\\"T\\\"", new CppGenerator().Generate(assertion), StringComparison.Ordinal);
+	}
+
+	/// <summary>
+	/// The other three have nothing checked before the program runs, so they say what was asserted
+	/// rather than dropping it.
+	/// </summary>
+	[TestMethod]
+	public void OtherLanguages_SayWhatWasAsserted()
+	{
+		CompileTimeAssertion assertion = new("std::is_standard_layout_v<RigidBody>", "layout must be stable");
+
+		Assert.Contains(
+			"// asserted at build time: std::is_standard_layout_v<RigidBody>",
+			new CSharpGenerator().Generate(assertion),
+			StringComparison.Ordinal);
+		Assert.Contains(
+			"# asserted at build time: std::is_standard_layout_v<RigidBody>",
+			new PythonGenerator().Generate(assertion),
+			StringComparison.Ordinal);
+		Assert.Contains(
+			"// asserted at build time: std::is_standard_layout_v<RigidBody>",
+			new JavaScriptGenerator().Generate(assertion),
+			StringComparison.Ordinal);
+	}
+
+	/// <summary>
+	/// Assertions about one type stay together, and are separated from the declaration they are about.
+	/// </summary>
+	/// <remarks>
+	/// The same rule the members of a type follow. Two of a kind that say nothing about themselves are
+	/// one block; a struct followed by an assertion is two.
+	/// </remarks>
+	[TestMethod]
+	public void Cpp_GroupsAssertionsAboutTheSameType()
+	{
+		SourceFile file = new("RigidBody.gen.hpp");
+		file.Members.Add(new ClassDeclaration("RigidBody") { Kind = TypeDeclarationKind.Struct });
+		file.Members.Add(new CompileTimeAssertion("std::is_trivially_copyable_v<RigidBody>", "bytes"));
+		file.Members.Add(new CompileTimeAssertion("std::is_standard_layout_v<RigidBody>", "offsets"));
+
+		string code = new CppGenerator().Generate(file).ReplaceLineEndings("\n");
+
+		Assert.Contains("};\n\nstatic_assert(", code, StringComparison.Ordinal);
+		Assert.Contains("\"bytes\");\nstatic_assert(", code, StringComparison.Ordinal);
+	}
+
+	/// <summary>
+	/// An assertion survives a round trip through YAML, and a clone carries it.
+	/// </summary>
+	[TestMethod]
+	public void Yaml_RoundTripsTheAssertion()
+	{
+		CompileTimeAssertion original = new("sizeof(Handle) == 8", "a handle is eight bytes");
+
+		string yaml = new YamlSerializer().Serialize(original);
+		CompileTimeAssertion restored = (CompileTimeAssertion)new YamlDeserializer().Deserialize(yaml)!;
+
+		Assert.AreEqual("sizeof(Handle) == 8", restored.Condition);
+		Assert.AreEqual("a handle is eight bytes", restored.Message);
+
+		CompileTimeAssertion clone = (CompileTimeAssertion)original.Clone();
+
+		Assert.AreEqual(original.Condition, clone.Condition);
+		Assert.AreEqual(original.Message, clone.Message);
+		Assert.AreNotSame(original, clone);
+	}
+
+	/// <summary>
+	/// A document says nothing for an assertion that asserts nothing.
+	/// </summary>
+	[TestMethod]
+	public void Yaml_WritesNothingForAnEmptyAssertion()
+	{
+		string yaml = new YamlSerializer().Serialize(new CompileTimeAssertion());
+
+		Assert.DoesNotContain("condition", yaml, StringComparison.Ordinal);
+		Assert.DoesNotContain("message", yaml, StringComparison.Ordinal);
+	}
+
+	/// <summary>
+	/// The editor can place one beside a declaration and edit both of its halves.
+	/// </summary>
+	[TestMethod]
+	public void Graph_AcceptsAndEditsAnAssertion()
+	{
+		NamespaceDeclaration components = new("holo::components");
+		CompileTimeAssertion assertion = new("sizeof(Handle) == 8");
+
+		Assert.IsTrue(AstSchema.TryAttach(components, AstSchema.SlotsOf(components)[0], assertion));
+		Assert.IsTrue(AstFields.TryWrite(assertion, "Message", "a handle is eight bytes"));
+
+		Assert.AreEqual("a handle is eight bytes", assertion.Message);
+	}
+}

Coder.Test/Languages/ExemplarHeaderTests.cs

@@ -81,6 +81,11 @@ enum class BodyKind : std::uint8_t
 		    BodyKind body_kind = BodyKind::Dynamic;
 		};
 
+		static_assert(std::is_trivially_copyable_v<RigidBody>,
+		    "RigidBody must be trivially copyable: it crosses the C# boundary and the wire as bytes");
+		static_assert(std::is_standard_layout_v<RigidBody>,
+		    "RigidBody must be standard layout for its field offsets to be stable");
+
 		}  // namespace holo::components
 		""";
 
@@ -136,6 +141,13 @@ private static SourceFile RigidBodyHeader()
 		NamespaceDeclaration components = new("holo::components");
 		components.Members.Add(rigidBody);
 
+		components.Members.Add(new CompileTimeAssertion(
+			"std::is_trivially_copyable_v<RigidBody>",
+			"RigidBody must be trivially copyable: it crosses the C# boundary and the wire as bytes"));
+		components.Members.Add(new CompileTimeAssertion(
+			"std::is_standard_layout_v<RigidBody>",
+			"RigidBody must be standard layout for its field offsets to be stable"));
+
 		SourceFile file = new("RigidBody.gen.hpp") { IsHeader = true };
 		file.HeaderComment.Add("Generated by holo_schemac. Do not edit.");
 		file.HeaderComment.Add("");

Coder.Test/Languages/ExemplarSemanticTypeTests.cs

@@ -60,6 +60,11 @@ [[nodiscard]] constexpr underlying value() const noexcept
 		private:
 		    underlying value_{};
 		};
+
+		static_assert(std::is_trivially_copyable_v<EntityId>,
+		    "EntityId must be trivially copyable: it appears in components");
+		static_assert(std::is_standard_layout_v<EntityId>,
+		    "EntityId must be standard layout for its field offsets to be stable");
 		""";
 
 	/// <summary>
@@ -114,6 +119,29 @@ private static ClassDeclaration EntityId()
 		return entity;
 	}
 
+	/// <summary>
+	/// The semantic type together with what is asserted about it.
+	/// </summary>
+	/// <returns>The file.</returns>
+	/// <remarks>
+	/// A file with no banner and no imports, because the document's section is the declaration and
+	/// the assertions beside it rather than a whole header. What the assertions say is the reason the
+	/// type can appear in a component at all.
+	/// </remarks>
+	private static SourceFile EntityIdWithAssertions()
+	{
+		SourceFile file = new("EntityId.gen.hpp");
+		file.Members.Add(EntityId());
+		file.Members.Add(new CompileTimeAssertion(
+			"std::is_trivially_copyable_v<EntityId>",
+			"EntityId must be trivially copyable: it appears in components"));
+		file.Members.Add(new CompileTimeAssertion(
+			"std::is_standard_layout_v<EntityId>",
+			"EntityId must be standard layout for its field offsets to be stable"));
+
+		return file;
+	}
+
 	/// <summary>
 	/// Builds one of the comparison operators, which are symmetric and so belong beside the type
 	/// rather than to either operand.
@@ -146,7 +174,7 @@ private static FunctionDeclaration Comparison(string symbol, string returnType)
 	public void Cpp_GeneratesTheSemanticTypeTheDocumentSpecifies() =>
 		Assert.AreEqual(
 			Expected.ReplaceLineEndings("\n").TrimEnd(),
-			new CppGenerator().Generate(EntityId()).ReplaceLineEndings("\n").TrimEnd());
+			new CppGenerator().Generate(EntityIdWithAssertions()).ReplaceLineEndings("\n").TrimEnd());
 
 	/// <summary>
 	/// A member is initialised rather than assigned, which is the only way to start one that cannot be

Coder/Ast/CompileTimeAssertion.cs

@@ -0,0 +1,84 @@
+// Copyright (c) 2023-2026 ktsu-dev contributors
+
+namespace ktsu.Coder.Ast;
+
+/// <summary>
+/// Something that must be true when the program is built rather than when it runs.
+/// </summary>
+/// <remarks>
+/// What a generated type promises is often not something the type itself can say. A struct that
+/// crosses a language boundary and the wire as raw bytes has to be trivially copyable and standard
+/// layout, and the moment that stops being true is the moment a saved file starts being wrong — so
+/// it is asserted where the type is declared, and the build fails rather than the save file.
+/// <para>
+/// <see cref="Condition"/> is text, and deliberately. A compile-time predicate is language-specific
+/// in a way most of the AST is not: <c>std::is_trivially_copyable_v&lt;T&gt;</c> has no equivalent
+/// anywhere else, so there is no shared idea underneath to model. It is carried the same way
+/// <see cref="SourceFile.Imports"/> are, and for the same reason — an assertion, like an import, is
+/// written for the language the file is for.
+/// </para>
+/// <para>
+/// Only C++ has this. Every other target here writes a comment saying what was asserted, because a
+/// generated file that silently drops a guarantee looks like one that still makes it.
+/// </para>
+/// </remarks>
+public class CompileTimeAssertion : AstNode
+{
+	/// <summary>
+	/// Initializes a new instance of the <see cref="CompileTimeAssertion"/> class.
+	/// </summary>
+	public CompileTimeAssertion()
+	{
+	}
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="CompileTimeAssertion"/> class.
+	/// </summary>
+	/// <param name="condition">The predicate that must hold, as the target language writes it.</param>
+	/// <param name="message">What to say when it does not.</param>
+	public CompileTimeAssertion(string condition, string? message = null)
+	{
+		Condition = condition;
+		Message = message;
+	}
+
+	/// <summary>
+	/// Gets or sets the predicate that must hold, as the target language writes it.
+	/// </summary>
+	public string? Condition { get; set; }
+
+	/// <summary>
+	/// Gets or sets what to say when the predicate does not hold.
+	/// </summary>
+	/// <remarks>
+	/// Worth writing rather than leaving to the compiler: the predicate says what is false and the
+	/// message says why anyone cared, and only the second tells whoever hits it what to do.
+	/// </remarks>
+	public string? Message { get; set; }
+
+	/// <summary>
+	/// Gets the type name of this node for serialization purposes.
+	/// </summary>
+	/// <returns>The name of the node type.</returns>
+	public override string GetNodeTypeName() => "CompileTimeAssertion";
+
+	/// <summary>
+	/// Creates a deep clone of this assertion.
+	/// </summary>
+	/// <returns>A new instance with the same properties.</returns>
+	public override AstNode Clone()
+	{
+		CompileTimeAssertion clone = new()
+		{
+			Condition = Condition,
+			Message = Message,
+		};
+
+		foreach ((string key, object? value) in Metadata)
+		{
+			clone.Metadata[key] = value;
+		}
+
+		return clone;
+	}
+}

Coder/Languages/CSharpGenerator.cs

@@ -61,6 +61,25 @@ protected override void GenerateInternal(AstNode node, CodeBlocker code)
 			case UnaryExpression unaryExpr:
 				GenerateUnaryExpression(unaryExpr, code, GetUnaryOperator(unaryExpr.Operator));
 				break;
+			default:
+				GenerateExpressionOrLeaf(node, code);
+				break;
+		}
+	}
+
+	/// <summary>
+	/// Emits an expression or a leaf.
+	/// </summary>
+	/// <param name="node">The node to emit.</param>
+	/// <param name="code">The writer to emit into.</param>
+	/// <remarks>
+	/// Split from the declarations only because one switch over every node the AST has is more
+	/// branches than the analyzer accepts. The line is the same one the AST already draws.
+	/// </remarks>
+	private void GenerateExpressionOrLeaf(AstNode node, CodeBlocker code)
+	{
+		switch (node)
+		{
 			case VariableReference varRef:
 				code.Write(varRef.Name);
 				break;
@@ -82,6 +101,9 @@ protected override void GenerateInternal(AstNode node, CodeBlocker code)
 			case NamespaceDeclaration namespaceDecl:
 				GenerateNamespace(namespaceDecl, code);
 				break;
+			case CompileTimeAssertion assertion:
+				WriteInexpressible(code, $"asserted at build time: {assertion.Condition}");
+				break;
 			case UsingAlias usingAlias:
 				GenerateUsingAlias(usingAlias, code);
 				break;