CultLib/unity/org.gamecult.cultlib/CHANGELOG.md

Changelog

All notable changes to this package are documented in this file.

[Unreleased]

Releases as 3.0.0 (major).

Breaking (major)

• A single-file store flush refuses a file it cannot read (empty, truncated, an unreadable stamp or body) with CultStoreUnreadableException and leaves the file as it is. A flush used to replace such a file. A write set cannot merge with a disk it cannot read, so the file is repaired or removed by its owner before the store writes again.
• A single-file store reads v1, v2 and v3 stamps and refuses v4 and later by name; a directory store reads v4 and v5 and refuses v6 and later by name. Each judges the stamp before the body, so an unreadable body never makes a newer store look like damage.
• A store is written in the format its content needs, and CultLib 2.0 refuses the newer ones by name. A single-file store holding a document variant is written as cultcache.store.v2, one holding an element id as cultcache.store.v3; a directory store holding an element id is written as cultcache.store.v5 (v4 otherwise). A store is marked only when a record actually holds an id or a variant. Upgrade readers before writers: a 2.0 reader that opens such a store is refused, not misread.
• Writes are write sets. A flush or commit replaces the records it staged and copies every other record forward as stored, under the store's lock, instead of rewriting the whole store from the cache's memory. A record the cache does not know is kept, and an untouched record keeps a dropped member's slot through every write (never reuse a dropped slot; see the schema-compatibility contract).
• A write or removal at a key whose stored record the writer does not own is refused with CultSchemaConflictException, and the file is left as it was. A writer owns a record whose schema id it declares (owns or lists compatible) and a record its type reads whole under compatible drift: that record is writable and is restamped under the type's own id on write, as in 2.0.1. A record a type reads only by dropping persisted slots stays read-only until its id is declared compatible, which accepts the loss (this differs from 2.0.1, which shed the slots silently). A cache owns through its registry; a cacheless CultMesh write owns through the catalog entry it writes.
• Registration refuses an owned object-list element type that has no [CultElementId] member (a public string with [Key]), naming the type and the list. Element ids let a write set merge a list by identity; a list of record references or plain values is a whole value and is not affected.
• The abstract and protected surface for store kinds outside this library changed. On SingleFileBackingStore, SerializeSnapshot and DeserializeSnapshot are replaced by the abstract SerializeStore, SerializeRecord, SerializeCatalogEntry and ReadStore, and the abstract SerializePayload(object) becomes SerializePayload(object document, Type documentType): a store encodes a document as the type it is given. On CacheBackingStore, Judging is removed, ToStoredDocument takes the record's version (record, version, catalog, deserialize, out report), and these protected members are new for a store kind to implement or call: HeaderFor, HeaderForWrite, Foreign, SetForeignRecords, Undeclared, RefuseUndeclared, RefuseUndeclaredOnDisk, RefuseRemovalOfUndeclared, Refuse, SameStoredIdentity, VersionOf, StoredAtOver, Overwrites, StagedChecks, StageChecks and JudgeChecks. MarkFlushSucceeded is unchanged. CacheBackingStore.ForeignRecords is new and public: the records a store holds under a schema id its cache does not declare.
• CultCommitRequest.Expected is now IReadOnlyList<(CultRecordKey Key, string? Version)> (it was a key with a schema id and a stored-at), CultCommitRequest.Checks is new, and ConditionsHold takes (IReadOnlyDictionary<string, string> durable, IEnumerable<CultStoredDocument> observed, IEnumerable<CultForeignRecord> foreign) in place of (IReadOnlyCollection<CultPersistedRecord>, IEnumerable<CultStoredDocument>). A store kind outside the library lists the record versions it holds and passes its foreign records.
• GameCult.Mesh: AsSchemaAlias<TAlias>() is removed from the interfaces ICultMeshDocumentHandle and ICultMeshCollectionHandle and from the classes CultMeshDocumentHandle and CultMeshCollectionHandle. Read the handle by the schema you mean.
• The element types of owned lists gain a public string Id member with [CultElementId], so their lists merge by identity: in GameCult.Mesh, CultMeshBodyDescriptor, CultMeshCdnChunkRef, CultMeshDiscoveryCandidateDocument, CultMeshEntityPrefabComponent, CultMeshEntityPrefabAssetRef and CultMeshEntityPrefabNode; in GameCult.Networking, CultWitnessContractPin, CultWitnessArtifactEntry and CultWitnessTimingEntry; in GameCult.Geometry, CultGeometryDomainNode, CultGeometryFeatureClaim and CultGeometryContributionRow. Code that matched those elements positionally by shape must set or read Id.
• CultNetDocumentRegistry.Register refuses a binding that claims a document type or a schema id another binding already holds, with CultSchemaConflictException; binding a type to the schema id it already holds still replaces that binding.
• InternalsVisibleTo GameCult.Mesh is removed from GameCult.Caching: CultMesh's single-file document helpers use the public ReadStoreSnapshot, WriteDocument, WriteRecord and CultCodec.DecodeDocument below.

