2026-06-27 17:28:15 +01:00
|
|
|
using System;
|
|
|
|
|
using System.IO;
|
|
|
|
|
using System.Linq;
|
|
|
|
|
using System.Security.Cryptography;
|
|
|
|
|
using GameCult.Caching;
|
|
|
|
|
using GameCult.Caching.MessagePack;
|
|
|
|
|
|
|
|
|
|
namespace GameCult.Mesh
|
|
|
|
|
{
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Schema metadata used when publishing one raw document payload as a CultCache single-file snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public sealed class CultMeshSingleFileDocumentSchema
|
|
|
|
|
{
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Creates schema metadata for a single-file document publication.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public CultMeshSingleFileDocumentSchema(string schemaId, string schemaName, string schemaVersion)
|
|
|
|
|
{
|
|
|
|
|
if (string.IsNullOrWhiteSpace(schemaId)) throw new ArgumentException("Value must be non-empty.", nameof(schemaId));
|
|
|
|
|
if (string.IsNullOrWhiteSpace(schemaName)) throw new ArgumentException("Value must be non-empty.", nameof(schemaName));
|
|
|
|
|
if (string.IsNullOrWhiteSpace(schemaVersion)) throw new ArgumentException("Value must be non-empty.", nameof(schemaVersion));
|
|
|
|
|
|
|
|
|
|
SchemaId = schemaId;
|
|
|
|
|
SchemaName = schemaName;
|
|
|
|
|
SchemaVersion = schemaVersion;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Gets the content-derived schema identifier.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public string SchemaId { get; }
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Gets the stable schema name.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public string SchemaName { get; }
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Gets the schema version.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public string SchemaVersion { get; }
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Gets or sets an optional canonical schema description.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public string CanonicalSchemaJson { get; set; } = string.Empty;
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Gets or sets compatible schema identifiers accepted for this document.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public string[] CompatibleSchemaIds { get; set; } = Array.Empty<string>();
|
|
|
|
|
|
|
|
|
|
internal CultSchemaCatalogEntry ToCatalogEntry(byte[] payload)
|
|
|
|
|
{
|
|
|
|
|
return new CultSchemaCatalogEntry
|
|
|
|
|
{
|
|
|
|
|
SchemaId = SchemaId,
|
|
|
|
|
SchemaName = SchemaName,
|
|
|
|
|
SchemaVersion = SchemaVersion,
|
|
|
|
|
ContentHash = StableHash(payload),
|
|
|
|
|
CanonicalSchemaJson = CanonicalSchemaJson,
|
|
|
|
|
CompatibleSchemaIds = CompatibleSchemaIds
|
|
|
|
|
.Append(SchemaId)
|
|
|
|
|
.Where(candidate => !string.IsNullOrWhiteSpace(candidate))
|
|
|
|
|
.Distinct(StringComparer.Ordinal)
|
|
|
|
|
.ToArray(),
|
|
|
|
|
Members = Array.Empty<CultSchemaMemberCatalogEntry>()
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
private static string StableHash(byte[] payload)
|
|
|
|
|
{
|
|
|
|
|
if (payload == null || payload.Length == 0)
|
|
|
|
|
return "empty";
|
|
|
|
|
|
|
|
|
|
using var sha = SHA256.Create();
|
|
|
|
|
return BitConverter.ToString(sha.ComputeHash(payload)).Replace("-", "", StringComparison.Ordinal).ToLowerInvariant();
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
public static partial class CultMesh
|
|
|
|
|
{
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Writes one typed document as a canonical single-file MessagePack CultCache snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public static void WriteSingleFileDocument<TDocument>(
|
|
|
|
|
string path,
|
|
|
|
|
CultRecordKey key,
|
|
|
|
|
TDocument document,
|
|
|
|
|
string? storedAt = null,
|
|
|
|
|
CultDocumentRegistry? registry = null)
|
|
|
|
|
where TDocument : class
|
|
|
|
|
{
|
|
|
|
|
if (document == null) throw new ArgumentNullException(nameof(document));
|
|
|
|
|
|
|
|
|
|
var resolvedRegistry = registry ?? CultDocumentRegistry.Shared;
|
|
|
|
|
var descriptor = resolvedRegistry.GetRequired<TDocument>();
|
2026-09-29 19:40:36 +02:00
|
|
|
// Element ids are decided as a cache write decides them, before anything is written: an unset id is minted, a
|
|
|
|
|
// refused list refuses the write, and the file is marked when it holds an id. A failed write gives the ids back.
|
2026-10-15 01:21:22 +02:00
|
|
|
var ids = CultElementIds.Plan(typeof(TDocument), document, key.Value, deterministic: false);
|
2026-09-29 19:40:36 +02:00
|
|
|
ids.Apply();
|
|
|
|
|
try
|
|
|
|
|
{
|
|
|
|
|
WriteSingleFileDocumentPayload(
|
|
|
|
|
path,
|
|
|
|
|
key,
|
|
|
|
|
descriptor.ToCatalogEntry(),
|
|
|
|
|
storedAt,
|
|
|
|
|
CultDocumentMessagePackSerialization.SerializeUntyped(document, typeof(TDocument)),
|
2026-10-15 01:21:22 +02:00
|
|
|
CultElementIds.Holds(typeof(TDocument), document),
|
2026-10-14 23:35:31 +02:00
|
|
|
resolvedRegistry);
|
2026-09-29 19:40:36 +02:00
|
|
|
}
|
|
|
|
|
catch
|
|
|
|
|
{
|
|
|
|
|
ids.Undo();
|
|
|
|
|
throw;
|
|
|
|
|
}
|
2026-06-27 17:28:15 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Reads one typed document from a single-file MessagePack CultCache snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public static TDocument ReadSingleFileDocument<TDocument>(
|
|
|
|
|
string path,
|
|
|
|
|
CultRecordKey key,
|
|
|
|
|
CultDocumentRegistry? registry = null)
|
|
|
|
|
where TDocument : class
|
|
|
|
|
{
|
|
|
|
|
var resolvedRegistry = registry ?? CultDocumentRegistry.Shared;
|
|
|
|
|
var descriptor = resolvedRegistry.GetRequired<TDocument>();
|
|
|
|
|
var payload = ReadSingleFileDocumentPayload(path, key, descriptor.SchemaId);
|
2026-09-29 19:40:36 +02:00
|
|
|
var document = (TDocument)CultDocumentMessagePackSerialization.DeserializeUntyped(typeof(TDocument), payload);
|
|
|
|
|
// A load refuses what a write refuses, and mints the ids a cache load of the same file would mint.
|
2026-10-15 01:21:22 +02:00
|
|
|
CultElementIds.Plan(typeof(TDocument), document, key.Value, deterministic: true).Apply();
|
2026-09-29 19:40:36 +02:00
|
|
|
return document;
|
2026-06-27 17:28:15 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Writes one raw document payload as a canonical single-file MessagePack CultCache snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public static void WriteSingleFileDocumentPayload(
|
|
|
|
|
string path,
|
|
|
|
|
CultRecordKey key,
|
|
|
|
|
CultMeshSingleFileDocumentSchema schema,
|
|
|
|
|
string? storedAt,
|
|
|
|
|
byte[] payload)
|
|
|
|
|
{
|
|
|
|
|
if (schema == null) throw new ArgumentNullException(nameof(schema));
|
2026-10-14 23:35:31 +02:00
|
|
|
WriteSingleFileDocumentPayload(path, key, schema.ToCatalogEntry(payload), storedAt, payload, holdsIds: null, registry: null);
|
2026-06-27 17:28:15 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Reads one raw document payload from a single-file MessagePack CultCache snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public static byte[] ReadSingleFileDocumentPayload(
|
|
|
|
|
string path,
|
|
|
|
|
CultRecordKey key,
|
|
|
|
|
string expectedSchemaId)
|
|
|
|
|
{
|
|
|
|
|
if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path));
|
|
|
|
|
if (string.IsNullOrWhiteSpace(expectedSchemaId)) throw new ArgumentException("Value must be non-empty.", nameof(expectedSchemaId));
|
|
|
|
|
|
2026-10-03 01:59:42 +02:00
|
|
|
var snapshot = StoreAt(path).ReadDurable() ?? throw new FileNotFoundException($"CultCache document '{path}' does not exist.", path);
|
2026-06-27 17:28:15 +01:00
|
|
|
var record = snapshot.Records.SingleOrDefault(candidate => string.Equals(candidate.Key, key.Value, StringComparison.Ordinal))
|
|
|
|
|
?? throw new InvalidDataException($"CultCache document '{path}' does not contain record '{key.Value}'.");
|
|
|
|
|
|
|
|
|
|
if (!string.Equals(record.SchemaId, expectedSchemaId, StringComparison.Ordinal))
|
|
|
|
|
{
|
|
|
|
|
throw new InvalidDataException(
|
|
|
|
|
$"CultCache document '{path}' record '{key.Value}' has schema '{record.SchemaId}', expected '{expectedSchemaId}'.");
|
|
|
|
|
}
|
|
|
|
|
|
C# core: variant records, top-level Set overrides, resolution in the admitting hold
A variant record stores [baseKey, overrides[]] in record slot 4 and an empty
payload; the cache resolves it against its base inside the hold that admits it or
any record on its base chain, and re-resolves dependents in the same Apply, so a
base change reaches its variants with contiguous sequences and no stamp. Plain
Upsert at a variant key is refused (Flatten is the explicit way); cycle, missing
base, different concrete type, evicted base with survivors and a name that
shadows the base are refused naming the keys. Overrides of a dropped slot or an
undecodable value are ignored with a warning and reported as compatible drift.
The store writes cultcache.store.v2 only when it holds a variant and reads v1 and
v2. The codec pair CultInspectorModel took becomes CultCodec, shared with the
cache, which needs it to clone documents and overlay override values. The
directory store, CultMesh single-file reads and CultNet row building refuse a
variant by name until their own cuts.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 03:51:53 +02:00
|
|
|
RefuseVariant(path, record);
|
|
|
|
|
|
2026-06-27 17:28:15 +01:00
|
|
|
if (!PublishesSchema(snapshot.SchemaCatalog, expectedSchemaId))
|
|
|
|
|
{
|
|
|
|
|
throw new InvalidDataException(
|
|
|
|
|
$"CultCache document '{path}' does not publish schema '{expectedSchemaId}' in its catalog.");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return record.Payload;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/// <summary>
|
|
|
|
|
/// Reads the only raw document payload from a single-file MessagePack CultCache snapshot.
|
|
|
|
|
/// </summary>
|
|
|
|
|
public static byte[] ReadSingleFileDocumentPayload(
|
|
|
|
|
string path,
|
|
|
|
|
string expectedSchemaId)
|
|
|
|
|
{
|
|
|
|
|
if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path));
|
|
|
|
|
if (string.IsNullOrWhiteSpace(expectedSchemaId)) throw new ArgumentException("Value must be non-empty.", nameof(expectedSchemaId));
|
|
|
|
|
|
2026-10-03 01:59:42 +02:00
|
|
|
var snapshot = StoreAt(path).ReadDurable() ?? throw new FileNotFoundException($"CultCache document '{path}' does not exist.", path);
|
2026-06-27 17:28:15 +01:00
|
|
|
if (snapshot.Records.Length != 1)
|
|
|
|
|
{
|
|
|
|
|
throw new InvalidDataException(
|
|
|
|
|
$"CultCache document '{path}' must contain exactly one record.");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
var record = snapshot.Records[0];
|
|
|
|
|
if (!string.Equals(record.SchemaId, expectedSchemaId, StringComparison.Ordinal))
|
|
|
|
|
{
|
|
|
|
|
throw new InvalidDataException(
|
|
|
|
|
$"CultCache document '{path}' has schema '{record.SchemaId}', expected '{expectedSchemaId}'.");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
if (!PublishesSchema(snapshot.SchemaCatalog, expectedSchemaId))
|
|
|
|
|
{
|
|
|
|
|
throw new InvalidDataException(
|
|
|
|
|
$"CultCache document '{path}' does not publish schema '{expectedSchemaId}' in its catalog.");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return record.Payload;
|
|
|
|
|
}
|
|
|
|
|
|
C# core: variant records, top-level Set overrides, resolution in the admitting hold
A variant record stores [baseKey, overrides[]] in record slot 4 and an empty
payload; the cache resolves it against its base inside the hold that admits it or
any record on its base chain, and re-resolves dependents in the same Apply, so a
base change reaches its variants with contiguous sequences and no stamp. Plain
Upsert at a variant key is refused (Flatten is the explicit way); cycle, missing
base, different concrete type, evicted base with survivors and a name that
shadows the base are refused naming the keys. Overrides of a dropped slot or an
undecodable value are ignored with a warning and reported as compatible drift.
The store writes cultcache.store.v2 only when it holds a variant and reads v1 and
v2. The codec pair CultInspectorModel took becomes CultCodec, shared with the
cache, which needs it to clone documents and overlay override values. The
directory store, CultMesh single-file reads and CultNet row building refuse a
variant by name until their own cuts.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-29 03:51:53 +02:00
|
|
|
// A variant record's payload is empty; its document exists only as the cache resolves it against its base.
|
|
|
|
|
private static void RefuseVariant(string path, CultPersistedRecord record)
|
|
|
|
|
{
|
|
|
|
|
if (record.Variant != null)
|
|
|
|
|
throw new NotSupportedException(
|
|
|
|
|
$"CultCache document '{path}' record '{record.Key}' is a variant of '{record.Variant.BaseKey}'; " +
|
|
|
|
|
"CultMesh does not resolve document variants, open the store with a CultCache.");
|
|
|
|
|
}
|
|
|
|
|
|
2026-06-27 17:28:15 +01:00
|
|
|
private static void WriteSingleFileDocumentPayload(
|
|
|
|
|
string path,
|
|
|
|
|
CultRecordKey key,
|
|
|
|
|
CultSchemaCatalogEntry catalogEntry,
|
|
|
|
|
string? storedAt,
|
2026-09-29 19:40:36 +02:00
|
|
|
byte[] payload,
|
2026-10-14 23:35:31 +02:00
|
|
|
bool? holdsIds,
|
|
|
|
|
CultDocumentRegistry? registry)
|
2026-06-27 17:28:15 +01:00
|
|
|
{
|
|
|
|
|
if (string.IsNullOrWhiteSpace(path)) throw new ArgumentException("Value must be non-empty.", nameof(path));
|
|
|
|
|
if (catalogEntry == null) throw new ArgumentNullException(nameof(catalogEntry));
|
|
|
|
|
if (string.IsNullOrWhiteSpace(catalogEntry.SchemaId))
|
|
|
|
|
throw new ArgumentException("Catalog entry must include a schema id.", nameof(catalogEntry));
|
|
|
|
|
|
|
|
|
|
payload ??= Array.Empty<byte>();
|
2026-10-03 03:05:08 +02:00
|
|
|
// The write replaces this one key and copies every other record and catalog entry forward as the store holds them, under
|
|
|
|
|
// the store's lock. A typed write sees its document, so its ids decide the header; a raw payload is opaque (holdsIds null),
|
2026-10-14 23:35:31 +02:00
|
|
|
// so a file already marked stays marked. A typed write attaches the registry its payload was encoded with, so the write
|
|
|
|
|
// decides for copied records that registry can read; a raw payload attaches none and decides nothing. A store this runtime
|
|
|
|
|
// cannot read refuses the write instead of being overwritten.
|
|
|
|
|
var store = StoreAt(path);
|
|
|
|
|
if (registry != null)
|
|
|
|
|
store.AttachRegistry(registry);
|
|
|
|
|
store.ApplyWriteSet(
|
2026-10-03 03:05:08 +02:00
|
|
|
new[]
|
2026-06-27 17:28:15 +01:00
|
|
|
{
|
2026-10-03 03:05:08 +02:00
|
|
|
new CultStagedRecord(
|
|
|
|
|
new CultPersistedRecord
|
|
|
|
|
{
|
|
|
|
|
Key = key.Value,
|
|
|
|
|
SchemaId = catalogEntry.SchemaId,
|
|
|
|
|
StoredAt = string.IsNullOrWhiteSpace(storedAt) ? DateTimeOffset.UtcNow.ToString("O") : storedAt!,
|
|
|
|
|
Payload = payload
|
|
|
|
|
},
|
|
|
|
|
catalogEntry,
|
|
|
|
|
holdsIds)
|
|
|
|
|
},
|
|
|
|
|
Array.Empty<string>());
|
2026-06-27 17:28:15 +01:00
|
|
|
}
|
|
|
|
|
|
2026-10-03 01:59:42 +02:00
|
|
|
private static SingleFileMessagePackBackingStore StoreAt(string path) => new SingleFileMessagePackBackingStore(path);
|
|
|
|
|
|
2026-06-27 17:28:15 +01:00
|
|
|
private static bool PublishesSchema(CultSchemaCatalogEntry[] catalog, string schemaId)
|
|
|
|
|
{
|
|
|
|
|
return catalog.Any(entry =>
|
|
|
|
|
string.Equals(entry.SchemaId, schemaId, StringComparison.Ordinal) ||
|
|
|
|
|
entry.CompatibleSchemaIds.Any(candidate => string.Equals(candidate, schemaId, StringComparison.Ordinal)));
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|