diff --git a/src/GameCult.Mesh/CultMeshOperationInvocationRecordFormatter.cs b/src/GameCult.Mesh/CultMeshOperationInvocationRecordFormatter.cs
new file mode 100644
index 00000000..f0426a7c
--- /dev/null
+++ b/src/GameCult.Mesh/CultMeshOperationInvocationRecordFormatter.cs
@@ -0,0 +1,79 @@
+using System;
+using MessagePack;
+using MessagePack.Formatters;
+
+#nullable enable
+
+namespace GameCult.Mesh
+{
+ ///
+ /// Reads the current structured invocation record and the legacy operation-id string.
+ ///
+ public sealed class CultMeshOperationInvocationRecordFormatter :
+ IMessagePackFormatter
+ {
+ private const int FieldCount = 5;
+
+ ///
+ public void Serialize(
+ ref MessagePackWriter writer,
+ CultMeshOperationInvocationRecord? value,
+ MessagePackSerializerOptions options)
+ {
+ if (value == null)
+ {
+ writer.WriteNil();
+ return;
+ }
+
+ writer.WriteArrayHeader(FieldCount);
+ writer.Write(value.OperationId);
+ writer.Write(value.SchemaId);
+ writer.Write(value.RouteKind);
+ writer.Write(value.RouteDescription);
+ writer.Write(value.IdempotencyKey);
+ }
+
+ ///
+ public CultMeshOperationInvocationRecord? Deserialize(
+ ref MessagePackReader reader,
+ MessagePackSerializerOptions options)
+ {
+ if (reader.TryReadNil())
+ return new CultMeshOperationInvocationRecord();
+
+ if (reader.NextMessagePackType == MessagePackType.String)
+ return new CultMeshOperationInvocationRecord(reader.ReadString());
+
+ if (reader.NextMessagePackType != MessagePackType.Array)
+ throw new MessagePackSerializationException(
+ $"CultMesh operation invocation must be a string or array, not {reader.NextMessagePackType}.");
+
+ options.Security.DepthStep(ref reader);
+ try
+ {
+ var fields = reader.ReadArrayHeader();
+ var operationId = ReadString(ref reader, fields, 0);
+ var schemaId = ReadString(ref reader, fields, 1);
+ var routeKind = ReadString(ref reader, fields, 2);
+ var routeDescription = ReadString(ref reader, fields, 3);
+ var idempotencyKey = ReadString(ref reader, fields, 4);
+ for (var index = FieldCount; index < fields; index++)
+ reader.Skip();
+ return new CultMeshOperationInvocationRecord(
+ operationId,
+ schemaId,
+ routeKind,
+ routeDescription,
+ idempotencyKey);
+ }
+ finally
+ {
+ reader.Depth--;
+ }
+ }
+
+ private static string ReadString(ref MessagePackReader reader, int fields, int index) =>
+ index < fields ? reader.ReadString() ?? "" : "";
+ }
+}
diff --git a/src/GameCult.Mesh/CultMeshPrimitives.cs b/src/GameCult.Mesh/CultMeshPrimitives.cs
index a7345ef2..165c9189 100644
--- a/src/GameCult.Mesh/CultMeshPrimitives.cs
+++ b/src/GameCult.Mesh/CultMeshPrimitives.cs
@@ -58,6 +58,7 @@ namespace GameCult.Mesh
/// Flat, transport-friendly fields for a CultMesh route hint.
///
[MessagePackObject]
+ [MessagePackFormatter(typeof(CultMeshRouteRecordFormatter))]
public sealed class CultMeshRouteRecord
{
/// Creates flat route fields.
@@ -3439,6 +3440,7 @@ namespace GameCult.Mesh
/// Flat, transport-friendly fields for a concrete CultMesh operation invocation.
///
[MessagePackObject]
+ [MessagePackFormatter(typeof(CultMeshOperationInvocationRecordFormatter))]
public sealed class CultMeshOperationInvocationRecord
{
/// Creates flat operation invocation fields.
diff --git a/src/GameCult.Mesh/CultMeshRouteRecordFormatter.cs b/src/GameCult.Mesh/CultMeshRouteRecordFormatter.cs
new file mode 100644
index 00000000..d0df7ebe
--- /dev/null
+++ b/src/GameCult.Mesh/CultMeshRouteRecordFormatter.cs
@@ -0,0 +1,54 @@
+using MessagePack;
+using MessagePack.Formatters;
+
+#nullable enable
+
+namespace GameCult.Mesh
+{
+ ///
+ /// Reads current structured route records and legacy locality strings.
+ ///
+ public sealed class CultMeshRouteRecordFormatter : IMessagePackFormatter
+ {
+ private const int FieldCount = 2;
+
+ public void Serialize(ref MessagePackWriter writer, CultMeshRouteRecord? value, MessagePackSerializerOptions options)
+ {
+ if (value == null)
+ {
+ writer.WriteNil();
+ return;
+ }
+
+ writer.WriteArrayHeader(FieldCount);
+ writer.Write(value.Kind);
+ writer.Write(value.Description);
+ }
+
+ public CultMeshRouteRecord? Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options)
+ {
+ if (reader.TryReadNil())
+ return new CultMeshRouteRecord();
+ if (reader.NextMessagePackType == MessagePackType.String)
+ return new CultMeshRouteRecord(reader.ReadString(), "");
+ if (reader.NextMessagePackType != MessagePackType.Array)
+ throw new MessagePackSerializationException(
+ $"CultMesh route must be a string or array, not {reader.NextMessagePackType}.");
+
+ options.Security.DepthStep(ref reader);
+ try
+ {
+ var fields = reader.ReadArrayHeader();
+ var kind = fields > 0 ? reader.ReadString() ?? "" : "";
+ var description = fields > 1 ? reader.ReadString() ?? "" : "";
+ for (var index = FieldCount; index < fields; index++)
+ reader.Skip();
+ return new CultMeshRouteRecord(kind, description);
+ }
+ finally
+ {
+ reader.Depth--;
+ }
+ }
+ }
+}
diff --git a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
index 4364aba3..e93da93c 100644
--- a/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
+++ b/tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
@@ -448,6 +448,48 @@ public sealed class CultMeshStreamingTests
payloadFields["value"].Should().Be("Raven");
}
+ [Test]
+ public void OperationInvocationRecord_ReadsLegacyStringAndWritesStructuredRecord()
+ {
+ var legacyPayload = MessagePackSerializer.Serialize(
+ "aetheria.entity.pilot.move",
+ CultDocumentMessagePackSerialization.Options);
+ var restored = MessagePackSerializer.Deserialize(
+ legacyPayload,
+ CultDocumentMessagePackSerialization.Options);
+ var currentPayload = MessagePackSerializer.Serialize(
+ restored,
+ CultDocumentMessagePackSerialization.Options);
+ var reader = new MessagePackReader(currentPayload);
+
+ restored.OperationId.Should().Be("aetheria.entity.pilot.move");
+ restored.SchemaId.Should().BeEmpty();
+ restored.RouteKind.Should().BeEmpty();
+ restored.IdempotencyKey.Should().BeEmpty();
+ reader.ReadArrayHeader().Should().Be(5);
+ reader.ReadString().Should().Be("aetheria.entity.pilot.move");
+ }
+
+ [Test]
+ public void RouteRecord_ReadsLegacyStringAndWritesStructuredRecord()
+ {
+ var legacyPayload = MessagePackSerializer.Serialize(
+ "SharedMemory",
+ CultDocumentMessagePackSerialization.Options);
+ var restored = MessagePackSerializer.Deserialize(
+ legacyPayload,
+ CultDocumentMessagePackSerialization.Options);
+ var currentPayload = MessagePackSerializer.Serialize(
+ restored,
+ CultDocumentMessagePackSerialization.Options);
+ var reader = new MessagePackReader(currentPayload);
+
+ restored.Kind.Should().Be("SharedMemory");
+ restored.Description.Should().BeEmpty();
+ reader.ReadArrayHeader().Should().Be(2);
+ reader.ReadString().Should().Be("SharedMemory");
+ }
+
[Test]
public void RouteRecord_FlattensAndParsesCrossRuntimeRouteKinds()
{