Skip to content

docs: add AI-agent-readable schemaVersion 3/4 specification - #1

Draft
webwarrior06 wants to merge 1 commit into
mainfrom
cursor/schema-version-spec-b724
Draft

docs: add AI-agent-readable schemaVersion 3/4 specification#1
webwarrior06 wants to merge 1 commit into
mainfrom
cursor/schema-version-spec-b724

Conversation

@webwarrior06

Copy link
Copy Markdown
Owner

Adds SCHEMA_VERSION_SPEC.md — a structured specification document written for AI coding agents.

What this covers

  • Glossary distinguishing schemaVersion, the entry-list version header, and formatVersion
  • Full data model for RootHash, UpdatedRootHash, and the entry-list text format
  • Table of every HTTP endpoint and whether it reads/sends schemaVersion
  • Step-by-step runtime branching logic for getRootHash() and getEntries()
  • Collection hash algorithm (distinct from file-content SHA-256)
  • Explicit table of which high-level methods are safe under schemaVersion 4
  • Statement that no migration logic exists
  • Test coverage gaps (schemaVersion 4 error paths not tested)
  • Actionable rules for agents making future changes (choke points, what must change together, what is safe to call independently)
Open in Web Open in Cursor 

Co-authored-by: Taha Yasin Kucuk <webwarrior06@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants