api

type ACLAcceptRequest struct {
	RequestRecordId string `json:"requestRecordId"`
	Permission      string `json:"permission"`
}

type ACLAddAccount struct {
	Identity   string          `json:"identity"`
	Permission string          `json:"permission"`
	Metadata   AccountMetadata `json:"metadata,omitempty"`
}

type ACLAddRequest struct {
	Accounts []ACLAddAccount `json:"accounts"`
}

type ACLChangePermissionsRequest struct {
	Changes []ACLPermissionChange `json:"changes"`
}

type ACLDeclineRequest struct {
	Identity string `json:"identity"`
}

type ACLOwnershipRequest struct {
	NewOwner     string `json:"newOwner"`
	OldOwnerPerm string `json:"oldOwnerPerm"`
}

type ACLPermissionChange struct {
	Identity   string `json:"identity"`
	Permission string `json:"permission"`
}

type ACLRemoveRequest struct {
	Identities []string `json:"identities"`
}

type APIError struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

type AccessCodeRequest struct {
	// Code is the invite code as typed; compared upper-cased with
	// whitespace removed.
	Code string `json:"code"`
}

type AccessCodeResponse struct {
	// Status is "accepted" (limits are being granted) or
	// "already_redeemed" (this account redeemed a code before).
	Status       string `json:"status" enums:"accepted,already_redeemed"`
	RedemptionId string `json:"redemptionId,omitempty"`
}

type AccountDiscoveryStatus struct {
	Enabled bool `json:"enabled"`
	// Relays are the configured pkarr relays, as hosts.
	Relays []string `json:"relays"`
	// Devices is how many sibling devices the record names.
	Devices int `json:"devices"`
	// OwnEntry — the record names this device with its current relay.
	OwnEntry      bool       `json:"ownEntry"`
	LastResolved  *time.Time `json:"lastResolved,omitempty"`
	LastPublished *time.Time `json:"lastPublished,omitempty"`
	// LastError is the last failed cycle; empty after a good one.
	LastError string `json:"lastError,omitempty"`
	// ClockAheadMs is how far the relays' record was dated past this
	// device's clock — a sibling whose clock runs ahead. Zero when it
	// was not.
	ClockAheadMs int64 `json:"clockAheadMs,omitempty"`
}

type AccountMetadata struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	IconCID     string `json:"iconCid,omitempty"`
}

type AccountResponse struct {
	Id       string           `json:"id"`
	Metadata *AccountMetadata `json:"metadata,omitempty"`
	// TechSpaceId is the account's tech space — the :spaceId for
	// account-level bundles (see docs/03-api.md § Bundles).
	TechSpaceId string `json:"techSpaceId"`
}

type AddDatasetFieldResponse struct {
	FieldDefId string `json:"fieldDefId"`
}

type AddDatasetResponse struct {
	DatasetDefId string `json:"datasetDefId"`
	// Collection is the computed collection name the new dataset's
	// records live in.
	Collection string `json:"collection"`
}

type AddPartResponse struct {
	PartId string `json:"partId"`
}

type AddPropertyRequest struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	// XKey is the property's handle — an alias, not a storage key
	// (values live under the content-addressed propId). Unique within
	// the type (409 property.xkey_conflict); mutable via PATCH.
	XKey string `json:"xKey,omitempty"`
	Kind string `json:"kind"`
	// Meta holds the consumer flags the server interprets — today only
	// meta["index"] = "<scope>" | "none" for the search indexer
	// (docs/13-index.md). Any other key is rejected; descriptive
	// metadata lives under xFormat.
	Meta map[string]string `json:"meta,omitempty"`
	// XFormat is the property's descriptor: everything descriptive
	// beyond the kind — the semantic slug, icon, ordering key, option
	// set, relation targets, per-format config (docs/27-descriptors.md).
	// An object; the server validates the keys it interprets (type,
	// icon, pos, options, relation, config, links) against the vocabulary and
	// the slug against kind, stores vendor-namespaced keys verbatim,
	// and reserves validate / compute. Every path under it is mutable
	// via PATCH.
	XFormat json.RawMessage `json:"xFormat,omitempty"`
	// Scope is the property's write/sync class: "synced" (default,
	// everyone in the space), "account" (this account's devices only),
	// or "local" (this device only, never synced). "derived" is
	// reserved for built-ins and rejected. Pinned by the first write,
	// like kind — changing a property's scope means defining a new
	// property. Property VALUE writes auto-route by the declared scope
	// (POST /v1/spaces/:spaceId/properties/:objectId/set/:typeId).
	Scope string `json:"scope,omitempty"`
}

type AddPropertyResponse struct {
	PropId string `json:"propId"`
}

type AggregateResponse struct {
	Records []json.RawMessage `json:"records,omitzero"`
	Plan    *string           `json:"plan,omitempty"`
}

type AuthAccount struct {
	// Id is the StrKey account address ("A…"). Empty for a default
	// root wallet whose id can't be derived without a passkey.
	Id string `json:"id,omitempty"`
	// Default marks the legacy flat-layout wallet at the data-dir root.
	Default bool `json:"default,omitempty"`
}

type AuthCapabilities struct {
	// Deauthorize: DELETE /v1/auth tears the account down in place.
	Deauthorize bool `json:"deauthorize"`
	// SwitchAccount: POST /v1/auth with replace:true switches accounts
	// in place.
	SwitchAccount bool `json:"switchAccount"`
	// Shutdown: POST /v1/shutdown stops the server.
	Shutdown bool `json:"shutdown"`
}

type AuthRequest struct {
	// Mnemonic restores (or first-creates) the account derived from
	// this BIP-39 phrase.
	Mnemonic string `json:"mnemonic,omitempty"`
	// AccountId selects an account that already has a local wallet
	// (standalone only).
	AccountId string `json:"accountId,omitempty"`
	// Index is the account derivation index for Mnemonic. Omitted
	// means 1, the `any` default; pass 0 explicitly to restore an
	// anytype-derived (or pre-index-1 any) account.
	Index *uint32 `json:"index,omitempty"`
	// Replace switches a managed server from its current account to
	// the one this request names, tearing the current engine down
	// first. Without it a different account is refused. Never implied.
	Replace bool `json:"replace,omitempty"`
}

type AuthResponse struct {
	AccountId string `json:"accountId"`
	// Created is true when this account had no local state before this
	// call (fresh generation or first restore on this device).
	Created bool `json:"created"`
	// Mnemonic is returned exactly once: when the server generated a
	// fresh account (no mnemonic/accountId in the request). The caller
	// must surface it to the user for backup.
	Mnemonic string `json:"mnemonic,omitempty"`
	// AlreadyAuthorized reports that the request named the account the
	// server already runs: nothing was booted. With a mnemonic this
	// confirms the phrase derives to the running account; with an
	// accountId it confirms only that the id matches.
	AlreadyAuthorized bool `json:"alreadyAuthorized,omitempty"`
}

type AuthStatusResponse struct {
	Authorized bool   `json:"authorized"`
	AccountId  string `json:"accountId,omitempty"`
	// Mode is the server's ownership mode, fixed at launch.
	Mode string `json:"mode" enums:"standalone,managed"`
	// Capabilities lists which lifecycle operations this server
	// accepts; every bit is false on a standalone server.
	Capabilities AuthCapabilities `json:"capabilities"`
	// Accounts are the wallets on disk (standalone only — a managed
	// server holds no keys and reports an empty list; the client owns
	// the account list there).
	Accounts []AuthAccount `json:"accounts"`
}

type BacklinksAllResponse struct {
	Spaces []SpaceBacklinks `json:"spaces"`
}

type BacklinksResponse struct {
	Object []Link `json:"object"`
	Parts  []Link `json:"parts"`
	// Truncated reports that the read hit its cap (`limit`, max 500)
	// before the split into Object / Parts; there is no continuation.
	Truncated bool `json:"truncated,omitempty"`
}

type BlockCreateRequest struct {
	Type  string         `json:"type"`
	Style map[string]any `json:"style,omitempty"`
	Text  string         `json:"text,omitempty"`
	Nav   *BlockNav      `json:"nav,omitempty"`
}

type BlockNav struct {
	ParentId string `json:"parentId"`
	Pos      string `json:"pos"`
}

type BlockPatchRequest struct {
	Set   map[string]json.RawMessage `json:"set,omitempty" swaggertype:"object"`
	Unset []string                   `json:"unset,omitempty"`
}

type Bundle struct {
	// Id is the stable bundle identifier — the record id. Permanent:
	// a successor install takes a new id (record deletes are refused,
	// so a reused id could never be reclaimed).
	Id string `json:"id"`
	// Name is the display name, stamped as `any.name` on the root by
	// whichever device installed it.
	Name string `json:"name,omitempty"`
	// RootId is the winning root object id. Setup objects are derived
	// from it, so this one id names the whole install. Provisional
	// until the space syncs.
	RootId string `json:"rootId"`
	// Roots is every root ever claimed for this bundle — the add-only
	// audit trail. A resolved loser stays listed; its death is
	// recorded by the deletion of its tree.
	Roots []string `json:"roots,omitempty"`
	// Losers is the live conflict set: claimed roots that are neither
	// the winner nor already deleted. Non-empty means two devices
	// installed concurrently — merge what matters out of each, then
	// resolve it.
	Losers []string `json:"losers,omitempty"`
	// Derived reports that the winner is the root derived from the
	// bundle id: the same id on every device, so this install cannot
	// fork — and cannot be uninstalled, a derived object being
	// undeletable. Absent means an ordinary created root.
	Derived bool `json:"derived,omitempty"`
}

