CultLib/src/GameCult.Caching
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Meta Vens 188d4ad88d C#: a whole-view write that stores a record differently mints it a later storedAt
A condition names a record by (stored schema id, storedAt), and that name must
say which bytes are stored. A single-file whole-view write (plain flush, or an
unconditional commit) re-encoded every record under its own type's id with the
storedAt it loaded, so the pair could name two byte strings: v1 shed a member
keeping storedAt, a second v2 cache restored v2's id keeping it again, and a v2
cache holding the original bytes committed its condition (Soul F6, A-B-A).

Now such a write stores a record under a later storedAt whenever it stores it
differently: under another id than it was loaded under, or with other bytes than
the file holds at that storedAt (a record written with the ids it minted at
load, for one). A record stored exactly as the file holds it keeps its storedAt.
The store's entries and the cache's take the id and storedAt the write gave them.

Tests: the A-B-A through commits and through plain flushes, with Expect and
ExpectUnchanged; a flush that re-encodes a record restamps the cache that
flushed (a condition holds straight after, SM12); a record stored unchanged keeps
its storedAt through commits and flushes; persisting load-minted ids gives a
later storedAt. The rolling-deploy test asserted v1's rewrite kept storedAt; it
now asserts a later one, since that rewrite is a new store of the record.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 15:25:22 +02:00
..
Contracts C#: a document type declares the older schema ids its records may sit under 2026-09-30 11:30:05 +02:00
CultAssetGuidKey.cs Studio: read and write sub-asset Addressables keys, warn on stale values 2026-09-17 19:48:45 +02:00
CultCache.cs C#: a whole-view write that stores a record differently mints it a later storedAt 2026-09-30 15:25:22 +02:00
CultDocumentContracts.cs C#: a document type declares the older schema ids its records may sit under 2026-09-30 11:30:05 +02:00
CultElementIds.cs C#: HoldsIds is read off the stored form each time a store writes 2026-09-29 23:46:50 +02:00
CultInspectorAttributes.cs Add model-owned record grouping: declaration, tree, create-in-group, ref labels 2026-09-29 12:09:25 +02:00
CultInspectorGrouping.cs Add model-owned record grouping: declaration, tree, create-in-group, ref labels 2026-09-29 12:09:25 +02:00
CultInspectorModel.cs Make group node id escaping injective 2026-09-29 14:03:58 +02:00
CultManagedDocument.cs Carry order as data: per-cache change Sequence, no delivery scheduler 2026-09-13 20:43:11 +02:00
CultSchemaConflictException.cs Writers derive the catalog from the records they write; the merging is deleted 2026-09-30 10:03:34 +02:00
CultSchemaTypeNames.cs Delete the CultCache MessagePack source generator 2026-09-13 23:38:08 +02:00
CultStoreUnreadableException.cs C#: compatible schema ids publish a schema on open, Mesh takes only the older layout, the refusal names its file 2026-09-30 06:54:17 +02:00
CultVariants.cs Variant overrides follow the plain-record outcome; bad writes and shared indexes are refused 2026-09-29 06:58:51 +02:00
GameCult.Caching.csproj Catalog writers merge entries that share an id; every reader resolves an id by its owner first 2026-09-30 08:17:59 +02:00
README.md Delete the CultCache MessagePack source generator 2026-09-13 23:38:08 +02:00
ReflectionExtensions.cs Rewrite CultCache as attribute-first storage 2026-05-08 01:13:15 +01:00

GameCult.Caching

GameCult.Caching is an attribute-driven typed cache with a canonical single-file MessagePack store. Domain models stay clean. The cache owns record keys, schema ids, timestamps, and persistence metadata instead of smearing that sludge across every class.

Authoring Model

Cacheable models are plain classes annotated with cache intent.

using GameCult.Caching;
using MessagePack;

[CultDocument("gamecult.item_data", "gamecult.item_data.v1")]
public sealed class ItemData
{
    [Key(0)]
    [CultName]
    public string Name = string.Empty;

    [Key(1)]
    [CultIndex]
    public string Category = string.Empty;

    [Key(2)]
    public int Value;
}

Available cache attributes:

  • CultDocument(schemaName, schemaVersion)
  • CultName
  • CultIndex(alias?)
  • CultGlobal
  • CultReference(targetType?, many: false)

CultDocumentRegistry builds every document descriptor by reflection over these attributes and MessagePack's [Key]/[IgnoreMember]; it is the only descriptor authority.

Main Concepts

Record keys and handles

CultCache gives each stored document a cache-owned CultRecordKey. You work with typed handles instead of forcing storage identity into the domain object.

