CultLib/packages/cultcache-py/PARITY.md

Python Runtime Parity Map

This file is the current audit map for cultcache-py as a Python runtime for CultCache, CultNet, and CultMesh. It is evidence, not confetti.

Proven Surfaces

• CultCache v1 store parity: packages/cultcache-ts/test/cult-cache.test.ts includes Python in the shared TypeScript/Rust/C#/Python store matrix.
• CultNet schema-v0 live interop: packages/cultnet-ts/test/interop/cultnet-interop.test.ts runs a live TS/Rust/C#/Python peer ring. The Python interop peer filters shard-scoped raw snapshots by its live shard-log membership before stamping shard cursor metadata.
• Python CultNet raw client: Fetches schema catalogs, raw snapshots, shard catalogs, shard logs, and live database subscription changes. Request-response reads and database subscription streams raise typed CultNetPeerError values for cultnet.error.v0 peer responses while preserving the raw error document for callers that need the wire evidence.
• Python CultNet raw snapshot: Provides typed CultNetRawSnapshotResponse and CultNetRawDocumentRecord helpers plus CultNetRawClient.fetch_snapshot_response(...) for inspecting peer snapshots before handing them to the existing replication helpers. apply_raw_document_record(...), apply_raw_snapshot(...), CultMeshDatabase.apply_snapshot_response(...), and sync paths accept typed records/responses while preserving the existing replication owner. CultMeshDatabase.build_snapshot_response(...) projects local envelopes into the same typed response shape; the older create_snapshot_response(...) remains the wire-dict compatibility projection.
• Python CultNet schema catalog: Exposes shared wire-message schema descriptors from the package surface so both the interop peer and CultMesh local server describe the CultNet/CultMesh messages they speak through the same catalog authority. Python callers can also ingest and filter remote schema catalog responses through typed CultNetSchemaCatalog and CultNetSchemaDescriptor helpers, including CultNetRawClient.sync_schema_catalog(...). The catalog includes cultnet.error.v0, and the local server advertises that version in hello responses because oversized snapshots and other peer failures use that contract on the wire. It also advertises the shared cultnet.transport_profile.v0 contract so Python peers can describe their TCP-framed and RUDP transport capabilities honestly.
• Python CultNet security/session primitives: CultNetClientSecurityOptions, CultNetServerSecurityOptions, and CultNetSecret mirror the C#/TS connection-key, server signing-secret, development-default, environment-validation, base64url, and HMAC-SHA256 session-token helper surface. Python creates C#-compatible versioned session tokens with userGuidN|expiresUnix|sessionVersion payloads and still validates legacy two-field tokens with session version 0. AES-GCM string and byte helpers use the same tag-prefix payload shape when the optional cryptography dependency is available; without that dependency they fail explicitly instead of pretending plaintext is secure.
• Python CultNet shard catalog: Provides typed CultNetShardCatalog and CultNetShardDescriptor helpers for ingesting, filtering, and emitting shard topology responses, plus CultNetRawClient.sync_shard_catalog(...) for peer topology discovery over the same framed CultNet pipe.
• Python CultNet shard log: Provides typed CultNetShardLogResponse and CultNetShardLogEntry helpers for inspecting mutation-log entries, resync pressure, and sequence cursors, including typed put-document and delete identity projections on individual entries while cache mutation remains owned by the existing replication helpers. apply_shard_log_response(...), CultMeshDatabase, and CultMeshGameSession can consume typed shard-log responses directly for database sync and prediction reconciliation. CultMeshDatabase.build_shard_log_response(...) creates the typed response from the package-local mutation log and reports resync-required responses for unknown shards or stale epoch cursors; create_shard_log_response(...) remains the raw wire-dict compatibility projection.
• Python CultNet shard replication: Provides schema-v0 shard-log and shard-snapshot fetchers, a schema-v0 write-forwarder for raw put/delete messages, plus a CultNetShardReplicator that tracks replica cursors, applies log responses through the existing database owner, runs explicit background pull loops for non-primary shards with advertised primaries, reports loop errors through a caller-owned callback, and recovers from compacted-history resync pressure by fetching a shard snapshot. Replica cursor storage can be in-memory or restart-safe through a local MessagePack cursor file. The write-forwarder is also exercised against a launched Python daemon endpoint: forwarded raw put/delete messages mutate daemon state and are recorded in the daemon-served shard log.
• Python CultNet database subscription changes: Provides typed CultNetDatabaseChange parsing plus CultNetDatabaseSubscription.read_next_change(...) / iter_changes(...) for live raw database subscriptions. Put/update changes expose their contained raw document as a typed CultNetRawDocumentRecord while preserving the legacy dict-shaped document projection. Initial snapshot frames can be read as typed CultNetRawSnapshotResponse values through read_next_snapshot_response(...) / iter_snapshot_responses(...), while raw message reads remain available for callers that own their own dispatch loop.
• Python CultNet witness artifacts: Provides typed CultNetWitnessArtifactBundle ownership for the C#-compatible 8-slot witness artifact payload while preserving dict helpers for existing wire callers.
• Python CultNet RUDP transport: Provides the shared cultnet.transport.rudp.v0 packet codec, deterministic RUDP session state machine, socket-backed single-peer transport connection, transport profile advertisement, ping/pong, disconnect reason propagation, timeout state, fragmentation/reassembly, reliable ordered schema delivery, unreliable sequenced latest, unreliable unordered realtime, resend pressure, and bounded reliable-send backpressure. The TypeScript interop harness proves bidirectional Python/TypeScript RUDP socket exchange, packet-loss recovery, reordering recovery, fragmentation, ping/pong, and disconnect reason propagation through the shared wire language.
• Python CultMesh discovery client: Fetches Verse catalogs and peer exchange responses from live endpoints over CultNet frames. It can also parse cultnet://host:port endpoints, discover from endpoint lists, de-duplicate discovery targets, fan out one-shot discovery from endpoints already advertised in local Verse and peer catalogs, fan out raw snapshot fetches and simulation observations to peer-card endpoints, apply peer snapshots through a caller-owned database, run lightweight scheduled snapshot and simulation-observation fanout loops, probe peer-card endpoints for hello-level reachability, preserve hello capability metadata on health results including document types, message versions, and mutation contracts, run immediate scheduled health probes on start, and upsert results into local catalogs with the same count-returning ergonomics as the C# discovery clients.
• Python CultMesh facade: Exposes C#-matching client entrypoints for Verse discovery, peer exchange, raw CultNet client construction, local nodes, catalogs, sessions, streams, authority leases, local TCP node serving, simulation fact commits, and the durable shard-log node option that attaches a file-backed authoritative log store beside the cache file by default. The cultmesh-py-daemon / python -m cultmesh_py.daemon entrypoint launches that same local TCP server body and emits a bounded readiness document for process supervisors while the served CultNet endpoint remains the capability owner. Readiness now mirrors the served hello capability metadata, shard ids, and configured snapshot limits so supervisors can inspect startup state without inventing a second protocol truth. Readiness also includes the same Verse descriptors and peer cards served by the live discovery endpoints, keeping operator and agent inspection tied to the catalogs that own mesh identity. The daemon can register and seed the package interop-note document so launched processes advertise a real payload schema and serve both a real snapshot and a real shard-log entry over the same CultNet lane. When launched with a Verse id, it publishes its actual bound endpoint in the Verse and peer catalogs so discovery clients can find the running Python peer without embedding code-owned catalogs. With a cache file and durable shard-log path, a restarted daemon can rehydrate the persisted interop-note snapshot and shard-log entry without reseeding. The launched daemon also accepts raw puts over a live database subscription stream, emits the matching change notification, and records the mutation in the served shard log. If its durable shard log has been compacted, stale shard-log requests return the same explicit compacted_history resync boundary over the daemon wire endpoint instead of silently looking empty. Simulation observation serving is opt-in: the daemon only advertises cultnet.simulation_observation.v0 when an observation hub is attached, and an opt-in launched daemon answers witness observations with schema-v0 consensus candidates. When such a daemon self-advertises into a Verse, its peer card includes the simulation-observer role so discovery clients can find the peer by the capability it actually serves. The daemon CLI snapshot document/byte limits feed the same public server edge; oversized daemon snapshot responses are returned as structured cultnet.error.v0 peer errors rather than partial payloads.
• Python CultMesh authority leases: Lease objects own validity and peer/role/shard coverage checks; the catalog owns sorted listing, lookup, upsert, signature verification policy, and authorization delegation, matching the C# reference authority boundary. Callers can require verified signatures and use the packaged HMAC verifier to issue and verify canonical lease payloads keyed by issuer runtime.
• Python CultMesh local server: Serves a CultMeshNode plus Verse and peer catalogs over the same framed MessagePack request/response lane used by CultNetRawClient and CultMeshDiscoveryClient. It also supports live raw database subscriptions for snapshot, put, and delete notifications on a connected client stream. When given a CultNetSimulationObservationHub, it accepts cultnet.simulation_observation.v0 messages and replies with current cultnet.simulation_consensus_candidate.v0 messages through the same framed lane. Its schema catalog includes both registered document payload schemas and shared wire-message descriptors for the CultNet/CultMesh messages it handles. Hello and payload schema descriptors advertise the raw snapshot, put, delete, and shard-log mutation surfaces the server actually serves. Unsupported request schemas, malformed raw put/delete messages, and snapshot limit violations return structured cultnet.error.v0 documents instead of silent stream stalls. Its shard catalog advertises the database-owned shard ids, schema ids, and latest shard epochs so discovery and shard-log catch-up agree on the same authority. Public mesh edges can set snapshot document and encoded-byte limits; oversized snapshot responses are rejected as cultnet.error.v0 before the payload is sent.
• Python CultMesh reactive catalogs: Verse and peer catalogs expose sorted local views, get(...), response application, and watch(...) callbacks for local discovery updates. Verse descriptors can evaluate transfer compatibility with the same transport/rules shape as the C# reference surface.
• Python CultMesh database facade: node.database owns the local typed document read/write/snapshot/sync surface so Python callers do not need to reach through the node composition wrapper. It includes global document helpers that delegate through the same singleton key invariant as CultCache. It also exposes local watch(...), watch_record(...), watch_global(...), watch_by_name(...), and watch_by_index(...) callbacks for database changes, including authoritative shard-log reconciliation applied through the session facade. Change notifications carry previous values when the database can observe the old record before local or replicated application. It can project local envelopes into schema-v0 raw snapshot responses and apply those responses back through the shared CultNet replication path. Typed builders own the local response shape and raw dict methods serialize that shape for compatibility with older callers and wire handlers. Shard-scoped raw snapshots filter by shard-log membership when the database has an authoritative log for the requested shard. Raw shard-scoped writes append a package-local mutation log that can be projected into schema-v0 shard-log responses for peer catch-up.
• Python CultMesh committed simulation facts: The live interop harness sends Python a simulation observation, receives a consensus candidate, then requests the committed gamecult.mesh.simulation_fact document back over the raw snapshot lane and checks its MessagePack slots. Python exposes typed CultNetSimulationObservation and CultNetSimulationConsensusCandidate objects for local consensus and game-session commit paths while preserving the schema-v0 dict projections used by the wire harness. Scheduled simulation-observation fanout keeps queued observations pending when no peer produces a candidate, even when endpoint failures are reported through a caller-owned error callback.
• Python CultMesh prediction reconciliation: The live interop harness runs a Python CultMesh session client, writes a local prediction, pulls the live Python peer shard log, applies the authoritative entry, and verifies the session reports the record as reconciled. Python sessions also expose pending prediction inspection, resimulation input listing, explicit rollback of one or all pending predictions, and authoritative-delete rollback when a shard log rejects speculative local input.
• Python CultMesh session watches: CultMeshGameSession.watch_candidates(...) and watch_simulation_facts(...) expose the same gameplay-facing observation and committed-fact watch points as the C# session facade. A game session can also serve its own Verse catalog, peer catalog, and simulation observation hub over the local framed CultMesh server so peer-facing session state uses the same wire contracts as lower-level server callers. Session serving options can keep individual discovery, peer exchange, or simulation surfaces unserved without advertising disabled capabilities.
• Python package health: cultcache-py-verify --json checks the public CultCache/CultNet/CultMesh export surface declared by each package __all__, py.typed markers, a live local CultMesh framed-wire smoke over hello/schema/snapshot/shard catalog/shard log, typed peer-error export availability, peer-advertised mutation contracts, payload schema wire contracts, simulation capability truth, and benchmark sanity for Python-owned hot paths.
• Python/C# public cache baseline: cultcache_py.compare_csharp runs Python and C# CultCache upsert/get benchmarks with the same operation names and reports median Python-to-C# ratios from three samples by default. It also emits per-metric threshold checks and an overall parity status so performance claims have an explicit evidence gate. Both benchmark lanes precompute record keys before measuring public cache reads and writes, matching the C# reference benchmark shape instead of charging one runtime for key construction inside the hot path. The Python in-memory record owner is type-partitioned so public get(...) reads avoid per-call composite-key allocation on the hot path.