type BundleChildRequest struct {
	// Seed derives the child deterministically under the bundle's
	// current winner. Permanent — a successor object takes a new seed.
	Seed string `json:"seed"`
	// Type is the child's one type, set on first materialization —
	// required (400 request.missing_field), `page` for a plain
	// document; Collections the child lacks are added on every call.
	Type        string   `json:"type"`
	Collections []string `json:"collections,omitempty"`
}

type BundleChildResponse struct {
	ObjectId string `json:"objectId"`
}

type BundleEnsureRequest struct {
	// Id is the bundle identifier. Required.
	Id string `json:"id"`
	// Name is the display name, written on install.
	Name string `json:"name,omitempty"`
	// RootType is the type of the root Ensure mints (its one type,
	// `any.type`): required when the body declares nothing (every
	// object has a type; `page` for a plain document), refused next to
	// a declaration — a declaring root carries its marker there.
	// RootCollections are the collections the root is filed under at
	// birth (a `miniapp` root is an app root). Both ride the root's
	// first change.
	RootType        string   `json:"rootType,omitempty"`
	RootCollections []string `json:"rootCollections,omitempty"`
	// RootProperties seeds the root's property values, keyed
	// owner → propId → value (same shape as POST /objects), written
	// with the membership; an owner that is neither rootType nor the
	// root's own declaration is added to rootCollections.
	RootProperties map[string]map[string]any `json:"rootProperties,omitempty"`
	// Derived installs the bundle on the root derived from its id
	// rather than a created one. Every device computes that id
	// offline, so the install never forks and never waits for the
	// registry to converge — which is the only way both sides of a
	// 1-1 (where nobody is the owner) can install while apart.
	//
	// Permanent in both directions: a derived root cannot be deleted,
	// so the bundle can never be uninstalled, and an existing install
	// on a created root is adopted rather than migrated. Ask for it
	// for a space's chat; not for anything a user may remove.
	Derived bool `json:"derived,omitempty"`
	// Parts declares the root's parts with their datasets (same shape
	// as POST …/types/:typeId/parts); the root becomes a type
	// definition, typeId = rootId, and — a definition implements
	// itself — the records are written through POST …/upsert /
	// …/modify on the root (dataset = the computed collection,
	// `<rootId>_<key>` for a namespaced one). Declared once on install;
	// later evolution goes through the …/types/:rootId/parts routes.
	// Parts or properties are required on the tech space. Refused with
	// `collection`.
	Parts []PartDraftRequest `json:"parts,omitempty"`
	// Properties declares property definitions on the root (same shape
	// as POST …/types/:typeId/properties, xKey REQUIRED and unique):
	// the root becomes a type (or, with `collection`, a collection)
	// objects use, and each property's id is derived from (rootId,
	// xKey) so two devices installing while apart mint one column per
	// handle. Resolve xKey → propId through GET …/types/:rootId/
	// properties (or …/collections/:rootId/properties). Declared once
	// on install (an adopt fills in only definitions the root lacks);
	// later evolution goes through the …/properties routes.
	Properties []AddPropertyRequest `json:"properties,omitempty"`
	// XKey is the root definition's handle (same meaning as on POST
	// …/types): what a client resolves it by, and what
	// relation.targetTypes in other declarations name. Unique within
	// the space among listed types and collections (409
	// type.xkey_conflict). An xKey alone declares a MARKER — a type, or
	// with `collection` a collection, with no properties and no parts.
	// Written on install. A writer's adopt fills in a handle the root
	// lacks (an install that predates it); an existing handle is never
	// changed.
	XKey string `json:"xKey,omitempty"`
	// Layout seeds the root type's rendering slice (same shape as POST
	// …/types; refused with `collection`); Hidden keeps the definition
	// out of the default listings. Both are written on install only —
	// an adopt never patches them. Hidden is explicit: a root that only
	// hosts its bundle's records should ask for it (a listed type is
	// one a client may set on other objects, granting them the bundle's
	// collections); a root that is a definition other objects use stays
	// listed.
	Layout json.RawMessage `json:"layout,omitempty"`
	Hidden bool            `json:"hidden,omitempty"`
	// Collection makes the declaration a COLLECTION instead of a type:
	// the root carries `__collection__` in any.type, properties are its
	// columns, and objects are filed under it through any.collections.
	// Parts and layout are refused with it.
	Collection bool `json:"collection,omitempty"`
}

type BundleEnsureResponse struct {
	// Bundle is the converged registry row.
	Bundle Bundle `json:"bundle"`
	// Installed reports whether THIS call registered the install.
	// False means an existing one was adopted — which for a derived
	// bundle may still materialize the root's tree on this device,
	// since that id is one every device can mint.
	//
	// For a derived install it reports what THIS DEVICE did: both
	// sides of a partition can report true for the one root they
	// share.
	Installed bool `json:"installed"`
}

type BundleGetResponse struct {
	Bundle Bundle `json:"bundle"`
	// Synced: see BundleListResponse.Synced.
	Synced bool `json:"synced"`
}

type BundleListResponse struct {
	Bundles []Bundle `json:"bundles"`
	// Synced reports whether the registry converged before this read
	// (the read-side lock): true means an absent bundle is definitively
	// not installed; false (the wait expired — cold offline device)
	// means absence is provisional.
	Synced bool `json:"synced"`
}

type BundleResolveRequest struct {
	// LoserRootId is the losing root to delete, cascading to its
	// derived children. Call it only once whatever mattered has been
	// merged out — the server never merges for you.
	LoserRootId string `json:"loserRootId"`
}

type CRDTVersionState struct {
	Supported int  `json:"supported"`
	Stored    int  `json:"stored"`
	Newer     bool `json:"newer"`
}

type CatalogBundle struct {
	Id          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Derived installs the bundle on the root derived from its id —
	// never forks, never deletable. The general chat only.
	Derived bool `json:"derived,omitempty"`
	// Hidden keeps the root's definition out of pickers; needs `type`,
	// `collection` or `parts`.
	Hidden bool `json:"hidden,omitempty"`
	// RootType is the root's type when the bundle declares nothing (a
	// bare app root): a registered type id, `page` for a plain
	// document. Required then, refused next to a declaration.
	RootType string `json:"rootType,omitempty"`
	// Type declares the type the root defines; Collection the
	// collection. Exclusive. A root hosting its own records (parts)
	// needs no flag: a definition implements itself.
	Type       *CatalogType       `json:"type,omitempty"`
	Collection *CatalogCollection `json:"collection,omitempty"`
	// Miniapp is a value map on the built-in `miniapp` collection the
	// root is filed under: `bundle` is this bundle's id (filled when
	// omitted), any other key must be a property the built-in declares.
	Miniapp map[string]any `json:"miniapp,omitempty"`
	// Parts declare records datasets on the root (the
	// POST …/types/:typeId/parts draft shape).
	Parts []PartDraftRequest `json:"parts,omitempty"`
	// Supersedes names bundles of the same usecase this one stands in
	// for. A space that has any of them installed keeps them and never
	// receives this bundle; every other space receives this bundle and
	// never the ones it names. A superseded bundle may share its xKey
	// with the bundle that supersedes it — the two never meet in a space.
	Supersedes []string `json:"supersedes,omitempty"`
	// Superseded marks a bundle another one of the usecase supersedes:
	// kept where a space already has it, never what a new space
	// receives. Derived from the other bundles' `supersedes` — the
	// listing reports it, a catalog source does not declare it.
	Superseded bool `json:"superseded,omitempty"`
}

type CatalogCollection struct {
	XKey       string               `json:"xKey"`
	Properties []AddPropertyRequest `json:"properties,omitempty"`
	// Meta is the definition's open bag of consumer flags (see
	// CollectionsCreateRequest): one string, bool or number per
	// single-level key, opaque to the server. Setup writes each key the
	// installed definition lacks and never overwrites one it carries.
	Meta map[string]any `json:"meta,omitempty"`
}

type CatalogListResponse struct {
	Usecases []CatalogUsecase `json:"usecases"`
}

type CatalogSetupBundle struct {
	// Usecase is the entry the bundle belongs to (the requested one or
	// a dependency).
	Usecase string `json:"usecase"`
	// Id is the bundle id.
	Id string `json:"id"`
	// Bundle is the converged registry row.
	Bundle Bundle `json:"bundle"`
	// Installed reports whether THIS call registered the root.
	Installed bool `json:"installed"`
	// TypeId is the root's id when the bundle declares a type — the
	// namespace of its property values (`<typeId>.<propId>`).
	TypeId string `json:"typeId,omitempty"`
	// CollectionId is the root's id when the bundle declares a
	// collection.
	CollectionId string `json:"collectionId,omitempty"`
	// Properties maps each declared property's xKey to its id.
	Properties map[string]string `json:"properties,omitempty"`
	// Miniapp is the value map the catalog declares on the built-in
	// `miniapp` collection, `bundle` included — what an install writes and an
	// adopt by a writer fills in where absent. Read the root for what it
	// carries.
	Miniapp map[string]any `json:"miniapp,omitempty"`
}

type CatalogSetupRequest struct {
	SpaceId string `json:"spaceId"`
}

type CatalogSetupResponse struct {
	// Usecase is the id that was asked for.
	Usecase string `json:"usecase"`
	// Bundles are the installs in setup order.
	Bundles []CatalogSetupBundle `json:"bundles"`
}