Added

• A cacheless WriteRecord or WriteDocument, and an attach, hold the store's gate while they run, and user code they run (a document's property getters, a constructor while a copied record is read) now throws InvalidOperationException if it enters a cache it does not hold or a second store; it used to wait forever against an attach of the same store. A store call that queued on an attach that then failed runs under the gate that owns the store, not beside a cacheless call or a second cache's attach. An attach that fails takes its registry back, so a PullAll on the store afterwards is refused as unattached instead of loading records the next cache never sees. A cacheless WriteRecord or WriteDocument made while the same thread already holds that store from user code another cacheless write of the store runs, or from a journal an attach's pull runs (then "The store is attached to a cache, write through the cache.", as after the attach) throws InvalidOperationException; it used to write the file behind the attaching cache and take that cache's registry, so the cache could never flush or pull the store again. A journal that calls its cache's store (Push, Delete, PushAll, CommitBatch, PullAll, ReadStoreSnapshot, JudgeChecks) while that cache's AddBackingStore runs the journal now throws "A journal entered the cache it journals", as it does after the attach; it used to stage or write records the cache never admitted, so the cache and the file disagreed.
• SingleFileBackingStore.ReadStoreSnapshot() reads a store file once, under the store's in-process gate, with the reader a cache's store opens with, and returns the durable snapshot or null when nothing is at the path. SingleFileBackingStore.WriteRecord(record, catalogEntry, holdsIds, registry) writes one record without a cache: under the store's lock every other record and catalog entry is copied as stored, the file is replaced atomically, and the header is decided as a flush decides it. It refuses on a store attached to a cache.
• SingleFileBackingStore.WriteDocument<T>(key, document, storedAt, registry) writes one typed document without a cache, as a cache write does: it plans element ids, encodes the document as T (the type its schema id and ids are taken from, also for a derived instance) and marks the store when it holds an id; a failed write gives the minted ids back. It refuses on a store attached to a cache. The registry of WriteRecord and WriteDocument serves that call only; a store keeps none.
• CultCodec.DecodeDocument<T>(key, payload) decodes a stored payload as a cache load does (CultCacheMessagePack.CreateCodec(registry) makes the codec). It reads no file and holds no state. CultElementIds stays internal.
• CultPersistedStoreSnapshot.FormatV3 names the element-id store header.
• CultDocumentAttribute.CompatibleSchemaIds and CultDocumentDescriptor.CompatibleSchemaIds: the schema ids besides its own a document type claims, so a record stored under one of them loads as that type.
• CultStoredDocument.StoredSchemaId (the schema id the record carries in its store, which may be an older one) and CultStoredDocument.HoldsIds.
• CultCache.MintElementIds() rewrites, once, the records of a store written before element ids whose ids exist only in memory, and returns how many it rewrote.
• CultElementIdAttribute declares an element id (derived from a named member when given), CultForeignRecord is a record a store carries untouched because no registered type reads it, and CultElementIdException, CultSchemaConflictException, CultStoreUnreadableException and CultWriteConflictException are the refusals named above.
• A store written by 1.0.x with a record-reference list in a slot still opens (from 2.0.1).

[2.0.1] - 2026-10-22

Fixed

• A store written by 1.0.x with a list of record references (CultRecordRef<T>[] or any IEnumerable<CultRecordRef<T>> slot) opens again. 2.0.0 classified such a slot as a reference to T, 1.0.x had persisted it as a plain value, and the schema comparison refused the store with "changed reference semantics" and "changed target schema". The payload is the same array of keys, so gaining the reference classification on an otherwise identical slot is now compatible drift (migration warning gained_reference_semantics). A reference that is lost or retargeted, and any change of type or cardinality, still refuses.

[2.0.0] - 2026-10-22

Breaking

• CultMathJson writes CultPhasor as {"cosine":..,"sine":..} and still reads the old cos/sin keys. A reader from before this change does not know the new keys: with default options it skips them and decodes zeros, and with UnmappedMemberHandling.Disallow it throws. Upgrade readers before writers. MessagePack bytes are unchanged.
• CultCache refuses an unknown union arm on read and an unnamed union subtype on write. A payload whose arm key the union does not declare used to decode to null (and the next save wrote the loss back); a value whose type the union does not name used to be written as nil. Both now throw, naming the union and the key or type, and a store pull names the record key and schema id. Known arms encode to the same bytes as before.
• A payload that fails to decode during a store pull (single-file or directory) now throws InvalidDataException naming the record key and schema id, with the original exception (for example MessagePackSerializationException) as its InnerException. Callers that caught the codec's exception type around a store open or pull must catch InvalidDataException. An arm key outside Int32 or not an integer is refused with the same union-naming refusal, and a variant override holding an unknown arm names the schema id.
• Removed or retyped public API, each with its replacement (measured against 1.0.61):
  • GameCult.Caching: the CultCache(CultDocumentRegistry?) constructor is now CultCache(CultDocumentRegistry? registry = null, CultCodec? codec = null); code that bound the old signature by reflection or a method group must rebind. CacheBackingStore.ToStoredDocument(CultPersistedRecord, IReadOnlyCollection<..>, ..) gains an out report of the schema drift it shed. The CultInspectorModel(registry, Func serialize, Func deserialize) constructor is now CultInspectorModel(registry, CultCodec codec).
  • GameCult.Mesh: CultMeshPeerSnapshotDocumentOptions.SchemaIds, CultMeshSnapshotRequestOptions.SchemaIds and .RecordKeys are removed; set Selection (a CultNetSelection) instead. CultMeshHotBodySubscription.SchemaIds and .RecordKeys are removed; read Selection.
  • GameCult.Networking: CultNetDatabaseSubscriptionServer no longer takes the projectRecord constructor argument; a subscription is narrowed by its selection and authorizeRecord.
  • InitialSequence is uint? instead of uint on CultMeshRudpSocketOptions, RudpCultNetSchemaServerOptions, CultNetRudpSessionOptions, CultNetRudpSocketTransportOptions and CultNetRudpSocketTransportServerOptions. Unset, a session draws a random initial sequence in [1, 2^31) (the old defaults were 1 and 100); set a value to keep a fixed one.
• A data member aliased the same name as a reference member in one document type (for example a member aliased Owner beside a reference member named Owner) used to register and is now refused at registration, naming the clash.
• A store header other than one this runtime knows, and a record with more slots than its header allows, are refused by name on read instead of being skipped or read as cultcache.store.v1. A reader from before this change silently dropped the extra slot (for example a variant) and the next save wrote the loss back. cultcache.store.v1 and cultcache.store.v2 are the formats this release reads; a store stamped with a newer one is refused, so this release never rewrites it.
• CultCache payload nesting is bounded at 256 on read and on write (it was 500), and a union arm slot [k, nil] is refused. A store holding a record nested 257 to 500 deep, which 1.0.61 read and wrote, no longer opens, and a value nested that deep can no longer be saved; flatten such a record before upgrading.
• RUDP: SendSchema throws the SocketException for a send that can never succeed as built (MessageSize, InvalidArgument, AddressFamilyNotSupported), queues nothing, and a permanent failure after an earlier fragment left ends the session. It used to count every send failure as a lost datagram and return. Inside a poll such a failure ends only that peer's session (PeerDisconnected carries a reason naming the error) and the poll is not failed.
• RUDP sessions end where they used to carry on: a peer whose message cannot be decoded or handled has its session ended with a goodbye, instead of throwing out of PollAvailableAsync/PollOnceAsync; a session that refuses a packet ends; FlushReliable throws for writes an ended session forgot; the listener replaces a peer on a Connect only when its connect payload differs (reporting PeerDisconnected for the old one) where it used to replace it on every Connect; server mode is claimed only by a Connect; an InitialSequence of uint.MaxValue is rejected; malformed, foreign-connection and refused packets are dropped and counted in Stats.PacketsDropped instead of throwing out of TryReceiveOnce.
• CultNetDatabase.PutAsync and DeleteAsync for a schema no shard owns throw CultNetUnownedSchemaException (an InvalidOperationException naming the schema) before the cache is touched. They used to cache the write and never log it. The fallback shard is gone: a database with shards that do not cover a schema serves and writes only what its shards own.
• RUDP: CultMeshRudpSocketOptions.BindHost is nullable and unset by default. A client now binds loopback for a loopback endpoint and the unspecified address of the endpoint's family otherwise (it used to bind 0.0.0.0 for every client, so an IPv6 endpoint could not be reached); a server still binds 0.0.0.0. An explicit BindHost wins for both.
• RUDP wire behaviour changed in step across the C#, Rust, TypeScript and Python runtimes: one received-through watermark per session owns ordered delivery; a Connect repeats only when it carries the sequence that opened the generation, and reliable data before the handshake is neither acknowledged nor delivered; the sender admits a packet only within 1,023 sequences and 4 MiB above the lowest unacknowledged one. A peer on 1.0.x interoperates only for traffic that stays inside those bounds.
• Variants (record-level wire and store format): a store holding at least one variant declares cultcache.store.v2 and its variant records carry a fifth slot. A reader from before this change refuses the store (unknown header) rather than reading it. A store with no variant stays cultcache.store.v1, byte-identical to 1.0.x. CultMesh single-file reads, the directory store and CultNet refuse a variant record by name; only the C# CultCache resolves variants.
• A plain flush (SingleFileBackingStore.PushAll) reads the file under the lock before it rewrites it, by the same rule attach and conditional commit use (the format stamp in the header decides, before the body is parsed), and throws NotSupportedException instead of writing when the store is one this runtime refuses to read: stamped by another process with a newer format, or with a stamp the reader refuses. A read that fails with an I/O or access error also refuses. It used to overwrite the file from this cache's older view. A directory store throws the same exception, from the manifest parse every write already ran, for a manifest stamped cultcache.store.v<N> with N > 4 (it threw InvalidOperationException). A flush rewrites any file whose stamp it can read as v1 or v2, or cannot read at all (empty, truncated, not a snapshot), which includes a v1 file whose body is corrupt or truncated. It refuses any other string stamp, a nil or binary stamp, and an I/O failure on the read. The public DeserializeSnapshot(byte[]) still parses any string stamp, but refuses a nil or binary stamp (1.0.61 read a nil stamp as v1).
• CultMesh.WriteSingleFileDocument and WriteSingleFileDocumentPayload read the file they replace, under the store's <path>.lock, and refuse (without touching it) a file this runtime cannot read, a store stamped with a newer format version, or one holding any record besides the key being written. They used to replace the file whole. Write to a store that holds several records through a CultCache.