var cache = new CultCache();
var handle = await cache.AddAsync(new ItemData
{
    Name = "Potion",
    Category = "Consumable",
    Value = 50
});

var potion = cache.Get<ItemData>(handle.Key);

Name and index lookups

Name and index lookups are driven from attributes, not manual registration.

var byName = cache.GetByName<ItemData>("Potion");
var byIndex = cache.GetByIndex<ItemData>("Category", "Consumable");

Explicit references

References stay explicit in the domain. The cache will resolve them on demand, but it will not quietly build an entire haunted object graph behind your back.

[CultDocument("gamecult.quest_data", "gamecult.quest_data.v1")]
public sealed class QuestData
{
    [Key(0)] public string Title = string.Empty;
    [Key(1)] [CultReference] public CultRecordRef<ItemData> Reward;
}

Persistence Shape

CultCache persistence is store-shaped, not entry-shaped:

  1. store header
  2. embedded schema catalog
  3. records

Each persisted record carries:

  • key
  • schemaId
  • storedAt
  • payload

The domain payload stays free of storage metadata.

Backing Store

CultCache now has one sanctioned persistence format:

  • SingleFileMessagePackBackingStore

It persists the whole store as:

  1. store format version
  2. embedded schema catalog
  3. persisted records

Each persisted record carries:

  • key
  • schemaId
  • storedAt
  • payload

Happy Path

using GameCult.Caching;
using GameCult.Caching.MessagePack;

var cache = await CultCacheMessagePack.OpenAsync("Data.msgpack");

var handle = await cache.UpsertAsync(new ItemData
{
    Name = "Potion",
    Category = "Consumable",
    Value = 50
});

await cache.FlushAsync();

If you want the explicit assembly rite, the lower-level CultCache + SingleFileMessagePackBackingStore path is still there. The helper is just the blessed front door.

Managed Documents And SoA Storage

Gameplay code keeps authoring normal typed documents. CultCache owns the record identity, reactive presentation, and CPU-local structure-of-arrays table behind that POCO surface.

[CultDocument("game.player_transform", "game.player_transform.v1")]
public sealed class PlayerTransform
{
    [CultName] public string Name = string.Empty;
    public float PositionX;
    public float PositionY;
    public int Health;
}

var player = cache.Document<PlayerTransform>(new CultRecordKey("player:alice"));

await player.ReplaceAsync(new PlayerTransform
{
    Name = "Alice",
    PositionX = 4,
    PositionY = 8,
    Health = 100
});

using var subscription = player.Watch().Subscribe(current => Render(current));

player.Value!.Health = 90;
await player.CommitAsync();

var table = cache.Soa<PlayerTransform>();

Span<float> x = table.Column<float>(nameof(PlayerTransform.PositionX)).Span;
Span<float> y = table.Column<float>(nameof(PlayerTransform.PositionY)).Span;
Span<int> health = table.Column<int>(nameof(PlayerTransform.Health)).Span;

for (var row = 0; row < table.Count; row++)
{
    x[row] += 0.016f;
}

Document<T>() is the standard presentation. Soa<T>() exposes the cache-owned physical table for hot loops and diagnostics; it is not a second domain model callers have to maintain.

Persistence discipline

Persistence stays manual by default. Mutations mark the cache and attached backing stores dirty; nothing silently flushes every object write just because that felt convenient in the moment.

Useful surfaces:

  • CultCacheMessagePack.OpenAsync(path)
  • cache.IsDirty
  • store.IsDirty
  • cache.Document<T>(key)
  • cache.Soa<T>()
  • cache.UpsertAsync(document)
  • cache.FlushAllBackingStores()
  • cache.FlushAsync()
  • cache.FlushBackingStore(store)
  • cache.PrepareForReloadOrShutdown()
  • cache.PrepareForReloadOrShutdownAsync()
  • cache.FlushAttachedStoresOnDispose
  • store.FlushOnDispose

This is built for callers like Aquarium that want durable runtime state while still choosing when to pay the write cost.

Single-file MessagePack remains a single-writer format. The atomic replace path protects against partial writes, not competing writers trampling each other.

Schema migration diagnostics

CultCache does not quietly fall back from exact schemaId resolution to "close enough, probably." When a persisted schema drifts, the cache now emits a typed migration report describing:

  • exact vs compatible-drift resolution
  • ignored extra slots
  • defaulted missing slots
  • warning codes/messages

Compatibility rules and canonical fixture receipts live in Contracts/cultcache-schema-compatibility.md.