type CatalogType struct {
	// XKey is the type's handle — what clients resolve it by and what
	// relation.targetTypes name. Unique across the catalog, types and
	// collections together.
	XKey string `json:"xKey"`
	// Layout is the rendering slug, `{type, config?}`.
	Layout json.RawMessage `json:"layout,omitempty"`
	// Properties are the columns (the POST …/types/:typeId/properties
	// draft shape); each carries an xKey, the property id derives from
	// it.
	Properties []AddPropertyRequest `json:"properties,omitempty"`
}

type CatalogUsecase struct {
	// Id is the usecase slug — the `:usecaseId` path segment. Never
	// enters a space.
	Id          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Requires lists the usecases set up before this one, transitively.
	Requires []string `json:"requires,omitempty"`
	// Bundles are the usecase's own installs, in setup order.
	Bundles []CatalogBundle `json:"bundles"`
}

type ChatAgentMeta struct {
	Name      string `json:"name"`
	DebugLink string `json:"debugLink,omitempty"`
	Done      bool   `json:"done"`
	// Outcome says how the run behind a done:true message ended when
	// it did not end normally — `interrupted` (the user stopped it),
	// `error` (it died). Absent on a normal reply. Opaque to the
	// server; clients key their rendering (a stop mark, a warning) on
	// it instead of parsing the text.
	Outcome string `json:"outcome,omitempty"`
}

type ChatAttachment struct {
	Type string `json:"type"`
	Link string `json:"link"`
}

type ChatEditRequest struct {
	Text string `json:"text"`
}

type ChatMessageContext struct {
	SpaceId  string `json:"spaceId"`
	ObjectId string `json:"objectId,omitempty"`
	View     string `json:"view,omitempty"`
}

type ChatMessageControl struct {
	Kind string `json:"kind"`
	Hard bool   `json:"hard,omitempty"`
}

type ChatSendRequest struct {
	Text             string                    `json:"text"`
	ReplyToMessageId string                    `json:"replyToMessageId,omitempty"`
	Agent            *ChatAgentMeta            `json:"agent,omitempty"`
	Attachments      map[string]ChatAttachment `json:"attachments,omitempty"`
	Context          *ChatMessageContext       `json:"context,omitempty"`
	Control          *ChatMessageControl       `json:"control,omitempty"`
}

type CollectionInfo struct {
	Id          string         `json:"id"`
	Name        string         `json:"name,omitempty"`
	Description string         `json:"description,omitempty"`
	IconCID     string         `json:"iconCid,omitempty"`
	XKey        string         `json:"xKey,omitempty"`
	BuiltIn     bool           `json:"builtIn,omitempty"`
	Hidden      bool           `json:"hidden,omitempty"`
	Meta        map[string]any `json:"meta,omitempty"`
}

type CollectionPatchRequest struct {
	Name        *string        `json:"name,omitempty"`
	Description *string        `json:"description,omitempty"`
	IconCID     *string        `json:"iconCid,omitempty"`
	Hidden      *bool          `json:"hidden,omitempty"`
	Meta        map[string]any `json:"meta,omitempty"`
}

type CollectionsCreateRequest struct {
	Name        string         `json:"name,omitempty"`
	Description string         `json:"description,omitempty"`
	IconCID     string         `json:"iconCid,omitempty"`
	XKey        string         `json:"xKey,omitempty"`
	Hidden      bool           `json:"hidden,omitempty"`
	Meta        map[string]any `json:"meta,omitempty"`
}

type CollectionsCreateResponse struct {
	CollectionId string `json:"collectionId"`
}

type CollectionsListResponse struct {
	Collections []CollectionInfo `json:"collections"`
}

type DatasetDefResponse struct {
	Id string `json:"id"`
	// Key is the slug inside the type; collection is the name reads and
	// writes address (`dataset` on /query, /modify, /upsert …) — the
	// module's canonical collection when shared, `<typeId>_<key>`
	// otherwise. Server-computed, never client-set.
	Key        string `json:"key"`
	Collection string `json:"collection"`
	Module     string `json:"module"`
	Shared     bool   `json:"shared,omitempty"`
	// PartId is the owning part's id.
	PartId      string               `json:"partId"`
	DisplayName string               `json:"displayName,omitempty"`
	Description string               `json:"description,omitempty"`
	Dynamic     bool                 `json:"dynamic,omitempty"`
	IdRule      string               `json:"idRule"`
	IdPattern   string               `json:"idPattern,omitempty"`
	IdMaxLen    int                  `json:"idMaxLen,omitempty"`
	DeleteBy    string               `json:"deleteBy"`
	SkipHistory bool                 `json:"skipHistory,omitempty"`
	Search      *DatasetSearchFields `json:"search,omitempty"`
	Fields      []DatasetFieldDef    `json:"fields"`
	// Invalid marks a definition whose folded declaration fails
	// validation (invalidReason says why) — a records fold missing a
	// creator stamp behind an author rule, an unknown module, a shared
	// rule violation. Invalid definitions never register or accept data
	// but stay listed so they can be repaired or removed.
	Invalid       bool   `json:"invalid,omitempty"`
	InvalidReason string `json:"invalidReason,omitempty"`
}

type DatasetDraftRequest struct {
	// Key is the dataset's slug inside its type ([a-z][a-z0-9_]*, ≤ 64)
	// — pinned. A namespaced dataset lives in the collection
	// `<typeId>_<key>`; a shared dataset's key is its module's canonical
	// collection name and may be omitted.
	Key string `json:"key,omitempty"`
	// Module is the serving module: "records" (the default) or
	// "editor". "chat" is reserved to the server (400
	// dataset.module_reserved) — the catalog's general-chat usecase is
	// its one declaration.
	Module string `json:"module,omitempty"`
	// Shared makes the type participate in the module's canonical
	// collection (editor_blocks) instead of a namespaced one, so two
	// types sharing the editor give an object carrying both a single
	// body. Editor: either; records: never.
	Shared      bool   `json:"shared,omitempty"`
	DisplayName string `json:"displayName,omitempty"`
	Description string `json:"description,omitempty"`
	// Dynamic keeps a free-form keyspace next to the declared fields.
	Dynamic bool `json:"dynamic,omitempty"`
	// IdRule: "auto" (default — ids derived from the change) or "user"
	// (caller-supplied ids, constrained by idPattern/idMaxLen; the id
	// doubles as the upsert idempotency key).
	IdRule    string `json:"idRule,omitempty"`
	IdPattern string `json:"idPattern,omitempty"`
	IdMaxLen  int    `json:"idMaxLen,omitempty"`
	// DeleteBy: "anyone" (default) or "author" (requires a
	// stamp:creator field among fields).
	DeleteBy string `json:"deleteBy,omitempty"`
	// SkipHistory keeps the dataset out of the version-history index.
	SkipHistory bool `json:"skipHistory,omitempty"`
	// Search is the optional search-extraction annotation (x-search):
	// which record fields feed the search index's title/text, and
	// optionally which index scope the entries land under.
	Search *DatasetSearchFields `json:"search,omitempty"`
	// Fields are the initial field definitions (records datasets only —
	// a module owns its schema). Declare required fields here — fields
	// added later cannot be required.
	Fields []DatasetFieldDraft `json:"fields,omitempty"`
}

type DatasetFieldDef struct {
	// Id is the field definition record's id — the identity
	// PATCH / DELETE …/fields/:fieldId target.
	Id          string `json:"id"`
	Key         string `json:"key"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Kind        string `json:"kind"`
	// Shape is the full declared value shape (kind plus items /
	// properties) when one was declared beyond the bare kind.
	Shape     *DatasetFieldShape `json:"shape,omitempty"`
	Scope     string             `json:"scope"`
	Required  bool               `json:"required,omitempty"`
	MutableBy string             `json:"mutableBy"`
	Stamp     string             `json:"stamp,omitempty"`
	// XFormat is the field's descriptor as stored; absent when none was
	// declared.
	XFormat json.RawMessage `json:"xFormat,omitempty"`
}

type DatasetFieldDraft struct {
	// Key is the on-record field name — pinned.
	Key         string `json:"key"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	// Kind is a PropertyKind* wire string. Required unless stamp
	// implies one (creator ⇒ string, createTime/modifyTime ⇒ datetime).
	Kind string `json:"kind,omitempty"`
	// Shape optionally refines array/object values.
	Shape *DatasetFieldShape `json:"shape,omitempty"`
	// Scope: "synced" (default) or "local"; "derived" is implied by
	// stamp and rejected otherwise.
	Scope string `json:"scope,omitempty"`
	// Required: field must be present on create. Incompatible with stamp.
	Required bool `json:"required,omitempty"`
	// MutableBy: "never" (default — write-once), "author", "any".
	// "author" requires a stamp:creator field in the dataset.
	MutableBy string `json:"mutableBy,omitempty"`
	// Stamp: "creator" | "createTime" | "modifyTime" — value derived at
	// apply time, client writes rejected.
	Stamp string `json:"stamp,omitempty"`
	// XFormat is the field's descriptor — the same object a property
	// definition carries (AddPropertyRequest.XFormat), validated the
	// same way against the field's kind. Mutable via
	// PATCH …/fields/:fieldId.
	XFormat json.RawMessage `json:"xFormat,omitempty"`
}

type DatasetFieldPatchRequest struct {
	Set   map[string]json.RawMessage `json:"set,omitempty" swaggertype:"object"`
	Unset []string                   `json:"unset,omitempty"`
}

type DatasetFieldShape struct {
	Kind       string                        `json:"kind"`
	Items      *DatasetFieldShape            `json:"items,omitempty"`
	Properties map[string]*DatasetFieldShape `json:"properties,omitempty"`
}

type DatasetPatchRequest struct {
	Set   map[string]json.RawMessage `json:"set,omitempty" swaggertype:"object"`
	Unset []string                   `json:"unset,omitempty"`
}

type DatasetSchema struct {
	Name   string          `json:"name"`
	Schema json.RawMessage `json:"schema"`
	// Owners are the types that declare the dataset: one for a
	// registered-type or namespaced dataset, every type sharing the
	// module for a canonical collection (empty while nothing declares
	// it), none for space-level built-ins. Records exist only on objects
	// carrying one of them; consumers gate indexing/eviction on it.
	Owners []string `json:"owners,omitempty"`
	// Module is the serving module ("records", "editor", "chat"; empty
	// for built-ins and registered-type datasets); Shared marks a
	// module's canonical collection.
	Module string `json:"module,omitempty"`
	Shared bool   `json:"shared,omitempty"`
}

type DatasetSearchFields struct {
	Title string `json:"title,omitempty"`
	// Text accepts a bare field-key string OR a non-empty array of
	// unique field keys; a single key always reads back as the bare
	// string. The generated schema can only show the array form — the
	// string form is equally valid on the wire.
	Text  SearchText `json:"text,omitempty"`
	Scope string     `json:"scope,omitempty"`
}

type DatasetsResponse struct {
	Datasets []DatasetSchema `json:"datasets"`
}

type DeleteRecordsRequest struct {
	ObjectId  string   `json:"objectId"`
	Dataset   string   `json:"dataset,omitempty"`
	RecordIds []string `json:"recordIds"`
	TraceIds  []string `json:"traceIds,omitempty"`
}

type DerivedSpaceInfo struct {
	Name    string `json:"name"`
	SpaceId string `json:"spaceId"`
	Created bool   `json:"created"`
	Status  string `json:"status,omitempty"`
}

type DerivedSpaceListResponse struct {
	Spaces []DerivedSpaceInfo `json:"spaces"`
}

type DeviceActivateRequest struct {
	App string `json:"app"`
}

type DeviceActiveClaim struct {
	Seq int64 `json:"seq"`
	At  int64 `json:"at"`
}

type DeviceInfo struct {
	PeerId  string `json:"peerId"`
	Name    string `json:"name,omitempty"`
	OS      string `json:"os,omitempty"`
	Version string `json:"version,omitempty"`

	Apps         map[string]map[string]any    `json:"apps,omitempty"`
	ActiveClaims map[string]DeviceActiveClaim `json:"activeClaims,omitempty"`
}

type DeviceUpdateRequest struct {
	Name string                    `json:"name,omitempty"`
	Apps map[string]map[string]any `json:"apps,omitempty"`
}

type DevicesListResponse struct {
	Devices []DeviceInfo      `json:"devices"`
	Active  map[string]string `json:"active,omitempty"`
	Self    string            `json:"self"`
}

type ErrorEnvelope struct {
	Error APIError `json:"error"`
}

type Event struct {
	Type    string          `json:"type"`
	Scope   string          `json:"scope"`
	SpaceId string          `json:"spaceId,omitempty"`
	Target  string          `json:"target,omitempty"`
	Data    json.RawMessage `json:"data,omitempty"`
	Sender  *EventSender    `json:"sender,omitempty"`
}

type EventLinksUpdatedData struct {
	SpaceId   string   `json:"spaceId"`
	Targets   []string `json:"targets"`
	Truncated bool     `json:"truncated,omitempty"`
}

type EventPublishRequest struct {
	Type    string `json:"type"`
	Scope   string `json:"scope"`
	SpaceId string `json:"spaceId,omitempty"`
	Target  string `json:"target,omitempty"`
	// Data is free-form: any JSON value, capped at 64 KiB marshaled.
	// The generated schema can only show the object form — a scalar or
	// an array is equally valid on the wire.
	Data json.RawMessage `json:"data,omitempty"`
}

type EventPublishResponse struct {
	Subscribers int `json:"subscribers"`
}

type EventSender struct {
	Identity string `json:"identity"`
	Self     bool   `json:"self"`
}

type FileCacheFreeRequest struct {
	Bytes int64 `json:"bytes"`
}

type FileCacheFreeResult struct {
	Freed int64 `json:"freed"`
}

type FileCacheInfo struct {
	Size int64 `json:"size"`
}

type FileInfo struct {
	FileId   string `json:"fileId"`
	ObjectId string `json:"objectId"`
	// RootCid is the content address of the encrypted file. Empty for
	// inline-tier files (bytes ride the CRDT row itself).
	RootCid string `json:"rootCid,omitempty"`
	// Size is the plaintext byte size.
	Size int64 `json:"size"`
	// Inline reports the inline tier (no rootCid, no backup needed).
	Inline bool `json:"inline"`
	// Durable reports a verified network-custody receipt (inline files
	// are durable by construction). False right after attach is normal:
	// backup runs in the background — watch /files/subscribe or re-GET.
	Durable bool `json:"durable"`
	// Cached reports a complete local copy (always true for inline).
	Cached    bool   `json:"cached"`
	Name      string `json:"name,omitempty"`
	Mime      string `json:"mime,omitempty"`
	Variant   string `json:"variant,omitempty"`
	VariantOf string `json:"variantOf,omitempty"`
}

type FileListResponse struct {
	Files []FileInfo `json:"files"`
}

type FileStats struct {
	Total    int `json:"total"`
	Durable  int `json:"durable"`
	InFlight int `json:"inflight"`
	Limited  int `json:"limited"`
}

type FileStatus struct {
	FileId   string `json:"fileId"`
	ObjectId string `json:"objectId"`
	State    string `json:"state"`
	Cached   bool   `json:"cached"`
	// Attempts counts failed background attempts since the last
	// success/enqueue; 0 when no work is pending.
	Attempts int    `json:"attempts,omitempty"`
	LastErr  string `json:"lastErr,omitempty"`
}

type GlobalP2PStatus struct {
	Enabled bool `json:"enabled"`
	// EndpointId is this device's iroh endpoint id (its device key).
	EndpointId string `json:"endpointId"`
	// Ticket is what this device publishes for others to dial; empty
	// until the relay session is up. Relay-only by construction — it
	// never carries this device's IP addresses.
	Ticket string `json:"ticket,omitempty"`
	// HomeRelay is the relay URL inside Ticket.
	HomeRelay string `json:"homeRelay,omitempty"`
	// RelayConnected — the session to the home relay is up. Until it
	// is, this device can dial out but cannot be reached.
	RelayConnected bool `json:"relayConnected"`
	// Peers are the peers known through records, connected or not —
	// except any in the disabled tier, which the SDK drops from this
	// list. A device silent for 30 days is therefore absent here, not
	// listed as disabled.
	Peers []P2PPeerStatus `json:"peers"`
	// Account is the account-level discovery record (pkarr).
	Account AccountDiscoveryStatus `json:"account"`
}

type HealthResponse struct {
	Status    string    `json:"status"`
	Version   string    `json:"version"`
	StartedAt time.Time `json:"startedAt"`
	// NetworkId is the any-sync network this server joins: the networkId
	// of the nodeconf it started with. Set whether or not an account is
	// authorized. The server names no networks; clients map well-known
	// ids to names themselves.
	NetworkId string `json:"networkId"`
	Account   string `json:"account"`
	// Bootstrapping is true while the booted SDK's background boot pass
	// (eager space loading + offline catch-up) is still running. The
	// server serves throughout; per-space convergence is /sync-status.
	// False when unauthorized and after the pass completes.
	Bootstrapping bool `json:"bootstrapping"`
	// CRDTVersion is the account's CRDT data-model version state
	// (absent when unauthorized): the version this server's SDK
	// supports, the one recorded on the account's tech space, and
	// `newer` — true when the recorded one is above the supported one,
	// which makes the account read-only until the server is upgraded
	// (every synced write answers 409 sdk.crdt_version_newer).
	CRDTVersion *CRDTVersionState `json:"crdtVersion,omitempty"`
}

type HistoryChange struct {
	Version   string                 `json:"version"`
	Author    string                 `json:"author"`
	Timestamp int64                  `json:"timestamp"` // author clock, Unix seconds — display-only
	Dataset   string                 `json:"dataset"`
	TraceIds  []string               `json:"traceIds,omitempty"`
	Touched   []HistoryTouchedRecord `json:"touched,omitempty"`
	// Truncated is RESERVED (always false today): the SDK keeps full
	// history locally. It becomes meaningful with the future
	// snapshot-horizon contract.
	Truncated bool `json:"truncated,omitempty"`
	GroupSize int  `json:"groupSize"`
}

type HistoryDatasetDiff struct {
	Dataset string              `json:"dataset"`
	Records []HistoryRecordDiff `json:"records"`
}

type HistoryDiffResponse struct {
	Base     string               `json:"base,omitempty"`
	Version  string               `json:"version"`
	Datasets []HistoryDatasetDiff `json:"datasets"`
}

type HistoryFieldDiff struct {
	Path []string `json:"path"`
	// Before / After are leaf values — usually a string, number or
	// boolean. The generated schema can only show the object form.
	Before json.RawMessage `json:"before,omitempty"`
	After  json.RawMessage `json:"after,omitempty"`
}

type HistoryListResponse struct {
	Changes []HistoryChange `json:"changes"`
	// Cursor resumes the next page; empty = history exhausted.
	Cursor string `json:"cursor,omitempty"`
}

type HistoryRecordDiff struct {
	Id     string             `json:"id"`
	Kind   string             `json:"kind"`
	Fields []HistoryFieldDiff `json:"fields,omitempty"`
}