Local Python Gates

$env:PYTHONPATH="$PWD\packages\cultcache-py\src"
python -m unittest discover -s packages\cultcache-py\tests
python -m cultcache_py.verify --json
python -m cultcache_py.benchmark --records 1000 --json
python -m cultcache_py.compare_csharp --records 1000 --samples 3 --json
python -m pip wheel --no-deps -w $env:TEMP packages\cultcache-py

Cross-Runtime Gate

$env:PYTHON='C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe'
npx tsc -p packages\cultnet-ts\tsconfig.test.json --pretty false
node --test packages\cultnet-ts\dist-test\test\interop\cultnet-interop.test.js

Still Not Claimed

• Python does not claim to match the C# runtime for every raw-throughput workload. It has a measured local baseline plus a shared public CultCache upsert/get comparison harness with threshold status, not a universal performance victory certificate.
• Python does not implement the full LiteNetLib client/server auth flow. It now owns the shared security/session primitives for helper parity, while the live transport harness still speaks the schema-v0 interop lane.
• Python does not make RUDP the only public pipe yet. The local CultMesh server, raw client, and interop peer still use the TCP-framed schema lane for many service and harness flows, while docs/cultnet-transport-parity.md tracks the remaining work to put broader server-side bodies behind the shared transport port instead of cloning LiteNetLib.
• Python does not implement the full C# daemon/server stack. Its current role is package runtime, raw interop peer, launchable local CultMesh endpoint, local CultMesh session facade, and typed state participant.
• Python does not claim the full C# shard mutation-log service surface. It can create/apply raw snapshots, create/apply package-local raw shard-log responses, consume remote shard-log responses, and run pull-once replica catch-up with snapshot recovery, a file-backed replica cursor store, and schema-v0 write forwarding. It also has an explicit package-level background pull loop for caller-provided shard descriptors. Its authoritative shard-log store is file-backed, supports compaction watermarks, and can be attached by CultMeshNodeOptions(enable_durable_shard_logs=True), but it is still package-local rather than the full C# daemon/server stack.