Added

• Variants: a record that stores only its difference from a base record, resolved in memory when the cache admits it (cultcache.store.v2; see the persistence-format contract). A plain write at a variant's key is refused, and Flatten replaces a variant with a plain record.
• CultNet selection v1: one CultNetSelection shape and evaluator (schemas, keys, field predicates, cites, cursors) used by CultMesh snapshot requests, the database server and subscriptions, with typed refusals and row identity of (schemaId, recordKey). v0 filters are lowered onto it with their pre-existing answers.
• Record grouping: a document type declares its inspector group, and the inspector model exposes the group tree, create-in-group and reference labels.
• CultMath value types have canonical MessagePack formatters and System.Text.Json converters, including CultPhasor, CultSiteCells, SpanNoise, SpanPath, SpanStage and the ExprGraph expression graph resolver.
• CultNet publishes every committed cache change once, in Sequence order, from the cache journal; CultNetDatabase.Dispose publishes what a writer logged and had not yet published.
• CultCache takes an optional CultCodec, and isolates every observer so a throwing one cannot stop the others.

Changed

• Requires org.gamecult.cultmath exactly 0.5.0.
• After another writer's whole-file flush or unconditional commit rewrites a drifted record under a schema id this cache did not read it under, keeping its storedAt, an Expect captured before fails until this cache re-reads the store (PullAll), as for any other lost race.

Fixed

• The native QUIC plugins' import settings enable Standalone: Win64 and disable the 32-bit target (the 1.0.61 fix, now on main).
• Expect and ExpectUnchanged hold on an unchanged record loaded under compatible schema drift (written under one version of its type, read by a cache that knows another). Before, they always failed: conditional commit compared the record's persisted schema id with the id this cache decodes it as.

[1.0.61] - 2026-10-03

Fixed

• The native QUIC plugins under Runtime/Plugins/x86_64 (gamecult_mesh_quic_native.dll and msquic.dll) are enabled for 64-bit Windows players (Standalone: Win64). Their import settings named only Standalone: Win, the 32-bit target, so a Win64 player build left both DLLs out and the native QUIC bridge was unavailable at runtime. They are now disabled for 32-bit Windows, which they cannot load.

[1.0.60]

Changed

• Native QUIC bridge: Schannel replaced by OpenSSL MsQuic 2.5.9, statically linked, first shipping in this package with this release. msquic.dll grew from 536,928 to 4,181,856 bytes and the bridge from 40,448 to 302,080 bytes as a result of the static CRT and the statically linked OpenSSL build. The bridge keeps its v1 exports on a v2 event-queue runtime. An OpenSSL notice was added under Third Party Notices.

Breaking

• CultInspectorAssetPath is removed. Inspector annotations that stored an asset by path now use CultInspectorAssetGuid, whose value is a CultAssetGuidKey: the bare Addressables GUID for a main asset, or guid[subAssetName] for a picked sub-asset.