type HistoryRecordResponse struct {
	Version  string          `json:"version"`
	Dataset  string          `json:"dataset"`
	RecordId string          `json:"recordId"`
	Exists   bool            `json:"exists"`
	Deleted  bool            `json:"deleted,omitempty"`
	Record   json.RawMessage `json:"record,omitempty"`
}

type HistoryTouchedRecord struct {
	Dataset  string   `json:"dataset"`
	RecordId string   `json:"recordId"`
	Ops      []string `json:"ops,omitempty"`
}

type HistoryViewDataset struct {
	Dataset string            `json:"dataset"`
	Records []json.RawMessage `json:"records"`
}

type HistoryViewResponse struct {
	Version  string               `json:"version"`
	Datasets []HistoryViewDataset `json:"datasets"`
}

type IdentitiesListResponse struct {
	Identities []IdentityInfo `json:"identities"`
}

type IdentityEventPayload struct {
	Added   []IdentityInfo `json:"added,omitempty"`
	Updated []IdentityInfo `json:"updated,omitempty"`
	Removed []string       `json:"removed,omitempty"`
}

type IdentityInfo struct {
	Identity    string   `json:"identity"`
	Name        string   `json:"name,omitempty"`
	Description string   `json:"description,omitempty"`
	IconCID     string   `json:"iconCid,omitempty"`
	SpaceIds    []string `json:"spaceIds"`
}

type InviteCreateResponse struct {
	SpaceId     string `json:"spaceId"`
	InviteToken string `json:"inviteToken"`
}

type InviteInfo struct {
	RecordId string `json:"recordId"`
	// Permission is "none" for the request-to-join invites v1 mints —
	// the role is chosen at accept time, not carried by the invite.
	Permission string `json:"permission"`
	// InviteToken is the same share token POST /invites returned at
	// mint time, recovered from the minting account's synced custody.
	// Present only on that account's devices — other members (any
	// role) never held the private key and get no token. Also omitted
	// for invites minted before custody shipped (regenerate once to
	// make the token durable) and for custody gone stale (invite
	// replaced or revoked on another device).
	InviteToken string `json:"inviteToken,omitempty"`
}

type InvitesListResponse struct {
	Invites []InviteInfo `json:"invites"`
}

