# dolt.sr.ht — the read schema.
#
# There are no mutations here, and the reason is the same one spec.sr.ht gives:
# a type federated into api.sr.ht is a consumed contract, expensive to churn, so
# only what has settled is published. Creating, renaming and deleting a database
# each move a metadata row and an on-disk store together, and that pairing is
# young; it stays behind the web UI until it is not.
#
# Rows and diffs are absent for a different reason. They exist on /mcp, where a
# read that had to be clipped says so in its own answer — a shape this schema
# would have to reproduce field by field to stay honest. Until it does, a client
# that wants table contents should ask /mcp, and this schema stops at the
# structure: what databases exist, what branches and commits they carry, and
# what tables live at a ref.
#
# Everything below is read through the same db/ store and browse/ session the
# web pages and the MCP tools use, so the three surfaces cannot disagree about
# what a database is.

"""
An RFC-3339 timestamp.
"""
scalar Time

"""
An opaque pagination cursor. Pass it back into the same field to fetch the next
page; it is null when there are no further results.
"""
scalar Cursor

"""
Who may see a database, and how it is listed.

PUBLIC is listed to everyone including anonymous callers. UNLISTED is reachable
by direct address but never appears in a listing to a stranger. PRIVATE is
neither: to a caller who may not see it, it does not exist — this schema answers
null rather than an authorization error, exactly as the web UI answers "no such
database" rather than "forbidden".
"""
enum Visibility {
  PUBLIC
  UNLISTED
  PRIVATE
}

"""
An ACL grant: read-only (browse and clone) or read-write (and push).
"""
enum AccessMode {
  RO
  RW
}

"""
A SourceHut account, mirrored from meta.sr.ht.
"""
type User {
  """
  The username with no leading "~". This is the name that addresses the account
  in `database(owner:)` and in a clone URL's path.
  """
  username: String!

  """
  The username with its leading "~", as SourceHut writes it in prose and in the
  web UI.
  """
  canonicalName: String!
}

"""
A hosted Dolt database: one metadata row and one bare chunk store.
"""
type Database {
  id: Int!
  name: String!
  owner: User!

  """
  The description shown in listings. Empty rather than null when unset: a
  companion of a git repository mirrors that repository's description, and "no
  description" and "the empty description" are the same state here.
  """
  description: String!
  visibility: Visibility!
  created: Time!
  updated: Time!

  """
  The branch a reader lands on: "main" when it exists, else the first branch by
  name. Null for a database nothing has been pushed to yet — a store with no
  commits has no branches, which is a state and not a failure.
  """
  defaultBranch: String

  """
  Every branch, the default one first and the rest by name. Empty for a database
  nothing has been pushed to.
  """
  branches: [Branch!]!

  """
  The commit log of `ref`, newest first. `ref` is a branch name or a commit
  hash, defaulting to `defaultBranch`; `from` continues a previous page from the
  hash it returned as `cursor`.
  """
  log(ref: String, from: Cursor, limit: Int): CommitCursor!

  """
  The tables of the committed root at `ref` (a branch name or a commit hash,
  defaulting to `defaultBranch`), each with its columns and row count.
  """
  tables(ref: String): [Table!]!

  """
  Who else may read or write this database. Owner-only: to anybody else it is
  the empty list, because the collaborator list of a database you do not own is
  not yours to enumerate.
  """
  acl: [ACLEntry!]!
}

"""
A branch and the commit it points at.
"""
type Branch {
  name: String!
  head: String!
}

"""
One commit of a database's history.
"""
type Commit {
  hash: String!
  author: String!
  email: String!
  date: Time!
  message: String!
  parents: [String!]!
}

"""
A column of a table, as the stored schema declares it.
"""
type Column {
  name: String!
  type: String!
  primaryKey: Boolean!
  nullable: Boolean!
}

"""
A table at a ref: its schema and how many rows it holds there.
"""
type Table {
  name: String!
  columns: [Column!]!
  rowCount: Int!
}

"""
An access grant on a database.
"""
type ACLEntry {
  user: User!
  mode: AccessMode!
}

"""
How a listing is paged. It is git.sr.ht's `Filter` minus `search`: nothing here
searches yet, and declaring a field this schema would ignore is a worse answer
than not declaring it.
"""
input Filter {
  """
  How many results one page holds, capped at 100. It travels in the cursor the
  page returns, so it is given once and kept for the rest of the walk.
  """
  count: Int = 25
}

type DatabaseCursor {
  results: [Database!]!
  cursor: Cursor
}

type CommitCursor {
  results: [Commit!]!
  cursor: Cursor
}

type Query {
  """
  The caller, or null for an anonymous one. Anonymous is a normal caller on this
  schema — it reads what an anonymous visitor reads — so a null here is an
  answer and not an error.
  """
  me: User

  """
  Every database the caller may be shown, newest first, across all owners.

  This is the listing rule and not the read rule: PUBLIC to everyone, plus
  whatever the caller owns or holds an ACL entry on. An UNLISTED database of
  somebody else is absent here and still readable through `database`.
  """
  databases(cursor: Cursor, filter: Filter): DatabaseCursor!

  """
  One owner's databases, under the same listing rule as `databases`. `owner`
  carries no leading "~".
  """
  databasesByOwner(owner: String!, cursor: Cursor, filter: Filter): DatabaseCursor!

  """
  One database by owner and name, neither carrying a leading "~". Null when
  there is no such database *or* when the caller may not see it — the two are
  deliberately one answer, so that a PRIVATE database cannot be discovered by
  the shape of the refusal.
  """
  database(owner: String!, name: String!): Database
}