Define transactional ordered scene snapshots and revisioned deltas

[zoeyrose]

Important

This issue now defines Game Protocol 1 in the fresh MIT Protobuf repository. The ordered-scene product contract and safety bounds remain authoritative; MAP2, classic command IDs, SOCKET_VERSION, 49-slot migration, C/Python generation, and classic consumer details below are historical evidence only.

Replacement outcome

Define transactional, revisioned, bounded tile/scene snapshots and deltas that let the Go server publish authorized ordered scene records and the Rust client consume them atomically through a renderer-neutral session adapter.

Schema and state-machine scope

• Stable map-instance, tile, scene-record/entity, resource, surface, role, physical-level, generation, revision, and transaction identities using common protocol types.
• Complete tile/scene snapshot begin/chunk/commit (or one bounded atomic message where limits permit) with explicit expected counts/bytes/digest.
• Revisioned deltas for add/update/remove/tombstone/reorder, visibility reset, map/instance transition, and generation replacement.
• Named render/semantic roles and structural placement; never positional display slots.
• Exact record/tile/transaction/string/collection/coordinate limits plus unknown/duplicate/stale/missing behavior.
• Atomic temporary validation: no partial mutation of live client session state before the complete transaction validates.
• Authorization/disclosure is server-owned; protocol transports only the viewer-specific scene.
• Reconnect/resync rules and explicit full-snapshot request/rejection behavior.

Cross-language conformance

• Go producer and Rust consumer golden fixtures for empty, single tile, dense overlap, tall/multipart, cross-depth, structural surfaces, removals/reorder, transition, and reconnect.
• Negative fixtures for truncation, oversize, duplicate IDs, missing commit/records, invalid surfaces/roles/resources, stale/future revision, digest/count mismatch, and unknown required feature.
• Fuzz framing plus semantic validation and prove failures leave the prior scene generation intact.
• Separate complete source-neutral scene bundles used by offscreen rendering from connection delta bookkeeping, while sharing logical records.

Acceptance criteria

• The fresh server/client interoperate without any classic packet/slot compatibility layer.
• Renderer receives only validated bounded logical scene snapshots, not generated Protobuf types.
• A rejected transaction cannot leak partial visibility, delete valid state, or retain unauthorized records.
• Schema breaking checks and Game Protocol 1 compatibility policy cover every released field/value.
• Root ordered-scene epic and server/renderer/content issues all point to this one wire contract.

Preserved design specification and historical implementation notes

Parent and roadmap

• Parent tracker: Ordered world model: compile, simulate, stream, render, and edit stable scene records atrinik#156
• Roadmap: Roadmap: replace classic Atrinik with a fresh MIT Go and Rust stack atrinik#168
• Roadmap milestone: M2
• Prerequisites: Define stable ordered scene records, render roles, and tile admission server#19, Modernization: adopt bounded packet cursors, protocol definitions, and fuzzing atrinik#190

Outcome

Replace flattened-slot MAP2 deltas with bounded, ordered, revisioned tile snapshots and a server delta cache keyed by stable record identity.

Scope

• Define length-delimited scene records and tile snapshots with map generation, tile revision, support/light metadata, bounded counts, and bounded encoded bytes.
• Split commands only at tile boundaries, prioritize dirty work within per-tick budgets, and commit server delta state only after successful enqueue.
• Implement bounded transactional parsing into temporary storage with complete validation before mutation.
• Update socket version, command definitions, server sender/cache, client parser contract, bots, fixtures, and ADS documentation together.

Superseded path / cleanup target

Delete the flattened slot update identity and obsolete MAP2 sender/cache path once all current endpoints consume snapshots. Do not maintain both protocols.

Acceptance criteria

• Round trips cover empty, sparse, dense, maximum-count/byte, multi-depth, and split updates.
• Stale generations/revisions, duplicates, truncation, invalid IDs, trailing data, and oversize records cannot partially mutate client state.
• Queue pressure cannot mark an unsent revision as delivered.
• All in-repository consumers and protocol documents use the ordered snapshot contract.

Validation baseline

Before: slot number is both display position and delta identity, and malformed updates can only be bounded by outer packet limits.

After: atomic bounded tile revisions carry ordered records with stable identities and explicit generations.

Run truncation-at-every-field and round-trip suites, queue-pressure tests, bot/client/server interoperability, fuzz smoke tests, and native builds.

This issue is a bounded child of atrinik/atrinik#156. The parent remains open until every sibling child is complete.