type JoinRequest struct {
	RecordId    string `json:"recordId"`
	Identity    string `json:"identity"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	IconCID     string `json:"iconCid,omitempty"`
}

type JoinRequestsResponse struct {
	Requests []JoinRequest `json:"requests"`
}

type Link struct {
	Source LinkSource `json:"source"`
	Kind   string     `json:"kind"`
	Target LinkTarget `json:"target"`
}

type LinkSource struct {
	SpaceId  string `json:"spaceId"`
	ObjectId string `json:"objectId"`
	Dataset  string `json:"dataset"`
	RecordId string `json:"recordId"`
	// TypeId is the type declaring a property value's source (`prop`
	// edges only): the value lives at record[typeId][recordId].
	TypeId string `json:"typeId,omitempty"`
	// Field is the record field the reference was read from, for a
	// runtime record with link-bearing fields; absent for a block or
	// message text and for a property value.
	Field string `json:"field,omitempty"`
}

type LinkTarget struct {
	Uri      string `json:"uri"`
	Kind     string `json:"kind"`
	SpaceId  string `json:"spaceId"`
	ObjectId string `json:"objectId,omitempty"`
	Dataset  string `json:"dataset,omitempty"`
	RecordId string `json:"recordId,omitempty"`
	PropId   string `json:"propId,omitempty"`
	Identity string `json:"identity,omitempty"`
	FileId   string `json:"fileId,omitempty"`
}

type LinksResponse struct {
	Links []Link `json:"links"`
	// Truncated reports that the read hit its cap.
	Truncated bool `json:"truncated,omitempty"`
}

type LocalAggregateRequest struct {
	Coll             LocalCollection  `json:"coll"`
	Pipeline         []map[string]any `json:"pipeline"`
	GroupLimit       *int             `json:"groupLimit,omitempty"`
	AccumArrayLimit  *int             `json:"accumArrayLimit,omitempty"`
	MemoryLimitBytes *int             `json:"memoryLimitBytes,omitempty"`
	Explain          bool             `json:"explain,omitempty"`
}

type LocalAggregateResponse struct {
	Records []json.RawMessage `json:"records,omitzero"`
	Plan    *string           `json:"plan,omitempty"`
	Written *int              `json:"written,omitempty"`
}

type LocalCollection struct {
	// Scope is "account" or "space".
	Scope string `json:"scope"`
	// SpaceId binds a space-scoped collection; required iff scope is
	// "space". Nothing drops the collection when the space goes away.
	SpaceId string `json:"spaceId,omitempty"`
	// Name: ^[a-z0-9][a-z0-9_-]{0,63}$.
	Name string `json:"name"`
}

type LocalCollectionInfo struct {
	LocalCollection
	// StorageName is the collection's any-store name (the "l_"-tagged
	// form). It is what a pipeline's $out / $merge `into` / $lookup
	// `from` must name — those stages take raw collection names.
	StorageName string       `json:"storageName"`
	Count       int          `json:"count"`
	Indexes     []LocalIndex `json:"indexes"`
}

type LocalDeleteRequest struct {
	Coll LocalCollection `json:"coll"`
	Ids  []string        `json:"ids,omitempty"`
	// Filter is omitzero, not omitempty: `{}` (delete everything) must
	// survive marshalling; only a nil map is absent.
	Filter map[string]any `json:"filter,omitzero"`
}

type LocalDeleteResponse struct {
	// Deleted counts documents actually removed (an id that was already
	// gone is not counted, not an error).
	Deleted int `json:"deleted"`
}

type LocalDiscoveryRequest struct {
	// Enabled false stops announce and browse within seconds and keeps
	// them stopped; true starts them at once. Required: an absent value
	// is 400 request.missing_field rather than a silent off. Held for
	// the process lifetime, across logout and account switches; a host
	// restates it after a restart, and may state it before the first
	// POST /v1/auth.
	Enabled *bool `json:"enabled"`
}

type LocalDiscoveryResponse struct {
	Enabled bool `json:"enabled"`
}

type LocalDocsRequest struct {
	Coll LocalCollection `json:"coll"`
	// Docs are JSON objects. A missing `id` is minted server-side
	// (insert and upsert alike); it must be a string when present.
	Docs []map[string]any `json:"docs"`
}

type LocalEnsureRequest struct {
	LocalCollection
	// Indexes to ensure on the collection (idempotent).
	Indexes []LocalIndex `json:"indexes,omitempty"`
}

type LocalEnsureResponse struct {
	Collection LocalCollectionInfo `json:"collection"`
	Created    bool                `json:"created"`
}

type LocalGetRequest struct {
	Coll LocalCollection `json:"coll"`
	Id   string          `json:"id"`
}

type LocalIdsResponse struct {
	Ids []string `json:"ids"`
}

type LocalImportResponse struct {
	Collections []LocalCollectionInfo `json:"collections"`
}

type LocalIndex struct {
	// Name is derived from Fields when empty (e.g. "kind,-at").
	Name string `json:"name,omitempty"`
	// Fields are field paths, "-" prefix for descending.
	Fields []string `json:"fields"`
	Unique bool     `json:"unique,omitempty"`
	Sparse bool     `json:"sparse,omitempty"`
}

type LocalIndexesRequest struct {
	Coll   LocalCollection `json:"coll"`
	Ensure []LocalIndex    `json:"ensure,omitempty"`
	// Drop names indexes to remove (a missing name is not an error).
	Drop []string `json:"drop,omitempty"`
}

type LocalIndexesResponse struct {
	Indexes []LocalIndex `json:"indexes"`
}

type LocalListResponse struct {
	Collections []LocalCollectionInfo `json:"collections"`
}

type LocalMetaResponse struct {
	Stages       []string `json:"stages"`
	Accumulators []string `json:"accumulators"`
}

type LocalQueryRequest struct {
	Coll   LocalCollection `json:"coll"`
	Filter map[string]any  `json:"filter,omitempty"`
	Sort   []string        `json:"sort,omitempty"`
	// Limit defaults to 100, capped at 1000.
	Limit        int  `json:"limit,omitempty"`
	Offset       int  `json:"offset,omitempty"`
	IncludeTotal bool `json:"includeTotal,omitempty"`
	// Projection shapes the records that come back — the same
	// mongo-style grammar the dataset query endpoints take (docs/09-
	// query.md § Projection): field paths to 1 (include) or -1
	// (exclude), `id` always present. A local record carries no `_ver`
	// and no delivery counters, so the protocol-field rules there are
	// simply inert here. `$project` inside /v1/local/aggregate is the
	// equivalent for a pipeline.
	Projection map[string]int `json:"projection,omitempty"`
}

type LocalRecordResponse struct {
	Record json.RawMessage `json:"record"`
}

type LocalUpdateRequest struct {
	Coll LocalCollection `json:"coll"`
	Id   string          `json:"id"`
	// Modifier is a mongo-style modifier ($set / $unset / $inc / …).
	Modifier map[string]any `json:"modifier"`
	// Upsert creates the document from the modifier when the id is
	// absent instead of answering 404 local.doc_not_found.
	Upsert bool `json:"upsert,omitempty"`
}

type LocalUpdateResponse struct {
	// Modified reports whether the modifier changed the document.
	Modified bool `json:"modified"`
	// Record is the document after the update.
	Record json.RawMessage `json:"record"`
}

type MarkdownContent struct {
	Content string `json:"content"`
}

type MarkdownEdit struct {
	OldText    string `json:"oldText"`
	NewText    string `json:"newText"`
	ReplaceAll bool   `json:"replaceAll,omitempty"`
}

type MarkdownEditRequest struct {
	Edits []MarkdownEdit `json:"edits"`
}

type MarkdownSetResponse struct {
	Inserted  []string `json:"inserted"`
	Updated   []string `json:"updated"`
	Deleted   []string `json:"deleted"`
	Unchanged int      `json:"unchanged"`
}

type Member struct {
	Identity        string `json:"identity"`
	Permission      string `json:"permission"`
	Status          string `json:"status"`
	Name            string `json:"name,omitempty"`
	Description     string `json:"description,omitempty"`
	IconCID         string `json:"iconCid,omitempty"`
	RequestRecordId string `json:"requestRecordId,omitempty"`
}

type MemberEventPayload struct {
	Kind     string  `json:"kind"`
	Member   Member  `json:"member"`
	Previous *Member `json:"previous"`
}

type MembersListResponse struct {
	Members []Member `json:"members"`
}

type ModifyResult struct {
	VersionId  string        `json:"versionId"`
	ChangeId   string        `json:"changeId"`
	RecordIds  []string      `json:"recordIds"`
	Rejections []OpRejection `json:"rejections,omitempty"`
}

type ObjectCreateRequest struct {
	// Type is the object's one type — what it IS: its parts, its layout
	// and one column group. Required (400 request.missing_field);
	// `page` is the plain document. Nothing is stamped server-side.
	Type string `json:"type"`
	// Collections lists the collections the object is filed under at
	// create — column groups without parts (docs/28-well-known-bundles.md:
	// an object is in a space's wiki tree only when it is in the wiki
	// collection).
	Collections []string `json:"collections,omitempty"`
	// InitialProperties carries the object's starting property values,
	// keyed by owner (the type or a collection) then property id — the
	// ONLY home for them: {"initialProperties": {"any": {"name":
	// "Dune"}}}. A top-level name/description/group key is rejected.
	InitialProperties map[string]map[string]any `json:"initialProperties,omitempty"`
}

type ObjectDebugResponse struct {
	ObjectId string `json:"objectId"`

	// SyncState is one of: unknown, offline, syncing, synced, error.
	// Pending is the set of heads the per-space syncstatus tracker is
	// waiting for a responsible-node HeadsApply on; empty means
	// converged with the last sender we trust.
	SyncState  string    `json:"syncState"`
	Pending    []string  `json:"pending"`
	LastSyncAt time.Time `json:"lastSyncAt"`

	// Heads / HeadsCount: current tree heads. HeadsCount > 1 means the
	// object is diverged across concurrent writers right now.
	// BranchCount counts every DAG branch that ever existed —
	// merged-in lineages (one per extra parent on a merge) plus
	// still-open ones (HeadsCount - 1). TreeLen is total change count.
	// Snapshots is the number of changes carrying IsSnapshot; costs a
	// full IterateRoot walk.
	Heads       []string `json:"heads"`
	HeadsCount  int      `json:"headsCount"`
	BranchCount int      `json:"branchCount"`
	TreeLen     int      `json:"treeLen"`
	Snapshots   int      `json:"snapshots"`

	// LatestVersionId is the lexid-max OrderId across Heads. Empty
	// when the tree has no heads (root-only / transient cold-restore).
	// Local to this peer — VersionIds don't match across peers.
	LatestVersionId string `json:"latestVersionId"`

	// MaxAddSeq is the controller's delivery-order watermark — the
	// highest AddSeq the apply path has seen. Exposed here as a
	// sanity check that the controller is keeping up with the tree;
	// not a cross-peer primitive.
	MaxAddSeq uint64 `json:"maxAddSeq"`
}

type ObjectGetResponse struct {
	ObjectId string          `json:"objectId"`
	Record   json.RawMessage `json:"record"`
}

type ObjectSyncStatusResponse struct {
	ObjectId   string    `json:"objectId"`
	State      string    `json:"state"`
	LastSyncAt time.Time `json:"lastSyncAt"`
}

type ObjectsCreateResponse struct {
	ObjectId string `json:"objectId"`
}

type Op struct {
	Type  string `json:"type" enums:"$set,$unset,$inc,$addToSet,$pull"`
	Path  string `json:"path,omitempty"`
	Value any    `json:"value,omitempty"`
}

type OpRejection struct {
	RecordIndex int    `json:"recordIndex"`
	RecordId    string `json:"recordId,omitempty"`
	OpIndex     int    `json:"opIndex"`
	Reason      string `json:"reason"`
}

type P2PPeerStatus struct {
	PeerId    string   `json:"peerId"`
	SpaceIds  []string `json:"spaceIds"`
	Connected bool     `json:"connected"`
	// Sources that know the peer: "lan", "global" (a space's records),
	// "account" (this account's own device record), in any
	// combination. A peer in the top-level list always carries at
	// least "lan", and one in global.peers may also carry it — a
	// device on the same LAN that a space's records also name appears
	// in both lists, so presence under global is not proof that
	// traffic is relayed.
	Sources []string `json:"sources,omitempty"`
	// LastSeen is the newest liveness evidence — a record heartbeat or
	// a local connection. Zero for LAN-only peers.
	LastSeen *time.Time `json:"lastSeen,omitempty"`
	// Tier derived from LastSeen: active, stale, dormant, disabled. It
	// sets how often the peer is dialed. Empty for LAN-only peers.
	Tier string `json:"tier,omitempty"`
	// Failures counts consecutive failed global dials.
	Failures int `json:"failures,omitempty"`
}

type P2PStatusResponse struct {
	// PeerId is THIS device's peer id. Devices of one account must
	// each have a distinct peerId — devices sharing one cannot pair.
	PeerId          string          `json:"peerId"`
	Enabled         bool            `json:"enabled"`
	ListenerStarted bool            `json:"listenerStarted"`
	Port            int             `json:"port"`
	Possibility     string          `json:"possibility"`
	State           string          `json:"state"`
	Peers           []P2PPeerStatus `json:"peers"`
	// LocalDiscovery is the mDNS switch (PUT /v1/local-discovery): false
	// means announce and browse are off and Possibility reads `disabled`.
	// Distinct from Enabled, the p2p.enabled config opt-out fixed at
	// boot, which also takes the QUIC listener down.
	LocalDiscovery bool `json:"localDiscovery"`
	// Global is the internet-wide layer (iroh over the relays).
	Global GlobalP2PStatus `json:"global"`
}

type PartDefResponse struct {
	Id       string               `json:"id"`
	Key      string               `json:"key"`
	Name     string               `json:"name,omitempty"`
	Icon     string               `json:"icon,omitempty"`
	Pos      string               `json:"pos,omitempty"`
	Hidden   bool                 `json:"hidden,omitempty"`
	UI       json.RawMessage      `json:"ui,omitempty"`
	Uses     []string             `json:"uses,omitempty"`
	Datasets []DatasetDefResponse `json:"datasets"`
}

type PartDraftRequest struct {
	// Key is the part's slug ([a-z][a-z0-9_]*, ≤ 64), unique within the
	// type — pinned.
	Key string `json:"key"`
	// Name / Icon / Pos are the display slice; clients sort parts by
	// pos. Hidden parts are not shown by default but stay revealable.
	Name   string `json:"name,omitempty"`
	Icon   string `json:"icon,omitempty"`
	Pos    string `json:"pos,omitempty"`
	Hidden bool   `json:"hidden,omitempty"`
	// UI is the widget descriptor — {type, config} in the xFormat shape
	// (v1 slugs: document, chat, table, list, board, gallery, chart,
	// properties; open set, an unknown slug renders the module default).
	// Written whole.
	UI json.RawMessage `json:"ui,omitempty"`
	// Uses names other datasets OF THIS TYPE the part renders without
	// owning them (dataset keys).
	Uses []string `json:"uses,omitempty"`
	// Datasets are the part's initial dataset declarations.
	Datasets []DatasetDraftRequest `json:"datasets,omitempty"`
}

type PartPatchRequest struct {
	Set   map[string]json.RawMessage `json:"set,omitempty" swaggertype:"object"`
	Unset []string                   `json:"unset,omitempty"`
}

type PeerSyncStats struct {
	PeerId     string    `json:"peerId"`
	LastSyncAt time.Time `json:"lastSyncAt"`
	New        int       `json:"new"`
	Changed    int       `json:"changed"`
	LastErr    string    `json:"lastErr,omitempty"`
}

type Process struct {
	Identity  string        `json:"identity"`
	Self      bool          `json:"self"`
	Id        string        `json:"id"`
	Kind      string        `json:"kind"`
	Title     string        `json:"title"`
	Scope     string        `json:"scope"`
	SpaceId   string        `json:"spaceId,omitempty"`
	Target    string        `json:"target,omitempty"`
	State     string        `json:"state"`
	Done      int64         `json:"done"`
	Total     int64         `json:"total,omitempty"`
	Message   string        `json:"message,omitempty"`
	Error     *ProcessError `json:"error,omitempty"`
	StartedAt int64         `json:"startedAt"`
	UpdatedAt int64         `json:"updatedAt"`
}

type ProcessCancelRequest struct {
	Identity string `json:"identity,omitempty"`
}

type ProcessError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message"`
}

type ProcessFinishRequest struct {
	Status string        `json:"status"`
	Error  *ProcessError `json:"error,omitempty"`
}

type ProcessListResponse struct {
	Processes []Process `json:"processes"`
}

