CultLib/src/GameCult.Caching
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Meta Vens a11d30fce2 C#: a whole-view write lays back a record under an id its type does not own
C2a F2, widened by Self: records and catalog entries a runtime does not own
survive its writes byte for byte. The schema-identity probe showed a C#
rewrite restamping every other runtime's record to its sha256 id and
dropping their catalog entries.

- The single-file store remembers, per key, a record it loaded under an id
  its type neither owns nor declares compatible (resolved through the
  catalog's schema name or an entry pointing at a local id), with the entry
  that published it. While the store still holds the entry it loaded, a
  whole-view write (flush or unconditional commit) lays that record back
  with its id, storedAt, bytes and catalog entry. A write of the record
  itself still stores it under the type's own id.
- A record published by an entry under the type's own id is this schema's
  and is re-encoded as before (the registered entry wins its own id).
- A laid-back record's load-minted element ids stay in memory only, so
  MintElementIds still rewrites it.
- The rolling-deploy tests lose their premise: an older version's whole
  view no longer sheds a newer record's member. They now pin that it lays
  the record back and the newer cache's condition holds; the A-B-A test
  keeps F6's defence through an explicit older write.
- Contract: the stamp and the lay-back rule in the persistence format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 21:20:11 +02:00
..
Contracts C#: a whole-view write lays back a record under an id its type does not own 2026-09-30 21:20:11 +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 lays back a record under an id its type does not own 2026-09-30 21:20:11 +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 C#: a record no registered type claims is carried untouched, and a write over it is refused 2026-09-30 20:50:15 +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.