VerseVDI-Protocol/AGENTS.md

VerseVDI Protocol repository guidance

This repository is the sole source of the VerseVDI Phase 3 wire contract. It contains OpenAPI, JSON Schema, Protobuf, registries, fixtures, and generated language bindings. It contains no Connection Server business policy, database/auth implementation, provider credentials, or media implementation.

Source and generation rules

• Edit schemas/, openapi/, proto/, registries/, and fixtures/ only as protocol sources. Never hand-edit gen/; run python3 tools/generate.py.
• VERSION and compatibility.json are the version authority. Current, N-1, and N-2 fixtures must remain executable.
• make verify runs schema/fixture checks, Protobuf lint/descriptor checks, the historical-descriptor breaking check, deterministic generation, Go tests, and native conformance runners.
• Generated output must be byte-for-byte clean after a second generation.
• gen/protobuf/phase3a-baseline.binpb is a generated historical descriptor used only by Buf breaking checks; regenerate it from an approved baseline tag, never by hand.
• The Connection Server consumes generated Go types through adapters; it does not own a competing wire schema.

Scope boundaries

Phase 3A covers control, authorization, resources, broker session actions, gateway-only grants/manifests, resumable control events, registered control datagrams, and bounded text clipboard. It does not implement a gateway, provider transport, video/audio forwarding, file transfer, or a second auth or datastore path.

Git and release safety

Keep private Gitea work and public-source boundaries explicit. Preserve dirty work from other owners. Do not push, merge, publish, or change release credentials unless the task separately authorizes it. A local immutable candidate tag is allowed only after matching Go/Rust/Swift fixture hashes and clean-checkout evidence; it is not a publication.

Private Go module identity

• The canonical module path is git.sechmachine.io.vn/sechmachine/VerseVDI-Protocol.
• Generated Protobuf go_package options and Go consumers must use that path; do not restore a GitHub import path or add a filesystem replace in a consumer checkout.
• Consumers pin an exact immutable Protocol tag. The Protocol Gitea workflow includes a Linux module job that verifies the module identity and builds all Go packages; the macOS job remains the full Rust/Swift/conformance gate.