type ProcessProgressRequest struct {
	Done    *int64  `json:"done,omitempty"`
	Total   *int64  `json:"total,omitempty"`
	Message *string `json:"message,omitempty"`
}

type ProcessRegisterRequest struct {
	Id      string `json:"id"`
	Kind    string `json:"kind"`
	Title   string `json:"title"`
	Scope   string `json:"scope"`
	SpaceId string `json:"spaceId,omitempty"`
	Target  string `json:"target,omitempty"`
}

type PropertiesGetResponse struct {
	Record json.RawMessage `json:"record"`
}

type PropertiesListResponse struct {
	Properties []PropertyDef `json:"properties"`
}

type PropertiesSetRequest struct {
	Patch map[string]any `json:"patch"`
}

type PropertyDef struct {
	Id          string `json:"id"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	XKey        string `json:"xKey,omitempty"`
	Kind        string `json:"kind"`
	// Meta is the consumer flag map (meta["index"] for the search
	// indexer).
	Meta map[string]string `json:"meta,omitempty"`
	// Scope is the property's write/sync class (synced / derived /
	// account / local). Definitions written before scopes existed
	// read back as "synced".
	Scope      string        `json:"scope,omitempty"`
	Items      *PropertyDef  `json:"items,omitempty"`
	Properties []PropertyDef `json:"properties,omitempty"`
	Required   []string      `json:"required,omitempty"`
	// XFormat is the descriptor as stored — absent for a property that
	// never declared one, which renders structurally from Kind.
	XFormat json.RawMessage `json:"xFormat,omitempty"`
}

type PropertyPatchRequest struct {
	Set   map[string]json.RawMessage `json:"set,omitempty" swaggertype:"object"`
	Unset []string                   `json:"unset,omitempty"`
}

type PushSubscription struct {
	SpaceKey string `json:"spaceKey"`
	Topic    string `json:"topic"`
}

type PushSubscriptionsResponse struct {
	Subscriptions []PushSubscription `json:"subscriptions"`
}

type PushTokenSetRequest struct {
	Platform string `json:"platform"`
	Token    string `json:"token"`
}

type PushTokenStatus struct {
	Registered bool   `json:"registered"`
	Platform   string `json:"platform,omitempty"`
}

type QueryBodyParams struct {
	// Filter is a mongo-style condition over record fields; omitted or
	// empty matches every record. Operator grammar: docs/09-query.md
	// (a bad operator answers 400 filter.unknown_operator listing the
	// full set).
	Filter map[string]any `json:"filter,omitempty"`
	// Sort lists field paths, "-" prefix for descending (e.g.
	// "-createdAt"). Required when limit > 0 on subscribe, so the
	// window is well-defined.
	Sort []string `json:"sort,omitempty"`
	// Limit bounds the window; 0 or absent = unbounded.
	Limit int `json:"limit,omitempty"`
	// Offset skips past the first N matches of the sorted result.
	Offset int `json:"offset,omitempty"`
	// IncludeTotal populates `total` (every match, regardless of
	// limit/offset) + `hasNext` in the snapshot reply.
	IncludeTotal bool `json:"includeTotal,omitempty"`
	// MailboxCapacity (subscribe only) sizes the event mailbox before
	// the stream closes with reason "overflow". Default 256, min 16.
	MailboxCapacity int `json:"mailboxCapacity,omitempty"`
	// DriftBudgetPercent (subscribe only) bounds window drift before
	// the stream closes with reason "drifted". Default 30.
	DriftBudgetPercent int `json:"driftBudgetPercent,omitempty"`
	// Projection shapes the records that come back, mongo-style: a flat
	// object of dotted field paths to 1 (include) or -1 (exclude).
	// `{"any":1,"nav":1}` is include mode — nothing but those subtrees;
	// `{"_ver":-1}` is exclude mode — every user field but that one.
	// Omitted, records ship their full form. Three rules worth knowing:
	// `id` always rides along and cannot be excluded, `_ver` is narrowed
	// to the projection automatically (never name a `_ver` path), and
	// `_addSeq`/`_applySeq` drop unless named. Full grammar and the
	// divergences from mongo: docs/09-query.md § Projection.
	Projection map[string]int `json:"projection,omitempty"`
}

type QueryResponse struct {
	Records []json.RawMessage `json:"records"`
	Total   *int              `json:"total,omitempty"`
	HasNext *bool             `json:"hasNext,omitempty"`
}

type QuerySubscribeEvent struct {
	VersionId string                 `json:"versionId"`
	Added     []QuerySubscribeRecord `json:"added,omitempty"`
	Updated   []QuerySubscribeRecord `json:"updated,omitempty"`
	Removed   []RemovedRecord        `json:"removed,omitempty"`
}

type QuerySubscribeRecord struct {
	Id  string             `json:"id"`
	Doc json.RawMessage    `json:"doc"`
	Ops []SubscribeEventOp `json:"ops,omitempty"`
}

type QuerySubscribeSnapshot struct {
	Records []json.RawMessage `json:"records"`
	Total   *int              `json:"total,omitempty"`
	HasNext *bool             `json:"hasNext,omitempty"`
}

type RecordModify struct {
	Id     string `json:"id,omitempty"`
	Upsert bool   `json:"upsert,omitempty"`
	Ops    []Op   `json:"ops"`
}

type RemovedRecord struct {
	Id     string `json:"id"`
	Reason string `json:"reason"`
}

type SearchHit struct {
	Scope    string `json:"scope"`
	ObjectId string `json:"objectId"`
	Dataset  string `json:"dataset"`
	RecordId string `json:"recordId"`
	// Chunk is the 0-based chunk of the record this hit shows: long
	// records are indexed as several docs, and the hit is the record's
	// best-ranked one. One hit per record — no client-side dedupe.
	Chunk int `json:"chunk,omitempty"`
	// Data is the hit's indexed text, windowed to MaxData runes around
	// the first matching term. DataOffset is the window's rune offset
	// into the chunk's full indexed text and DataTotal that text's rune
	// length — Data is the whole text iff DataOffset == 0 and
	// len([]rune(Data)) == DataTotal.
	Data       string  `json:"data"`
	DataOffset int     `json:"dataOffset,omitempty"`
	DataTotal  int     `json:"dataTotal"`
	Score      float64 `json:"score"`
	// Passages are the record's next best matching chunks. Absent when
	// the request did not ask (SearchRequest.Passages) and when the
	// record has no other matching chunk in the search window.
	Passages []SearchPassage `json:"passages,omitempty"`
}

type SearchPassage struct {
	Chunk      int     `json:"chunk,omitempty"`
	Data       string  `json:"data"`
	DataOffset int     `json:"dataOffset,omitempty"`
	DataTotal  int     `json:"dataTotal"`
	Score      float64 `json:"score"`
}

type SearchRequest struct {
	// Query is the search text. Required.
	Query string `json:"query"`
	// Scopes restricts results to the given index scopes (basic, chat,
	// props, …). Empty = all scopes.
	Scopes []string `json:"scopes,omitempty"`
	// Limit caps returned records — every hit is a distinct
	// (objectId, dataset, recordId). Default 10, max 100.
	Limit int `json:"limit,omitempty"`
	// Mode is hybrid (default), fts, or vector. Vector requires an
	// embedder configured on the server.
	Mode string `json:"mode,omitempty"`
	// Require / Exclude are extra must / must-not terms ($require /
	// $exclude) — a hit must contain every Require term and no Exclude
	// term, in every mode: the FTS leg matches on them, and vector hits
	// are post-filtered against the FTS index before fusion. Each term
	// may be a "phrase" or prefix*.
	Require []string `json:"require,omitempty"`
	Exclude []string `json:"exclude,omitempty"`
	// MaxData bounds each hit's Data to a window of at most this many
	// runes around the first query/require term match (the head when
	// nothing matches). 0 = DefaultSearchMaxData; -1 = the whole indexed
	// chunk text. DataOffset / DataTotal on the hit locate the window.
	MaxData int `json:"maxData,omitempty"`
	// Passages asks for up to this many further matching chunks per
	// record, best first, on hit.passages (0 = none, max 10). They are
	// the record's other chunks that ranked within the search window,
	// not every chunk of the record.
	Passages int `json:"passages,omitempty"`
	// Filter keeps only hits whose host object matches this condition,
	// in the /objects/query filter grammar verbatim (any.type,
	// any.collections, <ownerId>.<propId>, modifiedAt, …), in every mode — like Require /
	// Exclude. The object's live row is checked, so a property write is
	// honored at once. Limit still counts matching records. An object
	// with no row never matches.
	Filter json.RawMessage `json:"filter,omitempty"`
}

type SearchResponse struct {
	Hits []SearchHit `json:"hits"`
	Mode string      `json:"mode"`
	// VectorStatus: used | unavailable | disabled | skipped — whether
	// semantic recall participated in this response and, if not, why.
	VectorStatus string `json:"vectorStatus"`
	// Truncated is set when a leg's read budget under Filter ended and
	// the page holds fewer than Limit records: the index may hold
	// matches the reply cannot show. Absent without a filter. A Filter
	// no object satisfies answers empty without running a leg
	// (VectorStatus then reads skipped, or disabled without an embedder).
	Truncated bool `json:"truncated,omitempty"`
}

type SearchText []string

type SpaceAggregateObjectsRequest struct {
	Pipeline         []map[string]any `json:"pipeline"`
	GroupLimit       *int             `json:"groupLimit,omitempty"`
	AccumArrayLimit  *int             `json:"accumArrayLimit,omitempty"`
	MemoryLimitBytes *int             `json:"memoryLimitBytes,omitempty"`
	Explain          bool             `json:"explain,omitempty"`
}

type SpaceAggregateRequest struct {
	ObjectId         string           `json:"objectId"`
	Dataset          string           `json:"dataset"`
	Pipeline         []map[string]any `json:"pipeline"`
	GroupLimit       *int             `json:"groupLimit,omitempty"`
	AccumArrayLimit  *int             `json:"accumArrayLimit,omitempty"`
	MemoryLimitBytes *int             `json:"memoryLimitBytes,omitempty"`
	Explain          bool             `json:"explain,omitempty"`
}

type SpaceBacklinks struct {
	SpaceId   string `json:"spaceId"`
	Object    []Link `json:"object"`
	Parts     []Link `json:"parts"`
	Truncated bool   `json:"truncated,omitempty"`
}

type SpaceCreateRequest struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	IconCID     string `json:"iconCid,omitempty"`
	SpaceType   string `json:"spaceType,omitempty"`
}

type SpaceDebugResponse struct {
	SpaceId string          `json:"spaceId"`
	Peers   []PeerSyncStats `json:"peers"`
}

type SpaceInfo struct {
	Id                 string         `json:"id"`
	Type               string         `json:"type,omitempty"`
	SpaceType          string         `json:"spaceType,omitempty"`
	Author             string         `json:"author,omitempty"`
	Name               string         `json:"name,omitempty"`
	Description        string         `json:"description,omitempty"`
	IconCID            string         `json:"iconCid,omitempty"`
	Status             string         `json:"status"`
	OwnRole            string         `json:"ownRole" enums:"owner,admin,writer,reader,guest,none"`
	CreatedAt          time.Time      `json:"createdAt"`
	Settings           map[string]any `json:"settings,omitempty"`
	SpaceIndexObjectId string         `json:"spaceIndexObjectId,omitempty"`
	Push               *SpacePushKeys `json:"push,omitempty"`
	// Derived marks a space created by the account's own derivation
	// (POST /v1/spaces/derived/:name or another consumer of the SDK's
	// Derive). Derived spaces are permanent — DELETE refuses them with
	// 409 space.derived_undeletable. Absent on created / joined / 1-1
	// spaces.
	Derived bool `json:"derived,omitempty"`
}

type SpaceJoinRequest struct {
	InviteToken string          `json:"inviteToken"`
	Metadata    AccountMetadata `json:"metadata,omitempty"`
}

type SpaceListQueryRequest struct {
	// Dataset defaults to "spaces"; "profile" is the only other
	// reachable value (closed allowlist — identities is deliberately
	// excluded, read it via GET /v1/identities).
	Dataset string `json:"dataset,omitempty" enums:"spaces,profile"`
	QueryBodyParams
}

type SpaceListResponse struct {
	Spaces []SpaceInfo `json:"spaces"`
}

type SpaceModifyRequest struct {
	ObjectId string         `json:"objectId"`
	Dataset  string         `json:"dataset"`
	Records  []RecordModify `json:"records"`
	TraceIds []string       `json:"traceIds,omitempty"`
	// Scope selects the write route: "synced" (default — the object's
	// own DAG change) or "local" (device-only materialization for
	// fields the dataset schema declares local-scope; explicit record
	// ids, no upsert, no traceIds). See docs/03-api.md § Modify records.
	Scope string `json:"scope,omitempty" enums:"synced,local"`
}

type SpaceOneToOneRequest struct {
	OtherIdentity string `json:"otherIdentity"`
}

type SpacePushKeys struct {
	SpaceKey string `json:"spaceKey"`
	EncKey   string `json:"encKey"`
	EncKeyId string `json:"encKeyId"`
}

type SpaceQueryObjectsRequest struct {
	QueryBodyParams
}

type SpaceQueryRequest struct {
	// ObjectId names the object whose dataset is queried. Required.
	ObjectId string `json:"objectId"`
	// Dataset names the per-object dataset (chat_messages,
	// editor_blocks, …). Required.
	Dataset string `json:"dataset"`
	// IncludeDeleted (snapshot only) returns the dataset's record-level
	// tombstones next to the live rows: `{id, _deletedAt, _ver, …}`
	// with the content wiped. Lets a writer of an `id: user` dataset
	// find the highest id ever used — a deleted id is burned, so the
	// live maximum is not the next free one. Refused on `/subscribe`
	// (400 request.invalid_field); the other query surfaces reject it
	// as an unknown field (a deleted OBJECT is purged, not tombstoned).
	IncludeDeleted bool `json:"includeDeleted,omitempty"`
	QueryBodyParams
}

type SpaceRegisterIncomingRequest struct {
	PeerIdentity string          `json:"peerIdentity"`
	DisplayHint  AccountMetadata `json:"displayHint,omitempty"`
}

type SpaceSettingsPatchRequest struct {
	Set   map[string]any `json:"set,omitempty"`
	Unset []string       `json:"unset,omitempty"`
}

type SpaceSyncStatusResponse struct {
	SpaceId      string    `json:"spaceId"`
	State        string    `json:"state"`
	Synced       int       `json:"synced"`
	Total        int       `json:"total"`
	NetworkPeers int       `json:"networkPeers"`
	LocalPeers   int       `json:"localPeers"`
	GlobalPeers  int       `json:"globalPeers"`
	P2P          string    `json:"p2p"`
	LastSyncedAt time.Time `json:"lastSyncedAt"`
}

type SpaceUpdateRequest struct {
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
	IconCID     *string `json:"iconCid,omitempty"`
}

type SubscribeClosed struct {
	Reason string `json:"reason"`
}

type SubscribeEventOp struct {
	Type    string          `json:"type"`
	Path    []string        `json:"path"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

type SubscribeReady struct{}

type SyncStatusLagged struct {
	Total uint64 `json:"total"`
}

type SyncStatusReady struct{}

type TypeDatasetsListResponse struct {
	Datasets []DatasetDefResponse `json:"datasets"`
}

type TypeInfo struct {
	Id          string `json:"id"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	IconCID     string `json:"iconCid,omitempty"`
	// XKey is the stable, caller-side programmatic key. For builtin/registered
	// types it equals Id (a clean literal like "chat"); for user types it's
	// the value set at create (or derived from Name by the client). Clients use
	// it as the stable type handle in dotted property paths.
	XKey    string `json:"xKey,omitempty"`
	BuiltIn bool   `json:"builtIn,omitempty"`
	// Layout — see TypesCreateRequest. Absent on built-ins.
	Layout json.RawMessage `json:"layout,omitempty"`
	// Hidden / Meta — see TypesCreateRequest. GET …/types omits hidden
	// types unless includeHidden=true.
	Hidden bool           `json:"hidden,omitempty"`
	Meta   map[string]any `json:"meta,omitempty"`
}

type TypePartsListResponse struct {
	Parts []PartDefResponse `json:"parts"`
}

type TypePatchRequest struct {
	Name        *string         `json:"name,omitempty"`
	Description *string         `json:"description,omitempty"`
	IconCID     *string         `json:"iconCid,omitempty"`
	Layout      json.RawMessage `json:"layout,omitempty"`
	Hidden      *bool           `json:"hidden,omitempty"`
	Meta        map[string]any  `json:"meta,omitempty"`
}

type TypesCreateRequest struct {
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	IconCID     string `json:"iconCid,omitempty"`
	// XKey is the stable, caller-side programmatic key for the type
	// (e.g. "agent_memory"). REQUIRED on create and unique per space: the
	// server rejects an empty xKey (type.xkey_required) and one that
	// collides with an existing type's xKey or id (type.xkey_conflict).
	// Clients derive it as a slug of Name. It's the only human handle a
	// type resolves by — the display Name is not a resolution key.
	XKey string `json:"xKey,omitempty"`
	// Layout is how the type's header and parts compose — {type,
	// config} in the xFormat shape (v1 slugs: page, tabs, chat, profile;
	// open set, unknown renders as page). Mutable via PATCH
	// …/types/:typeId.
	Layout json.RawMessage `json:"layout,omitempty"`
	// Hidden keeps the type out of GET …/types by default (pass
	// includeHidden=true to list it) and out of a client's pickers;
	// GET …/types/:typeId always resolves it. Meta is the open bag of
	// consumer flags — one string, bool or number per single-level key
	// (no '.', no '$', ≤64 bytes), written per key so concurrent
	// writers merge; opaque to the server. Both mutable via PATCH.
	Hidden bool           `json:"hidden,omitempty"`
	Meta   map[string]any `json:"meta,omitempty"`
}

type TypesCreateResponse struct {
	TypeId string `json:"typeId"`
}

type TypesListResponse struct {
	Types []TypeInfo `json:"types"`
}

type UpsertRecord struct {
	Id     string         `json:"id"`
	Fields map[string]any `json:"fields"`
}

type UpsertRejection struct {
	Index  int    `json:"index"`
	Id     string `json:"id,omitempty"`
	Code   string `json:"code"`
	Reason string `json:"reason"`
}

type UpsertRequest struct {
	ObjectId string         `json:"objectId"`
	Dataset  string         `json:"dataset"`
	Records  []UpsertRecord `json:"records"`
	// PageSize caps records per emitted change. 0 = 500.
	PageSize int      `json:"pageSize,omitempty"`
	TraceIds []string `json:"traceIds,omitempty"`
}

type UpsertResult struct {
	Pages      []ModifyResult    `json:"pages"`
	Created    int               `json:"created"`
	Updated    int               `json:"updated"`
	Skipped    int               `json:"skipped"`
	Rejections []UpsertRejection `json:"rejections,omitempty"`
}