space

type ACL interface {
	// CreateInvite mints a new RequestToJoin invite, revoking any
	// prior invite on this space (mirrors AclSpaceClient.ReplaceInvite
	// semantics — only one active invite at a time). The returned
	// Invite is share-friendly (base58-encoded via Invite.Encode()
	// equivalents on space.EncodeInvite).
	CreateInvite(ctx context.Context) (Invite, error)

	// RevokeInvite revokes a single invite by record id. The record id
	// is what AclState lists in InviteIds.
	RevokeInvite(ctx context.Context, inviteRecordId string) error

	// RevokeAllInvites tears down every active invite in one batch.
	RevokeAllInvites(ctx context.Context) error

	// AcceptRequest approves a pending join request and grants the
	// joiner the given permission. requestRecordId is the id from
	// MembersAPI.JoinRequests. Owner / admin only.
	AcceptRequest(ctx context.Context, requestRecordId string, perm Permission) error

	// DeclineRequest rejects a pending join request from identity.
	// Owner / admin only.
	DeclineRequest(ctx context.Context, identity string) error

	// ChangePermissions updates the permissions of one or more existing
	// members in a single batch. Owner / admin only; cannot demote the
	// owner.
	ChangePermissions(ctx context.Context, changes []PermissionChange) error

	// RemoveAccounts kicks one or more members out, rotating the read
	// key so removed members can no longer decrypt new content. Owner
	// / admin only.
	RemoveAccounts(ctx context.Context, identities []string) error

	// AddAccounts adds members directly without an invite/request
	// round-trip — the whole batch lands in ONE ACL record. Useful
	// wherever the caller already holds the joiners' identities.
	//
	// When the coordinator inbox transport is available, each added
	// account is also notified durably (queued + retried across
	// restarts): the space surfaces on their devices as
	// StatusInvitePending for them to AcceptInvite / DeclineInvite.
	// Without the transport (headless deployments) the ACL write still
	// happens but no notification is sent.
	AddAccounts(ctx context.Context, accounts []MemberAdd) error

	// OwnershipChange transfers ownership to newOwner; the old owner's
	// permission becomes oldOwnerPerm (typically PermissionAdmin).
	OwnershipChange(ctx context.Context, newOwner string, oldOwnerPerm Permission) error

	// RequestSelfRemove asks to be removed from this space. Self-service
	// — works for any non-owner, non-guest member.
	RequestSelfRemove(ctx context.Context) error

	// CancelJoinRequest withdraws the caller's pending request on a
	// LOADED space. A pending join is never loaded (Service.Get refuses
	// it), so withdrawing a join request goes through the account-level
	// Service.CancelJoin; this handle only reaches a request the loaded
	// space can hold, i.e. a pending self-remove.
	CancelJoinRequest(ctx context.Context) error

	// StopSharing drops every non-owner member, revokes every invite,
	// and rotates the read key in one batch. Owner only.
	StopSharing(ctx context.Context) error

	// CreateGuestKey enables public read-only access: it mints a shared
	// guest identity, adds it to the ACL with PermissionGuest, and
	// returns it as an InviteKindGuest invite for Service.JoinGuest.
	// One active guest key per space; the private key is persisted on
	// the owner's tech-space row, so repeated calls return the same
	// invite while the guest identity is still active in the ACL
	// (idempotent — the key is not recoverable from the ACL itself).
	// Owner only: custody lives in the owner's tech space, so admins
	// can neither fetch nor reissue it.
	CreateGuestKey(ctx context.Context) (Invite, error)

	// RevokeGuestKey removes the guest identity from the ACL and
	// rotates the read key, cutting every guest off from new content
	// (already-synced local copies stay readable on their devices).
	// Clears the stored key; a later CreateGuestKey mints a fresh
	// identity, so old invites die permanently. No-op error when no
	// guest key is active.
	RevokeGuestKey(ctx context.Context) error
}

type AccountMetadata struct {
	Name        string
	Description string
	IconCID     string
}

type Agg interface {
	// GroupLimit overrides the maximum number of unique $group keys
	// (any-store default 50 000; negative = unlimited).
	GroupLimit(n int) Agg

	// AccumArrayLimit overrides the maximum $push / $addToSet array
	// length (any-store default 10 000; negative = unlimited).
	AccumArrayLimit(n int) Agg

	// MemoryLimit overrides the retained-bytes budget shared by the
	// pipeline's blocking stages (any-store default 256 MiB; negative =
	// unlimited).
	MemoryLimit(bytes int) Agg

	// Iter executes the pipeline and streams result documents. Results
	// are pipeline output, not dataset rows — a $group doc carries the
	// group key as `id`, a $count doc is `{<name>: N}` with no id at
	// all. Each value is valid only until the next Next() call.
	Iter(ctx context.Context) (Iterator, error)

	// All materializes every result into a slice, cloned off the
	// iterator's reused buffers so caller-held pointers stay valid.
	All(ctx context.Context) ([]*anyenc.Value, error)

	// Count executes the pipeline and returns the number of result
	// documents. (A terminal $count stage instead emits the count as a
	// document.)
	Count(ctx context.Context) (int, error)

	// Explain returns the access plan of the pushed prefix plus the
	// in-pipeline stage list. Diagnostic only, NOT a stable format —
	// don't parse it.
	Explain(ctx context.Context) (string, error)
}

type AttachOpts struct {
	// Name is the user-facing file name.
	Name string
	// Mime is the content-type hint.
	Mime string
	// Variant + VariantOf attach this content as an alternate
	// representation of an existing file on the SAME object (the
	// embedder produces the bytes — e.g. a thumbnail it rendered).
	// The variant is an ordinary sibling file with its own tier,
	// durability and lifecycle; Open(originalId, variant) resolves it.
	// Both must be set together; VariantOf must reference a file bound
	// to the same objectId.
	Variant   Variant
	VariantOf string
}

type Bundle struct {
	// Id is the stable bundle identifier (marketplace id or a
	// hardcoded slug like "bao/v1") — the record id.
	Id string
	// Name is the bundle's display name.
	Name string
	// RootId is the winning root object id — the converged LWW value.
	// Children of the setup are derived from it (DeriveObjectOpts.
	// ParentId), so this one id transitively names the whole install.
	RootId string
	// Roots is every root object id ever claimed for this bundle, in
	// arrival order. Add-only audit trail — entries are never removed;
	// a resolved loser's death is recorded by its tree deletion.
	Roots []string
	// Losers is the live conflict set: Roots minus the winner minus
	// roots whose trees are already deleted. Non-empty means a
	// concurrent-install conflict awaits resolution — merge what
	// matters out of each loser, then ResolveLoser it.
	Losers []string
	// Derived reports that the winner is the bundle's canonical
	// derived root (EnsureBundleRequest.DerivedRoot). Such an install
	// cannot fork and cannot be uninstalled: the root id is a pure
	// function of (space, bundle id), and derived trees are not
	// deletable. Computed on read, not stored.
	Derived bool
}

type BundlesAPI interface {
	// Ensure installs the bundle or adopts the existing install:
	// when a live record with a winner exists, it is returned as-is
	// (no root is created); otherwise the root is minted — NewRoot for
	// a created root, the canonical derivation for DerivedRoot — and
	// one change registers it ($set rootId + $addToSet roots). Fully
	// local — no network wait; two devices ensuring concurrently each
	// register their root and the CRDT converges on one deterministic
	// winner after sync, the other surfacing in Losers. Callers must
	// therefore treat the returned RootId as provisional until the
	// space has synced, and re-read after.
	//
	// Adoption wins over derivation: a bundle already installed on a
	// created root stays on it, even when this call asks for
	// DerivedRoot. Nothing migrates behind the caller's back — check
	// Bundle.Derived to see what the install actually is.
	//
	// A CLAIMED CANONICAL DERIVED ROOT ALWAYS WINS the registry, on
	// every replica, whatever the rootId register says. The claim set
	// is add-only, so the verdict itself is order-independent: every
	// replica reads the same winner from any prefix containing the
	// claim, which is what keeps a derived root (undeletable, and
	// therefore unresolvable as a loser) from ever becoming one.
	//
	// The verdict is not a race, but the CLAIM can be: a device that
	// installs a derived root without a converged registry demotes an
	// existing created install to a loser, irreversibly, on every
	// replica. Converge before installing derived into a space that
	// may already carry a created install of the same id — see
	// docs/bundles.md § Derived roots.
	//
	// A declaring root (Parts, Properties or XKey; Collection for a
	// collection) is stamped as a definition: the root's first change
	// carries its membership (the marker in `any.type`, or RootType;
	// RootCollections), `any.name`, the definition metadata (`xkey` /
	// `layout` / `hidden` under `type` or `collection`) and the
	// RootProperties values together — one `objects` change — then the
	// registry row, then the declarations (one `properties` change,
	// one `datasets` change for a type): root + up to 3 changes. A
	// crash mid-install leaves a registered row the retry heals
	// idempotently. Two devices declaring the same name concurrently
	// converge on one definition after sync; a DefId read before
	// convergence may change — look definitions up by name when
	// evolving them.
	//
	// On the tech space (Service.Get(SDK.TechSpaceId())) roots are
	// minted by Ensure only — NewRoot is refused — and a declaration
	// (Parts, Properties or XKey) is required; both root strategies
	// are available.
	//
	// The bool reports whether THIS call registered the install.
	// False means an existing one was adopted — which for a derived
	// root may still materialize its tree locally.
	//
	// Options carry what a request body must never say: SystemInstall
	// admits a reserved module (handler.Module.Reserved) for the
	// consumer's own install.
	Ensure(ctx context.Context, req EnsureBundleRequest, opts ...EnsureOption) (Bundle, bool, error)

	// Get returns the bundle row. ErrBundleUnknown when no live record
	// exists OR the winning root's tree is deleted — a dead winner
	// reads as uninstalled everywhere (Get, List, Ensure's adopt gate),
	// and the next Ensure reinstalls with a fresh root. As of local
	// state — sync first for a network answer.
	Get(ctx context.Context, bundleId string) (Bundle, error)

	// List returns every live bundle row.
	List(ctx context.Context) ([]Bundle, error)

	// DerivedRootId is the id the bundle's derived root has in this
	// space — a pure function of (space, bundle id), computed without
	// reading the registry, materializing anything, or touching the
	// network. Every device and every member gets the same answer,
	// offline, which is what makes DerivedRoot installs fork-proof.
	//
	// It answers "where would this bundle live", not "is it
	// installed": a bundle installed on a created root lives
	// elsewhere, and an uninstalled one lives nowhere yet.
	DerivedRootId(ctx context.Context, bundleId string) (string, error)

	// ResolveLoser deletes a losing root object (cascade-deleting its
	// derived children) after the caller has merged whatever content
	// mattered out of it. The target must be a claimed root and must
	// not be the current winner (ErrBundleNotLoser). Idempotent: a
	// root already deleted returns nil. Deletion needs the loser's
	// tree synced to this device — until then the call fails with
	// ErrLoserNotSynced (retry after sync, or run from the device that
	// created the loser). Never auto-invoked — loser cleanup is always
	// an explicit caller decision.
	ResolveLoser(ctx context.Context, bundleId, loserRootId string) error
}

type CRDTVersionNewerError struct {
	Stored    int
	Supported int
}

type CRDTVersionState struct {
	Supported int
	Stored    int
	Newer     bool
}

type ChangeIndexAPI interface {
	// MaxApplySeq returns the current upper bound of the cursor — the
	// highest per-object applySeq persisted in this space. 0 when
	// nothing has applied yet.
	MaxApplySeq(ctx context.Context) (uint64, error)

	// ChangedSince returns objects whose applySeq exceeds `since`,
	// ordered ascending, capped at limit (0 = no cap). Page by passing
	// the last returned ApplySeq as the next `since`.
	//
	// Objects already on disk before this SDK version started stamping
	// space scope appear only after their next change ("index from now
	// on" for pre-existing data).
	ChangedSince(ctx context.Context, since uint64, limit int) ([]ObjectChange, error)

	// Subscribe registers cb to fire once per applied change in this
	// space. cb runs synchronously on the apply path — keep it small or
	// hand work off to your own goroutine. The returned cancel is
	// idempotent.
	//
	// Best-effort: a dropped event (crash, slow cb) is recovered by
	// re-running ChangedSince from the consumer's persisted cursor. Do
	// not treat the callback as a durable queue.
	Subscribe(cb func(ObjectChange)) (cancel func())

	// Generation is a per-space epoch that changes iff the SDK store was
	// rebuilt (the applySeq axis renumbered). It is stable across normal
	// restarts. A consumer persists it alongside its cursor; when the
	// returned value differs from the stored one (or the stored cursor
	// exceeds MaxApplySeq, an older-backup restore), it must reset the
	// cursor to 0 and full-reindex from a live QueryObjects snapshot.
	Generation(ctx context.Context) (string, error)
}

type ChangeList struct {
	Changes []ChangeMeta
	// Cursor resumes the NEXT page; "" = history exhausted.
	Cursor string
}

type ChangeMeta struct {
	Version   Version // ChangeId; for groups: the head (newest) member
	Author    string  // per-change signer identity (the objects row's modifiedBy, not its author)
	Timestamp int64   // author clock, Unix seconds — display-only
	Dataset   string
	TraceIds  []string
	Touched   []TouchedRecord
	// Truncated marks the oldest listable entry when the history
	// horizon was hit. RESERVED: always false today — the SDK never
	// writes tree snapshots, so full history is always local. It
	// becomes meaningful with the future snapshot/GC contract
	// (proposal §9); until then only ViewAt/Diff can surface
	// ErrHistoryTruncated (ACL gaps).
	Truncated bool
	GroupSize int // 1 unless coalesced
}

type CoalesceOpts struct {
	// Window bounds the author-clock spread between adjacent group
	// members. <=0 = 5 minutes.
	Window time.Duration
}

type CollectionCreateParams struct {
	Name        string
	Description string
	IconCID     string
	XKey        string
	Hidden      bool
	Meta        map[string]any
}

type CollectionInfo struct {
	Id          string
	Name        string
	Description string
	IconCID     string
	XKey        string
	Hidden      bool
	Meta        map[string]any
	// BuiltIn marks the synthetic `collection` meta-type and every
	// caller-registered collection. User collections return false.
	BuiltIn bool
}

type CollectionPatch struct {
	Name        *string
	Description *string
	IconCID     *string
	Hidden      *bool
	Meta        map[string]any
}

type CollectionsAPI interface {
	PropertyDefsAPI

	// List returns the meta `collection` built-in, every registered
	// collection and every user collection of this space. Hidden ones
	// are included; the consumer filters.
	List(ctx context.Context) ([]CollectionInfo, error)
	// Get returns one collection; ErrNotACollection for a type id,
	// ErrNotFound for anything else.
	Get(ctx context.Context, collectionId string) (CollectionInfo, error)

	// Create a new user-defined collection. Returns the new object's
	// id.
	Create(ctx context.Context, params CollectionCreateParams) (collectionId string, err error)

	// Delete a collection. Objects listing it keep the reference
	// (orphan), per docs §"read tolerance".
	Delete(ctx context.Context, collectionId string) error

	// Patch edits a user collection's display and listing metadata.
	// Registered built-ins refuse (ErrTypeRegistered); a type id
	// refuses (ErrNotACollection).
	Patch(ctx context.Context, collectionId string, patch CollectionPatch) error
}

type CreateObjectOpts struct {
	// Type is the object's one type (`any.type`). Required: every
	// object has exactly one type (ErrTypeRequired otherwise).
	Type string
	// Collections are the collections the object is filed under at
	// birth (`any.collections`). Optional.
	Collections []string

	// InitialProperties seeds base-scope property values. Keyed by
	// owner (the type or a collection) → propId → value. An owner the
	// object does not have is rejected — name it in Type / Collections.
	InitialProperties map[string]map[string]any
}

type CreateRequest struct {
	Name        string
	Description string
	IconCID     string
	// SpaceType is stamped into the space header at create time and
	// gated by the any-sync-coordinator. Must be SpaceTypeAny or empty
	// (same meaning). Anything else is rejected by Create with a clear
	// error; passing an invalid type would otherwise produce a space
	// the coordinator refuses to sync.
	SpaceType string
}

type DatasetDef struct {
	Id string // head record id, immutable
	// Key is the slug inside the type; Collection the name reads and
	// writes address (the module's canonical collection when Shared,
	// `<typeId>_<key>` otherwise) — server-computed, never client-set.
	Key        string
	Collection string
	Module     string
	Shared     bool
	// PartId is the owning part's id.
	PartId      string
	DisplayName string
	Description string
	Dynamic     bool
	IdRule      IdRule
	IdPattern   string
	IdMaxLen    int
	DeleteBy    DeletePolicy
	SkipHistory bool
	Search      *SearchFields
	Fields      []DatasetFieldDef

	// Invalid marks a definition whose folded declaration fails
	// validation (InvalidReason says why). Invalid definitions never
	// register or accept data but stay listed so they can be repaired
	// (AddDatasetField) or removed.
	Invalid       bool
	InvalidReason string
}

type DatasetDefPatch struct {
	Set   map[string]any
	Unset []string
}

type DatasetDiff struct {
	Dataset string
	Records []RecordDiff
}

type DatasetDraft struct {
	// Key is the dataset's slug inside its type — pinned. Namespaced
	// datasets live in the collection `<typeId>_<key>`; a shared
	// dataset's key is its module's canonical collection name and may
	// be left empty to default to it.
	Key string
	// Module is the serving module — "records" (the default when
	// empty), or a registered module such as "editor" / "chat".
	Module string
	// Shared makes the type participate in the module's canonical
	// collection instead of a namespaced one: two types sharing the
	// editor give an object carrying both a single body. Legal only
	// for modules with a canonical collection; at most one shared
	// dataset per module per type. Never for records.
	Shared bool

	DisplayName string
	Description string

	// Dynamic keeps a free-form keyspace next to the declared fields.
	Dynamic bool

	// IdRule / IdPattern / IdMaxLen: record-id production. Zero rule =
	// auto-derived ids; IdUser accepts caller ids (also the upsert
	// idempotency key) constrained by pattern/length.
	IdRule    IdRule
	IdPattern string
	IdMaxLen  int

	// DeleteBy gates record deletes. DeleteByAuthor requires a
	// StampCreator field among Fields.
	DeleteBy DeletePolicy

	// SkipHistory keeps the dataset out of the version-history index.
	SkipHistory bool

	// Search is the optional search-extraction annotation (x-search).
	Search *SearchFields

	// Fields are the initial field definitions. Records datasets only —
	// a module owns its schema and refuses fields.
	Fields []DatasetFieldDraft
}

type DatasetFieldDef struct {
	// Id is the field definition record's id — the identity
	// RemoveDatasetField / PatchDatasetField target.
	Id          string
	Key         string
	Name        string
	Description string
	Kind        PropertyKind
	// Shape is the full declared value shape (kind plus items /
	// properties); Kind is its top-level kind.
	Shape     *handler.FieldShape
	Scope     Scope
	Required  bool
	MutableBy Mutability
	Stamp     Stamp
	// XFormat is the opaque descriptor declared on the field, nil when
	// unset. See DatasetFieldDraft.XFormat.
	XFormat map[string]any
}

type DatasetFieldDraft struct {
	// Key is the on-record field name — pinned.
	Key         string
	Name        string
	Description string

	// Kind is the value kind. Required unless Stamp implies one
	// (creator ⇒ string, createTime/modifyTime ⇒ datetime).
	Kind PropertyKind
	// Shape optionally refines array/object values (items/properties).
	Shape *handler.FieldShape

	// Scope: zero = synced. Derived is implied by Stamp and rejected
	// otherwise.
	Scope Scope
	// Required: must be present on create. Incompatible with Stamp.
	Required bool
	// MutableBy: post-create write rule. Zero = write-once.
	MutableBy Mutability
	// Stamp: apply-time derived value (handler-written).
	Stamp Stamp

	// XFormat is the field's opaque descriptor (semantic slug, icon,
	// options, …) — the same bag a property definition carries. Stored
	// verbatim, mutable via PatchDatasetField, surfaced by Datasets()
	// and as the `x-format` keyword in discovery. Nil when unset.
	XFormat map[string]any
}

type DatasetSchema struct {
	Name       string
	JSONSchema json.RawMessage
	// Owners are the types that declare the dataset: exactly one for a
	// registered-type or namespaced dataset, every type declaring a
	// shared dataset of the module for a canonical collection (empty
	// while nothing declares it), none for space-level built-ins.
	// Consumers gate indexing/eviction on it — an object may hold the
	// dataset when it carries one of the owners.
	Owners []string
	// Module is the serving module ("records" for the generic
	// schema-enforced kind, "editor" / "chat" for registered modules);
	// empty for built-ins and registered-type datasets. Shared marks a
	// module's canonical collection.
	Module string
	Shared bool
}

type DebugAPI interface {
	Object(ctx context.Context, objectId string) (ObjectDebug, error)
	Space() SpaceDebug
}

type DeleteBatch struct {
	ObjectId  string
	Dataset   string
	RecordIds []string
	TraceIds  []string
}

type DeletePolicy = handler.DeletePolicy

type DeriveObjectOpts struct {
	Seed []byte
	// Type is set on first materialization; a type the object already
	// has is never replaced. Required unless the object already has one
	// (ErrTypeRequired). Collections it lacks are added on every call
	// ($addToSet, idempotent); optional.
	Type        string
	Collections []string

	// ParentId derives the object as a child bound to this parent. The
	// parent id is hashed into the child's derived id, so a child is
	// re-derivable only with the same ParentId. Deleting the parent
	// cascade-deletes the child's tree and excludes it from cold sync.
	// Empty derives a top-level object.
	//
	// Creating the child needs the parent's tree on this device:
	// ErrObjectNotFound until it has synced, ErrObjectDeleted once it
	// is deleted. A child that is already here (synced ahead of its
	// parent) re-derives regardless.
	ParentId string
}

type DeriveRequest struct {
	// Seed is hashed into the derivation. Zero seed = account-root
	// derivation (tech space).
	Seed []byte

	// SpaceType is an app-level tag surfaced as SpaceInfo.SpaceType for
	// client-side filtering. It is NOT the on-wire header type (that
	// stays SpaceTypeAny and is coordinator-gated) and not stamped into
	// the header as the type. Empty defaults to SpaceTypeAny.
	SpaceType string

	// Name is the initial display name, written on FIRST
	// materialization only (a pre-existing row keeps its metadata) and
	// NOT hashed into the derivation — the id is stable regardless.
	// Propagates into the in-space spaceIndex via the owner-side lazy
	// seed; rename later with Space.SetMetadata.
	Name string
}

type Device struct {
	// PeerId is the device's libp2p peer id — the row id. Stable per
	// device installation; every device writes only its own row.
	PeerId string

	// Name is the device's display name (hostname or user-set).
	Name string

	// OS is the device's operating system (runtime.GOOS vocabulary by
	// convention).
	OS string

	// Version is the device's engine build version.
	Version string

	// Apps is the set of installed apps keyed by slug (an open set —
	// nothing app-specific is hardcoded). Presence = installed; the
	// value is a free-form scalar bag (e.g. {"version": "1.2.3"}).
	// Nil when the device never registered an app.
	Apps map[string]map[string]any

	// ActiveClaims holds the device's active claim per app slug,
	// written by Service.ClaimActive. Resolve the winner with
	// ActiveDevice — never by comparing claims ad hoc.
	ActiveClaims map[string]DeviceClaim
}

type DeviceClaim struct {
	// Seq is max(existing seqs for the slug) + 1 at claim time;
	// highest wins.
	Seq int64
	// At is the claim wall-clock time in unix seconds — tiebreak on
	// equal Seq.
	At int64
}

type DeviceUpsert struct {
	Name    string
	OS      string
	Version string
	Apps    map[string]map[string]any
}

type DiffFilter struct {
	Dataset   string
	RecordIds []string // requires Dataset
}

type DiffKind string

type DiffResult struct {
	Base     Version
	Version  Version
	Datasets []DatasetDiff
}

type EnsureBundleRequest struct {
	// Id is the stable bundle identifier. Required.
	Id string
	// Name is the display name, written on install ($set — the
	// converged value is whichever install wins). Optional.
	Name string
	// NewRoot creates the bundle's root object and returns its id,
	// called only when no winner exists yet. The root must be a
	// non-derived object (Objects().Create) — a losing root must be
	// deletable, and derived trees are not. Required unless
	// DerivedRoot.
	//
	// Ensure stamps `any.name` (Name, falling back to Id) on the new
	// root: the root tree must carry a non-root change to enter the
	// head-sync diff, or a losing root could never be resolved from
	// another device.
	NewRoot func(ctx context.Context) (rootId string, err error)

	// DerivedRoot installs the bundle on its CANONICAL DERIVED root —
	// derived from the bundle id, so every device computes the same
	// root id with zero communication and concurrent installs cannot
	// fork. Ensure derives the root itself (NewRoot must be nil) and
	// stamps its membership (RootType / RootCollections).
	//
	// Two consequences, both permanent: the install can never be
	// uninstalled (derived trees are not deletable, so a dead-winner
	// reinstall is impossible), and a claimed canonical root always
	// wins the registry — see BundlesAPI.Ensure. The EXCEPTION, not
	// the default: bundles exist so a converged install does not need
	// a derived object, and the registry resolves created-root forks.
	// Derive only when a fork would be unmergeable — chat-like content,
	// above all the 1-1 general chat, where the convergence gate cannot
	// work — never for anything a user may remove or for id convenience.
	DerivedRoot bool
	// RootType is the type of the root Ensure mints — required on a
	// derived root that declares nothing (every object has a type),
	// written with its name in the root's first change and, on a later
	// Ensure, set when the row has no type yet (a type it already has
	// is never replaced). Refused next to a declaration (Parts /
	// Properties / XKey / Collection): a definition object carries its
	// marker in `any.type` and has no type of its own. A caller-minted
	// root (NewRoot) gets its type from NewRoot and refuses it here.
	RootType string
	// RootCollections are added to the root Ensure mints in that same
	// change, and on every later Ensure a collection the row lacks is
	// added ($addToSet, idempotent), so a request that gains one
	// reaches an existing install. NewRoot roots refuse them.
	RootCollections []string
	// RootProperties seeds the root's property values, keyed owner
	// (typeId or collectionId) → propId → value, in that same change
	// (their own op), before the install is registered, so a failed
	// seed leaves no install to adopt. Install only — an adopt never
	// re-seeds, the installer's values sync in. A keyed owner that is
	// neither RootType nor the root's own declaration is added to
	// RootCollections — a property write to an owner the object does
	// not have is rejected. Values are checked to encode before any
	// root is minted. The root's own id is a usable key only through
	// its declaration: its property ids are derived from (rootId,
	// XKey) and known before the install. Roots Ensure mints only.
	RootProperties map[string]map[string]any

	// Parts declares parts (with their datasets) on the root — derived
	// or created — which then defines a type: any.type = "__type__",
	// typeId = rootId. Records live on the objects of that type in the
	// declared collections (`<rootId>_<key>` for a namespaced dataset,
	// the module's canonical collection for a shared one),
	// discoverable through Types().Parts(rootId) / Datasets(rootId) and
	// Space.Datasets(), writable through Modify/Upsert. The root
	// itself hosts them too: a definition object implicitly implements
	// itself, which is how a bundle keeps its own records (favourites
	// entries, an app's layouts) on its root. Refused with Collection.
	// Declared in one change after the registering write, and on adopt
	// only when the root's tree is local and carries no declaration
	// yet (crash between registering and declaring, a row adopted
	// before the root tree synced); a root with any declaration —
	// live, or removed through Types().RemovePart — is left alone:
	// nothing is patched, added or resurrected by Ensure. Later
	// evolution goes through Types().AddPart / AddDataset /
	// AddDatasetField / PatchDataset with typeId = rootId. An invalid
	// or duplicate draft fails the request with ErrBundleBadRequest
	// before any root is minted. With a created strategy, omit NewRoot
	// and Ensure mints and stamps the root itself — the only create a
	// space with a fenced object lifecycle (the tech space) allows.
	// Parts or Properties are required on the tech space.
	Parts []PartDraft

	// Properties declares property definitions on the root, which then
	// defines a type like Parts does — or a collection, with
	// Collection set — for a bundle that IS a definition other objects
	// use (a wiki collection's `parentId` / `pos`).
	// Every draft needs an XKey, unique within the request: the
	// property id is DERIVED from (root id, XKey), so two devices
	// installing while apart mint one column per handle instead of
	// two. Declared in one change after the registering write; on
	// adopt only the definitions the root lacks are written — one is
	// present when its id exists (live, or removed through
	// Types().RemoveProperty: the tombstone keeps the id) or a live
	// definition carries its handle under any id, so nothing is
	// patched, resurrected or doubled. Later evolution goes through
	// Types().AddProperty / PatchProperty / RemoveProperty with typeId
	// = rootId; a property added that way gets an ordinary
	// change-derived id. Kind, Scope and XKey are validated as
	// AddProperty validates them, before any root is minted.
	Properties []PropertyDraft

	// XKey is the root definition's handle (TypeInfo.XKey /
	// CollectionInfo.XKey, stored as `type.xkey` / `collection.xkey`):
	// the stable slug a consumer resolves the definition by, and what
	// `relation.targetTypes` in other declarations name. An XKey alone
	// is a declaration — a MARKER type, or with Collection a marker
	// collection objects are filed under as a flag, with no columns.
	// Written with the name stamp on install; on adopt it is filled in
	// only when the root carries none (an install that predates the
	// handle), never changed. Not unique on the SDK side: the consumer
	// enforces handle uniqueness.
	XKey string
	// Layout and Hidden seed the root definition's rendering and
	// listing metadata with the name stamp, on install only — adopt
	// never patches them. They need a declaration — Parts, Properties
	// or XKey (ErrBundleBadRequest otherwise); Layout describes a
	// type and is refused with Collection. Hidden is EXPLICIT: a root
	// that only hosts its bundle's records should ask for it, since 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 (a page, a wiki) stays listed.
	Layout map[string]any
	Hidden bool

	// Collection makes the declaration a COLLECTION instead of a type:
	// the root carries `__collection__` in `any.type`, its handle and
	// flags live under `collection.*`, and Properties are its columns.
	// Parts and Layout are refused with it (a collection has neither).
	Collection bool
}

type EnsureOption func(*EnsureOptions)

type EnsureOptions struct {
	// SystemInstall marks the consumer's own catalog install: it lifts
	// the reserved-module refusal (handler.Module.Reserved) for this
	// call. The reservation exists so only the consumer's installs
	// declare such a module.
	SystemInstall bool
}

type EventOp struct {
	Type    crdt.OpType
	Path    []string
	Payload *anyenc.Value
}

type FieldDiff struct {
	Path   []string
	Before *anyenc.Value
	After  *anyenc.Value
}

type FileInfo struct {
	// FileId identifies the file within its space (the payloads row id).
	FileId string
	// ObjectId is the object the file is bound to.
	ObjectId string
	// RootCid is the content address of the encrypted file. Empty for
	// inline-tier files (which live inside the row itself).
	RootCid string
	// Size is the plaintext byte size.
	Size int64
	// Inline reports the inline tier (no RootCid, no backup needed).
	Inline bool
	// Durable reports whether the file is backed up on the network (a
	// verified custody receipt is recorded on the row). Inline files
	// are durable by construction.
	Durable bool
	// Name is the user-facing file name (member-only; empty without
	// the space key).
	Name string
	// Mime is the content-type hint (member-only).
	Mime string
	// Cached reports a complete local copy (always true for inline).
	Cached bool
	// Variant/VariantOf tag alternate representations (member-only;
	// empty for originals and keyless readers).
	Variant   Variant
	VariantOf string
}

type FileListOpts struct {
	// ObjectId restricts the listing to files bound to one object.
	ObjectId string
	// Limit caps the result (0 = unlimited). Applied after ObjectId.
	Limit int
}

type FileReader interface {
	io.Reader
	io.Seeker
	io.Closer
	// Size is the plaintext byte length.
	Size() int64
}

type FileStats struct {
	Total    int
	Durable  int
	InFlight int
	Limited  int
}

type FileStatus struct {
	FileId   string
	ObjectId string
	State    FileSyncState
	// Cached reports a complete local copy (inline always true).
	Cached bool
	// Attempts counts failed background attempts since the last
	// success/enqueue; 0 when no work is pending.
	Attempts int
	// LastErr is the last background-attempt failure ("" when none).
	LastErr string
}

type FileSyncState string

type Files interface {
	// Attach ingests r as a file bound to objectId. The whole reader is
	// consumed. Attach is local-only and never waits on the network:
	// registration is durable in the CRDT immediately, and for
	// node-backed files the backup ("durable") phase runs in the
	// background. A false FileInfo.Durable means the file is registered
	// and locally available but not yet backed up; Status and
	// SubscribeStatus observe the flip.
	Attach(ctx context.Context, objectId string, r io.Reader, opts AttachOpts) (FileInfo, error)

	// Open returns a random-access reader over the file's verified
	// plaintext. Content not yet local streams in on demand (every
	// fetched block persists, so reads accrete toward a complete local
	// copy); a file that is neither local nor durable is not openable
	// until the P2P block layer lands. The reader is bound to ctx.
	Open(ctx context.Context, fileId string, variant Variant) (FileReader, error)

	// Get returns the file's current info (member-only fields like
	// Name/Mime are empty for a keyless reader).
	Get(ctx context.Context, fileId string) (FileInfo, error)

	// Status derives the file's durability state on read: durable
	// (verified receipt on the row, inline included), in-flight
	// (registered; backup pending or being driven), or limited (the
	// network refused backup for storage limit; retried on a slow
	// cadence and on Retry).
	Status(ctx context.Context, fileId string) (FileStatus, error)

	// SubscribeStatus delivers FileStatus events for this space's
	// files on LOCAL transitions — attach, backup progress/failure,
	// pin completion, manual retries. (Remote flips — another device
	// finishing a backup — are visible via Status/Get reads; a synced
	// event feed arrives with the SYN-30 files view.) The returned
	// function unsubscribes.
	SubscribeStatus(cb func(FileStatus)) (unsubscribe func())

	// Stats returns this space's aggregate durability counts (UI
	// badges: "n files not backed up").
	Stats(ctx context.Context) (FileStats, error)

	// Pin schedules a full background fetch of the file's content into
	// the local store (survives restarts; on-demand reads stay the
	// default without it).
	Pin(ctx context.Context, fileId string) error

	// Retry makes the file's pending background work due immediately —
	// a limited file after a quota raise, or any stalled backup. No-op
	// with no pending work; re-enqueues the backup when the row is
	// unsigned and the bytes are local.
	Retry(ctx context.Context, fileId string) error

	// Offload drops the file's local bytes, keeping the file itself —
	// a later Open transparently refetches from the network. Refused
	// unless the file is backed up (never drops the only copy); inline
	// files are a no-op. Content shared with other files (dedup) loses
	// its local bytes for all of them — each stays refetchable; Pin a
	// sibling to keep it hot.
	Offload(ctx context.Context, fileId string) error

	// Delete removes the file: its payload row is deleted in one synced
	// CRDT change (every member sees the file disappear), pending
	// background work is cancelled, and the local content ref is
	// released so cache GC reclaims the bytes (unreferenced CARs age
	// out past the safety-sweep grace period — deletion never races a
	// settling sync). Deleting an original also deletes its variant
	// rows — they are unresolvable without it; a keyless reader (who
	// cannot see VariantOf) deletes only the addressed row. Content
	// shared with a surviving row (dedup/BIND) is untouched: each row
	// holds its own ref. The network copy is NOT reclaimed here —
	// fileprotov2 has no delete RPC yet; the broker's row-driven
	// accounting stops counting the rows once the deletion syncs.
	// ErrNotFound when no such file exists (Delete is not idempotent
	// over the wire — a second call fails like any other read).
	Delete(ctx context.Context, fileId string) error

	// List returns the space's files as typed infos. Opts.ObjectId
	// restricts to one object's files (the fast path — one indexed
	// lookup). The unfiltered listing walks every file in the space:
	// fine for human-scale spaces, but a consumer tracking a very
	// large space should page with Opts.Limit or drive Query/Changes
	// instead of re-listing.
	List(ctx context.Context, opts FileListOpts) ([]FileInfo, error)

	// Query returns the generic query surface (filter / sort /
	// subscribe — see space.Query) over the payload rows of ONE
	// object's files. Rows expose the cleartext fields (fileId,
	// rootCid, size, networkSign, objectId); the member-only meta
	// stays sealed — use Get/List for typed access to it.
	//
	// ErrNotFound until the object's first file is attached (the
	// backing dataset materializes with the first Attach) — fall back
	// to List/Changes until then.
	Query(objectId string) (Query, error)
}

type HistoricalView interface {
	// Version returns the cut handle the view was built at.
	Version() Version
	// Datasets lists dataset names this view can serve.
	Datasets() []string
	// Record returns one record (nil if absent at this version).
	// Deleted records surface as tombstones (`_deletedAt` set).
	Record(ctx context.Context, dataset, recordId string) (*anyenc.Value, error)
	// Records returns all live records of a dataset at this version.
	Records(ctx context.Context, dataset string) ([]*anyenc.Value, error)
	Close() error
}

type HistoryAPI interface {
	// ListChanges lists an object's history, newest first (descending
	// causal order: parents never appear after children; timestamps
	// are author-supplied and display-only). Pagination via the opaque
	// cursor returned in ChangeList. The first call on an object whose
	// index is stale triggers a lazy backfill.
	ListChanges(ctx context.Context, objectId string, f HistoryFilter, limit int, cursor string) (ChangeList, error)

	// ViewAt materializes the object as of version — object or (via
	// filter in the returned view's Records calls) dataset scope. The
	// view holds an in-memory projection of the SYNCED scope only:
	// local/account-scope values have no history in the object's DAG
	// and are excluded rather than misleadingly shown current. The
	// caller must Close.
	ViewAt(ctx context.Context, objectId string, version Version) (HistoricalView, error)

	// RecordAt reconstructs one record as of version — the chat-scale
	// fast path (filtered replay ∩ causal past). Returns nil when the
	// record does not exist at that cut; a deleted record surfaces as
	// its tombstone (check the `_deletedAt` field).
	RecordAt(ctx context.Context, objectId, dataset, recordId string, version Version) (*anyenc.Value, error)

	// Diff computes the structural difference between two versions.
	// base == "" means version's parents — the per-change effect diff
	// ("what did this change actually land", ops gated out by newer
	// concurrent writes excluded). Scope narrows via the filter.
	Diff(ctx context.Context, objectId string, base, version Version, f DiffFilter) (DiffResult, error)
}

type HistoryFilter struct {
	Dataset  string        // only this dataset
	RecordId string        // only changes touching this record (requires Dataset)
	TraceId  string        // only changes carrying this trace id
	Author   string        // identity filter
	Coalesce *CoalesceOpts // group keystroke-grained changes; nil = raw
}

type IdRule = handler.IdRule

type IdentitiesAPI interface {
	// List returns every known identity.
	List(ctx context.Context) ([]IdentityInfo, error)
	// Get returns a single identity, ok=false when never encountered.
	Get(ctx context.Context, identity string) (info IdentityInfo, ok bool, err error)
	// Subscribe streams add/update/remove batches for the directory.
	// The returned func cancels the subscription.
	Subscribe(cb func(IdentityListEvent)) (cancel func())
}

type IdentityInfo struct {
	// Identity is the account address (the row key).
	Identity string
	// Name / Description / IconCID are the last profile resolved from
	// identityRepo; empty until resolved (or if we lack the key).
	Name        string
	Description string
	IconCID     string
	// SpaceIds is the set of spaces where we've currently seen this
	// identity (pruned when we leave/offload a space).
	SpaceIds []string
}

type IdentityListEvent struct {
	Added   []IdentityInfo
	Updated []IdentityInfo
	Removed []string
}

type Indexer interface {
	// OnSpaceCreated runs after a new space is successfully created or
	// joined. The hook is expected to add a record to the space index
	// in the tech space. Errors are logged but do not abort the
	// creation — the space exists either way.
	OnSpaceCreated(ctx context.Context, spaceId string, meta SpaceInfo) error

	// OnSpaceDeleted runs after local deletion. The hook flips the
	// space index record to Status = StatusDeleted; the record is
	// never physically removed (see docs/tech-space.md).
	OnSpaceDeleted(ctx context.Context, spaceId string) error

	// OnSpaceMetadataUpdated mirrors the converged state of the
	// per-space `spaceIndex` derived object into the tech-space row.
	// Fired by the per-space watcher every time the spaceIndex
	// object's property record applies (locally or pushed from a
	// peer). Idempotent overwrite of name/description/icon — `type`
	// stays pinned by the tech-space handler. See
	// docs/space-index-proposal.md for the convergence story.
	OnSpaceMetadataUpdated(ctx context.Context, spaceId string, meta SpaceInfo) error
}

type Invite struct {
	SpaceId   string
	InviteKey crypto.PrivKey
	// Kind distinguishes a member invite (RequestToJoin proof key) from
	// a guest invite (the shared read-only guest identity itself). Zero
	// value is member — pre-Kind invites decode as members.
	Kind InviteKind
}

type InviteInfo struct {
	RecordId string
	// Permission applies only to AnyoneCanJoin invites — for the
	// RequestToJoin path it is set at accept time. Always
	// PermissionNone here in v1.
	Permission Permission
	// Key is the invite private key when THIS account minted the
	// invite: recovered from the account's synced issued-key custody
	// (the ACL record carries only the public key), so it is present
	// on every device of the minting account and nil everywhere else —
	// other members', even admins', devices never held it. Also nil
	// for invites minted before custody shipped (re-mint once to make
	// them recoverable) and for custody gone stale (invite replaced /
	// revoked elsewhere). Non-nil Key re-encodes to the original share
	// token via EncodeInvite(Invite{SpaceId, InviteKey: Key}).
	Key crypto.PrivKey
}

type InviteKind byte

type Iterator interface {
	Next() bool
	Doc() (*anyenc.Value, error)
	Err() error
	Close() error
}

type JoinRequest struct {
	// Invite is the invite string produced by ACL.CreateInvite on the
	// host side. The SDK parses it internally; opaque to the caller.
	Invite string

	// Metadata is the joining account's metadata that will be attached
	// to the ACL join record (display name, icon, etc.).
	Metadata AccountMetadata
}

type JoinRequestInfo struct {
	// RecordId is the ACL record id — pass it to ACL.AcceptRequest.
	RecordId string
	// Identity is the joiner's account id.
	Identity string
	// Name / Description / IconCID are decoded from the metadata blob
	// the joiner attached at request time.
	Name        string
	Description string
	IconCID     string
}

type Member struct {
	Identity    string
	Permission  Permission
	Status      MemberStatus
	Name        string
	Description string
	IconCID     string

	// RequestRecordId is set only when Status == MemberStatusJoining.
	// Pass it to ACL.AcceptRequest / DeclineRequest.
	RequestRecordId string
}

type MemberAdd struct {
	Identity   string
	Permission Permission
	Metadata   AccountMetadata
}

type MemberEvent struct {
	Kind     MemberEventKind
	Member   Member
	Previous *Member
}

type MemberEventKind uint8

type MemberStatus uint8

type MembersAPI interface {
	// List returns every account currently visible in the ACL: active
	// members, removed-member tombstones (Status=Removed), and pending
	// join requests (Status=Joining). Order is not stable across calls.
	List(ctx context.Context) ([]Member, error)

	// Get returns a single member entry by identity, or ErrNotFound.
	// Pending join requests are reachable here too.
	Get(ctx context.Context, identity string) (Member, error)

	// Me returns the caller's own member entry. Convenient shortcut
	// for surfacing the caller's role in the UI.
	Me(ctx context.Context) (Member, error)

	// JoinRequests returns the subset of List() with Status=Joining —
	// kept as a convenience for admin UIs that approve / decline.
	JoinRequests(ctx context.Context) ([]JoinRequestInfo, error)

	// Invites returns the active invites for this space, with their
	// record ids (use these as inputs to ACL.RevokeInvite).
	Invites(ctx context.Context) ([]InviteInfo, error)

	// Subscribe registers a firehose listener. cb runs synchronously
	// from the watcher goroutine — keep work small or hand off to your
	// own goroutine. The returned cancel function detaches the
	// subscriber; it's safe to call multiple times.
	//
	// Events cover: a new member appearing (active or pending),
	// permission/status flips, and members disappearing (pending
	// requests dropped on accept/decline/cancel; full members keep
	// a Status=Removed tombstone via a Changed event).
	Subscribe(cb func(MemberEvent)) (cancel func())

	// Query returns a chainable query builder over the materialized
	// members system collection. Supports the same Filter / Sort /
	// Limit / Offset shape as Space.Query / Space.QueryObjects.
	//
	// The collection is kept in sync with the underlying ACL by the
	// per-space watcher (poll interval ~250 ms). Reads here may lag
	// in-memory state (List / Get / Me) by at most one tick; for
	// strictly current state use those direct methods.
	//
	// Schema fields (all strings unless noted):
	//   id          — identity (== Member.Identity)
	//   permission  — "owner" / "admin" / "writer" / "reader" / "guest" / "none"
	//   status      — "active" / "joining" / "removed" / "removing" /
	//                 "declined" / "canceled" / "unknown"
	//   name        — decoded display name
	//   description — decoded description
	//   icon        — IconCID
	//   requestId   — present only for status=joining (recordId for accept)
	Query() Query
}

type ModifyBatch struct {
	ObjectId string
	Dataset  string
	Records  []RecordModify

	// TraceIds are opaque caller-supplied correlation tokens that
	// travel through any-sync in a dedicated field so the whole space
	// can be queried by trace. Empty slice means no trace.
	TraceIds []string

	// Scope selects the write route for the whole batch. A write call
	// is single-scope — routes commit in different version domains and
	// there is no cross-route rollback (same rule as PropertiesAPI.Set).
	// Zero value = ScopeSynced: the object's own DAG change, synced to
	// every member. The default, and the only route ModifyMany and
	// Delete support.
	//
	// ScopeLocal is the device-local materialization route: no DAG
	// change, never syncs, VersionId minted by the local lexid
	// allocator; the write flows through Query/Subscribe like any
	// apply. Every op must target a field the dataset schema declares
	// ScopeLocal — ops on fields of any other scope are refused by the
	// apply layer's scope enforcement and surface in
	// ModifyResult.Rejections, like handler rejections on the synced
	// route. Records must already exist: explicit ids, no Upsert —
	// local fields annotate synced records, they don't create them
	// (a strict-mode miss surfaces as an ErrStrictSkipAbsent
	// rejection). TraceIds are rejected (they ride the any-sync
	// change). The shared `objects` dataset is rejected too: its
	// per-property scopes are enforced by the writer, so local
	// property values go through PropertiesAPI.Set.
	//
	// ScopeAccount and ScopeDerived are rejected: derived is
	// handler-only, and the account transport for dataset records is
	// not wired yet — the account mirror handles objects rows only
	// (docs/scoped-properties-proposal.md § Account transport).
	Scope Scope
}

type ModifyResult struct {
	VersionId  VersionId
	ChangeId   string
	RecordIds  []string
	Rejections []OpRejection
}

type Mutability = handler.Mutability

type ObjectChange struct {
	ObjectId string
	ApplySeq uint64
	Deleted  bool
}

type ObjectDebug struct {
	ObjectId string

	// Sync state — from the per-space syncstatus.Tracker. Pending
	// is the set of heads the tracker is waiting for a
	// responsible-node HeadsApply on; empty means converged with
	// the last sender we trust.
	SyncState  SyncState
	Pending    []string
	LastSyncAt time.Time

	// Tree structure — read from any-sync's ObjectTree.
	//
	// HeadsCount == len(Heads), exposed as a separate field so a
	// caller checking "is this object diverged right now" doesn't
	// need to len() the slice.
	//
	// BranchCount counts every branch that ever existed in the
	// DAG: merged-in lineages (one per extra parent on a merge
	// change) plus still-open ones (HeadsCount - 1). A linear
	// tree with one head returns 0.
	//
	// Snapshots is the number of changes carrying IsSnapshot in
	// the tree. Costs a full IterateRoot walk — O(TreeLen).
	Heads       []string
	HeadsCount  int
	BranchCount int
	TreeLen     int
	Snapshots   int

	// LatestVersionId is the lexid-max OrderId across Heads. Empty
	// string when the tree has no heads (root-only or transient
	// states during cold restore). The value is local to this
	// peer's any-sync — VersionIds don't match across peers.
	LatestVersionId string

	// MaxAddSeq is the controller's delivery-order watermark — the
	// highest AddSeq seen by the apply path. Used internally for
	// cold-restore replay; surfaced here as a sanity check that
	// the controller is keeping up with the tree.
	MaxAddSeq uint64
}

type ObjectReadState struct {
	ObjectId string
	// StateSeq is the cursor axis — same per-space monotonic domain
	// as ObjectChange.ApplySeq. Persist the last seen value and pass
	// it back to ChangedSince.
	StateSeq uint64
}

type ObjectService interface {
	// Get returns the object's row from the per-space objects
	// collection (membership and property values). An object whose tree
	// is present locally but that never wrote a row returns {id} only;
	// ErrNotFound when the id is unknown here, ErrObjectDeleted when
	// the object's tree is deleted — both read from the space's
	// any-sync storage.
	Get(ctx context.Context, objectId string) (*anyenc.Value, error)

	// Create a fresh object. Returns the any-sync-assigned objectId.
	// Type and Collections seed the object's membership at birth;
	// InitialProperties seeds the per-space properties record.
	Create(ctx context.Context, opts CreateObjectOpts) (objectId string, err error)

	// Derive a deterministic object from a seed. Re-runs idempotently;
	// second call with the same seed returns the same objectId.
	Derive(ctx context.Context, opts DeriveObjectOpts) (objectId string, err error)

	// Delete marks the object as deleted (any-sync settings tree) and
	// wipes local any-store state. See docs/object.md §"Deletion".
	Delete(ctx context.Context, objectId string) error
}

type ObjectSyncStatus struct {
	ObjectId   string
	State      SyncState
	LastSyncAt time.Time
}

type Op struct {
	Type OpType
	Path string
	// Value is the operand — scalar, slice, or map[string]any
	// depending on Type. A value means what its JSON form means:
	// Extended-JSON wrappers are typed values, the same spelling a
	// Query.Filter literal uses, and {"$date": "<RFC 3339>"} is the
	// one with a property kind (datetime); $binary, $oid and $vector
	// decode too but fit only undeclared fields. A Go time.Time is a
	// datetime and []byte is binary, at any depth of map[string]any /
	// []any. A *fastjson.Value is decoded under the same rule; a
	// *anyenc.Value is taken verbatim. Every value written into a
	// dataset record follows this rule: UpsertRecord.Fields,
	// PropertiesAPI.Set, CreateObjectOpts.InitialProperties,
	// PropertyPatch.Set, DatasetDefPatch.Set. Tech-space settings and
	// device app bags are scalar-only (Service.SetSettings,
	// DeviceUpsert.Apps).
	Value any
}

type OpRejection struct {
	RecordIndex int
	RecordId    string
	OpIndex     int
	Reason      string
	ReasonErr   error
}

type OpType string

type P2PState uint8

type PartDef struct {
	Id       string // part record id, immutable
	Key      string
	Name     string
	Icon     string
	Pos      string
	Hidden   bool
	UI       map[string]any
	Uses     []string
	Datasets []DatasetDef
}

type PartDraft struct {
	// Key is the part's slug, unique within the type — pinned.
	Key string
	// Name / Icon / Pos are the display slice; clients sort parts by
	// Pos. Hidden parts are not shown by default but stay revealable.
	Name   string
	Icon   string
	Pos    string
	Hidden bool
	// UI is the widget descriptor — a slug plus an opaque config in the
	// x-format shape ({type, config}). Written whole; nil = the first
	// dataset's module default.
	UI map[string]any
	// Uses names other datasets OF THIS TYPE the part renders without
	// owning them (keys).
	Uses []string
	// Datasets are the part's initial dataset declarations.
	Datasets []DatasetDraft
}

type PayloadRow struct {
	// FileId identifies the row — derived from the creating change,
	// deterministic and never reused.
	FileId string

	// RootCid is the UnixFS root of the encrypted file. Empty for
	// inline-tier rows (bytes ride inside the sealed blob).
	RootCid string

	// Size is the plaintext byte size (cleartext hint; quota uses the
	// node's own measurement).
	Size int64

	// NetworkSign is the node's durable-custody receipt. Empty until
	// the file is durable; always empty for inline rows.
	NetworkSign string

	// Author is the account that registered the file (derived from the
	// creating change's signer).
	Author string

	// ObjectId is the object the file is bound to (the cleartext parent
	// reference).
	ObjectId string

	// Sealed reports whether the row's member-only secrets remain
	// closed to this identity. True for a keyless reader (the broker
	// view — not an error); false when the local account holds the
	// space key, even though the secrets are still not exposed here.
	Sealed bool
}

type PayloadsView interface {
	// ListObjects returns the objectIds of the materialized payloads
	// objects in this space (one per file owner, derived lazily on the
	// owner's first registration). Classified by the tree root's
	// changeType — signed and content-addressed, so the set can't be
	// spoofed. Trees known only as heads-only stubs (selective sync) or
	// deleted trees are excluded.
	ListObjects(ctx context.Context) ([]string, error)

	// ListRows returns every live row of one payloads object. The
	// object must be materialized locally (an id from ListObjects);
	// rows come back in collection order.
	ListRows(ctx context.Context, payloadsObjectId string) ([]PayloadRow, error)
}

type PeerSyncStats struct {
	PeerId     string
	LastSyncAt time.Time
	New        int
	Changed    int
	LastErr    string
}

type Permission uint8

type PermissionChange struct {
	Identity   string
	Permission Permission
}

type ProjectionOpts struct {
	// IncludeDeleted returns record-level tombstone rows (id, _deletedAt,
	// _ver, _traces, _addSeq; content wiped) instead of skipping them —
	// e.g. a deleted record inside a still-live object's dataset. Honored
	// by the find path (Iter / All / One / Count); Snapshot/Subscribe keep
	// skipping tombstones (the windowed live view is unchanged).
	//
	// Note: a deleted OBJECT is NOT a tombstone. Its whole local
	// projection is purged (any-sync's head storage is the durable,
	// cross-device delete record), so IncludeDeleted surfaces nothing for
	// it on QueryObjects. Observe object deletions via
	// QueryObjects().Subscribe (a Removed{RemoveDeleted} event), or by
	// reconciling against any-sync's deleted-tree set.
	IncludeDeleted bool
}

type PropertiesAPI interface {
	Get(ctx context.Context, objectId string) (*anyenc.Value, error)

	// Set merges the patch into the object's property record. ownerId
	// is the type or collection whose properties the patch names; keys
	// are propIds and all must resolve to the SAME declared scope.
	// Unknown keys, kind mismatches, mixed-scope patches, and an owner
	// the object does not have are rejected before anything is
	// written.
	Set(ctx context.Context, objectId, ownerId string, patch map[string]any) (ModifyResult, error)

	// SetType replaces the object's type. The previous type's values
	// and dataset records become orphan data, read-tolerant; its
	// datasets refuse further writes. A known collection id is refused
	// (ErrWrongSlot).
	SetType(ctx context.Context, objectId, typeId string) (ModifyResult, error)

	// AttachCollection adds the object to a collection ($addToSet —
	// idempotent). A known type id is refused (ErrWrongSlot).
	AttachCollection(ctx context.Context, objectId, collectionId string) (ModifyResult, error)
	// DetachCollection removes the object from a collection ($pull).
	// Values in that namespace become orphan data, read-tolerant.
	DetachCollection(ctx context.Context, objectId, collectionId string) (ModifyResult, error)
}

type PropertyDef struct {
	Id          string // base58(xxh3-64(changeId)), immutable
	Name        string // display label, CRDT-mutable
	Description string // CRDT-mutable

	// XKey is an optional stable caller-side key (e.g. for generated
	// client code mapping). Not unique, not enforced — metadata only.
	XKey string

	// Meta is an opaque consumer-controlled flag map. The SDK stores
	// and returns it verbatim and never interprets it — e.g. the `any`
	// server's search indexer reads meta["index"] = "<scope>" to mark
	// a property as full-text/vector indexable. Nil when unset.
	// Deliberately not schema-bearing: CRDT-mutable via PatchProperty
	// (meta.<k> paths).
	Meta map[string]string

	Kind       PropertyKind  // first-write-wins; immutable
	Items      *PropertyDef  // for arrays
	Properties []PropertyDef // for objects
	Required   []string      // for objects — CRDT-mutable additions

	// Scope is the property's write/sync class (synced / account /
	// local; derived on built-ins). First-write-wins like Kind —
	// immutable for the propId's life. Definitions written before
	// scopes existed read back as ScopeSynced.
	Scope Scope

	// XFormat is the property's opaque descriptor — semantic slug,
	// icon, ordering key, option set, relation targets, per-format
	// config — as the consumer wrote it. The SDK stores it verbatim,
	// never interprets it, and lets every path under it mutate
	// (PatchProperty); a whole-bag write must be an object. Nil for
	// definitions that carry none. Decoded from the record with plain
	// Go values: nested objects as map[string]any, arrays as []any,
	// numbers as float64, instants as time.Time, binaries as []byte,
	// object ids as hex strings, float vectors as []float64. Every
	// view is a fresh copy — the caller's to mutate.
	XFormat map[string]any
}

type PropertyDefsAPI interface {
	// Properties returns the current property definitions of the
	// owner. Built-ins (`any`, `type`, `collection`, `spaceIndex`) and
	// registered definitions answer their static tables.
	Properties(ctx context.Context, ownerId string) ([]PropertyDef, error)

	// AddProperty mints a new property on the owner. The returned
	// propId is base58(xxh3-64(changeId)) — immutable for the life of
	// the property. Registered owners refuse (ErrTypeRegistered).
	AddProperty(ctx context.Context, ownerId string, draft PropertyDraft) (propId string, err error)

	// RemoveProperty drops a property definition. Existing value
	// records are NOT cleaned up; subsequent writes touching that
	// property are dropped op-by-op via the unknown-property rule.
	RemoveProperty(ctx context.Context, ownerId, propId string) error

	// PatchProperty applies a generic per-path patch to a property
	// definition. Set assigns values at dotted paths; Unset removes
	// them. Both merge per-path through the record's CRDT, so
	// concurrent edits to different paths converge.
	//
	// Mutable paths: name, description, x-key, meta.<k>, x-format and
	// every path under it (any JSON value — the SDK stores the
	// descriptor opaquely; the consumer owns its vocabulary and its
	// leaf-only patch rule). Pinned paths (key, kind, scope, items,
	// properties) are rejected — define a new property to change them.
	PatchProperty(ctx context.Context, ownerId, propId string, patch PropertyPatch) error
}

type PropertyDraft struct {
	Name        string
	Description string
	XKey        string
	Meta        map[string]string // opaque consumer flags — see PropertyDef.Meta
	Kind        PropertyKind
	Items       *PropertyDraft
	Properties  []PropertyDraft
	Required    []string

	// Scope is the property's write/sync class. Zero value means
	// ScopeSynced. ScopeDerived is reserved for built-ins and rejected.
	// Pinned by the first write — to change a property's scope, define
	// a new property (which mints a new propId).
	Scope Scope

	// XFormat optionally declares the descriptor at creation, written
	// as one whole object (see PropertyDef.XFormat). Values convert as
	// Op.Value describes; nothing inside is validated — the consumer
	// owns the vocabulary.
	XFormat map[string]any
}

type PropertyKind uint8

type PropertyPatch struct {
	Set   map[string]any
	Unset []string
}

type PubSubAPI interface {
	// Publish sends payload on topic. Returns fast after local
	// validation, signing and encryption — network delivery is
	// asynchronous and unacknowledged. Local subscribers with a
	// matching pattern receive the message synchronously (Self=true).
	Publish(ctx context.Context, topic string, payload []byte) error

	// Subscribe registers cb for messages matching pattern and pushes
	// the interest to the space's peers. cb runs on a single shared
	// dispatch goroutine and MUST NOT block — slow handlers drop
	// messages for every subscriber. Do not call Publish synchronously
	// from cb while holding locks cb needs. The returned cancel is
	// idempotent; cb may fire once more after cancel returns.
	Subscribe(pattern string, cb func(PubSubMessage)) (cancel func(), err error)
}

type PubSubMessage struct {
	// SpaceId the message was published in.
	SpaceId string
	// Topic the publisher targeted (concrete, no wildcards).
	Topic string
	// SenderIdentity is the sender's account address (same form as
	// Account().Id() / Member.Identity).
	SenderIdentity string
	// Self is true when the message is the loopback delivery of this
	// account's own publish (any device of the account).
	Self bool
	// Payload is the decrypted application payload.
	Payload []byte
}

type PushAPI interface {
	// SetToken registers this device's platform push token (APNs / FCM)
	// with the server. Call again on token rotation; RevokeToken on
	// logout.
	SetToken(ctx context.Context, platform PushPlatform, token string) error

	// RevokeToken removes this device's push token — the device stops
	// receiving notifications for the account.
	RevokeToken(ctx context.Context) error

	// RegisterSpace registers the space's derived push key with the
	// server, enabling Notify/Subscribe for its topics. Requires read
	// access to the space's ACL (members only). Idempotent — the server
	// treats a re-registration as success.
	RegisterSpace(ctx context.Context, spaceId string) error

	// RemoveSpace unregisters the space's push key — its topics and
	// subscriptions are dropped server-side.
	RemoveSpace(ctx context.Context, spaceId string) error

	// SubscribeAll replaces the account's ENTIRE topic set across all
	// spaces (server semantics: full replace, not a merge). Callers own
	// the reconcile: compute the complete desired set — every space,
	// every topic — and submit it in one call; anything absent is
	// unsubscribed.
	SubscribeAll(ctx context.Context, subs []PushSpaceTopics) error

	// Subscriptions returns the account's current topic set as the
	// server holds it — raw {base58 spaceKey, topic} rows, without
	// signatures. Use it to diff local desired state against the server
	// before a SubscribeAll.
	Subscriptions(ctx context.Context) ([]PushSubscription, error)

	// Notify publishes an encrypted notification to the given topic
	// strings within spaceId. The payload (cleartext JSON by
	// convention) is encrypted with the space's derived key and signed
	// by this account; only space members can decrypt. groupId is the
	// server-side collapse key (e.g. a chat id) — an opaque grouping
	// hint, empty for none.
	Notify(ctx context.Context, spaceId string, topics []string, payload []byte, groupId string) error

	// NotifySilent wakes the account's OWN other devices with a
	// data-only push (no user-visible message) — e.g. after a read-state
	// change, so their badges refresh. It targets only the caller's
	// own-identity topic within spaceId; the server drops any other
	// topic on the silent path.
	NotifySilent(ctx context.Context, spaceId string, groupId string) error
}

type PushKeys struct {
	// SpaceKey is the base64 (std) of the protobuf-marshalled ed25519
	// private key that identifies the space on the push server
	// (pushapi Topic.SpaceKey is its public half). Derived from the
	// ACL's first metadata key — fixed for the space's life.
	SpaceKey string
	// EncKey is the base64 (std) of the raw AES payload key derived
	// from the CURRENT ACL read key.
	EncKey string
	// EncKeyId is hex(sha256(raw EncKey bytes)) — the value stamped
	// into pushapi.Message.KeyId, i.e. the cache key a receiver looks
	// up on an incoming push.
	EncKeyId string
}

type PushPlatform string

type PushSpaceTopics struct {
	SpaceId string
	Topics  []string
}

type PushSubscription struct {
	SpaceKey string
	Topic    string
}

type Query interface {
	// Filter applies a query condition. Anything query.ParseCondition
	// accepts works — an already-built query.Filter, a JSON-shaped
	// string ("{\"any.name\":\"Casablanca\"}"), or a map literal with
	// mongo-style operators ($eq, $gt, $in, $and, $or, …). The
	// argument is parsed eagerly; a malformed filter surfaces on the
	// first terminal call (Iter / All / One / Count), not silently.
	// A map literal is converted like a record value (see Op.Value):
	// a time.Time or []byte in it is typed, and a {"$date": …}
	// literal is an instant, so a datetime field is filtered by either
	// spelling.
	Filter(filter any) Query

	// Sort orders results by the given keys. Anything query.ParseSort
	// accepts works — string keys ("-_ver.id" for descending) or
	// already-built query.Sort values. Parsed eagerly; errors surface
	// on the terminal call.
	Sort(sorts ...any) Query

	// Limit caps returned records. Zero means unlimited.
	Limit(n int) Query

	// Offset skips the first n records. Use cautiously for large result
	// sets — cursor-based pagination is a future add.
	Offset(n int) Query

	// Projection controls which reserved fields appear in returned
	// records. See ProjectionOpts.
	Projection(opts ProjectionOpts) Query

	// Iter opens a streaming iterator. Caller must Close when done.
	Iter(ctx context.Context) (Iterator, error)

	// All materializes every match into a slice. Convenience wrapper
	// around Iter; avoid for large result sets.
	All(ctx context.Context) ([]*anyenc.Value, error)

	// One returns the first match or (nil, ErrNotFound).
	One(ctx context.Context) (*anyenc.Value, error)

	// Count returns the match count without returning documents.
	Count(ctx context.Context) (int, error)

	// Snapshot is the typed terminal that returns an initial result set
	// plus an optional one-shot total count, without subscribing for
	// live updates. Same result shape as Subscribe — callers that only
	// need a point-in-time view can use this instead of chaining
	// All + Count separately.
	Snapshot(ctx context.Context, opts QueryOpts) (*QueryResult, error)

	// Subscribe returns the initial snapshot AND a live QuerySubscription
	// whose mailbox carries incremental updates (added / updated /
	// removed records within the windowed view). The window tracks the
	// chained filter / sort / limit; offset applies to the initial
	// snapshot only.
	//
	// Sub closes with ErrSubscriptionOverflow when its mailbox fills,
	// or ErrSubscriptionDrifted when too many in-window records leave
	// without replacements. Both signal "resubscribe to recover".
	Subscribe(ctx context.Context, opts QueryOpts) (*QueryResult, error)
}

type QueryOpts struct {
	// IncludeTotal asks for a one-shot count of filter-matching records
	// (independent of limit/offset), returned in QueryResult.Total, and
	// derives QueryResult.HasNext from it. No live total events are
	// emitted by Subscribe; callers who need a refreshed count call
	// Snapshot again. When false, Total is -1 and HasNext is false.
	IncludeTotal bool

	// MailboxCapacity bounds the per-subscription event queue. Default
	// 256, minimum 16. On overflow the subscription closes; Wait
	// returns mb.ErrClosed and Err() returns ErrSubscriptionOverflow.
	// Subscribe-only.
	MailboxCapacity int

	// DriftBudgetPercent: when more than this fraction of Limit
	// records leave the held window without replacements, the
	// subscription closes with ErrSubscriptionDrifted. Default 30.
	// Ignored when Limit == 0. Subscribe-only.
	DriftBudgetPercent int
}

type QueryResult struct {
	Initial []*anyenc.Value
	Total   int               // -1 unless QueryOpts.IncludeTotal=true
	HasNext bool              // true when more matches exist past this page (offset+len(Initial) < Total); always false when Total is unknown
	Sub     QuerySubscription // nil for Snapshot
}

type QuerySubscription interface {
	// Events returns the underlying mb/v3 mailbox. Use Wait for
	// batched delivery or WaitOne for single events.
	Events() *mb.MB[SubscriptionEvent]

	// Err returns the close reason after the mailbox closes. nil
	// while the subscription is live or after a user-initiated Close.
	Err() error

	// Close releases the subscription. Idempotent.
	Close() error
}

type ReadStateAPI interface {
	// Subscribe fires after a committed read-state change for an
	// object. cb runs synchronously on the notifying path — keep it
	// small or hand off.
	Subscribe(cb func(objectId string, stateSeq uint64)) (cancel func())

	// ChangedSince returns objects whose read state advanced past
	// since, ascending by StateSeq, capped at limit (0 = no cap) —
	// one element per object. Re-pull UnreadSnapshot per dirty object
	// and diff against your held set.
	ChangedSince(ctx context.Context, since uint64, limit int) ([]ObjectReadState, error)

	// UnreadSnapshot returns the object's full current unread set
	// (ascending by VersionId) and the object's current stateSeq —
	// the per-object pull after a ChangedSince hit, and the cold
	// start / resync entry point.
	UnreadSnapshot(ctx context.Context, objectId string) ([]UnreadChange, uint64, error)

	// UnreadCounts returns the object's per-tag unread counters.
	UnreadCounts(ctx context.Context, objectId string) (map[string]int, error)

	// MarkRead covers the given changes and their causal ancestry,
	// then publishes the account's read frontier to the account's
	// other devices.
	MarkRead(ctx context.Context, objectId string, changeIds []string) error

	// MarkReadUpTo covers every unread change with VersionId <= upTo —
	// "this and everything before" in this device's display order.
	// "" reads everything. Backs Read(message) / ReadAll() sugar.
	MarkReadUpTo(ctx context.Context, objectId string, upTo crdt.VersionId) error

	// Generation is the same per-space rebuild epoch as
	// ChangeIndexAPI.Generation — cursors reset when it changes.
	Generation(ctx context.Context) (string, error)
}

type RecordDiff struct {
	Id     string
	Kind   DiffKind
	Fields []FieldDiff
}

type RecordModify struct {
	Id     string
	Upsert bool
	Ops    []Op
}

type RemoveReason uint8

type RemovedRecord struct {
	Id     string
	Reason RemoveReason
}

type Scope = handler.Scope

type SearchFields = handler.SearchFields

type Service interface {
	// Create a new regular space owned by the authenticated account.
	Create(ctx context.Context, req CreateRequest) (Space, error)

	// Join a space via an invite. Depending on the invite key mode the
	// space is either immediately active or pending approval. The
	// pending join is account-wide: the row reads StatusJoining on every
	// device of the account, none materializes the space, and the
	// device that observes the acceptance loads it and flips the row
	// active for the rest. A row left by an earlier join that ended
	// without membership (owner declined, or withdrawn via CancelJoin —
	// surfaced as StatusDeleted) is revived: the request is posted again
	// and the row returns to StatusJoining. A synced tombstone (Delete)
	// is sticky and refused with ErrSpaceDeleted before anything reaches
	// the network.
	Join(ctx context.Context, req JoinRequest) (Space, error)

	// CancelJoin withdraws this account's pending join request for
	// spaceId (a row in StatusJoining) — from any of the account's
	// devices, not only the one that requested. Nothing local is
	// materialized: the request record lives on the space's ACL chain,
	// which the nodes serve directly, so the cancel is posted through
	// the joining client the way Join posted the request. On success the
	// row flips to StatusDeleted account-wide — the same end state an
	// owner decline leaves — and a later Join with a valid invite
	// revives it. ErrSpaceUnknown for an id with no row;
	// ErrJoinNotPending when the row is not joining or the owner
	// accepted the request first (see the sentinel for what happens to
	// the row then). A request already gone from the chain with no
	// membership behind it — withdrawn or declined elsewhere before the
	// marker synced — is settled here: the row is marked ended, nil. A
	// chain that cannot be read (offline) is reported as the transport
	// error and the row is left as it is.
	CancelJoin(ctx context.Context, spaceId string) error

	// JoinGuest adds a space via a guest invite (InviteKindGuest): the
	// invite carries the shared read-only guest identity, so there is no
	// join request and no owner approval — the space is pulled and opened
	// signing as that identity. One bounded synchronous load attempt is
	// made; if the content isn't pullable yet the row is recorded
	// durably, (nil, ErrGuestJoinPending) is returned, and loading
	// finishes in the background (resumed across restarts). The space is
	// read-only for life: synced writes fail with ErrReadOnlySpace and
	// Info reports OwnRole = PermissionGuest. Remove it with Delete
	// (local drop — a guest cannot write to the ACL).
	JoinGuest(ctx context.Context, invite string) (Space, error)

	// Derive a deterministic space from the account keys. Used for
	// the tech space (never returned here) and future derived spaces.
	// Derived spaces are permanent — Delete refuses them with
	// ErrIsDerivedSpace (see the sentinel for why).
	Derive(ctx context.Context, req DeriveRequest) (Space, error)

	// DeriveId returns the deterministic spaceId for a DeriveRequest
	// without creating or loading the space. Same id as Derive(...).Id()
	// for the same request. Lets a consumer recompute a known derived
	// space's id (from its own seed) to recognize or filter it
	// client-side.
	DeriveId(ctx context.Context, req DeriveRequest) (string, error)

	// OneToOne reaches out to — or explicitly accepts / un-declines — the
	// derived 1-1 space shared with otherIdentity. Materializes and
	// activates it locally (implicit self-approval). Same id regardless of
	// key order — both peers land on the same space. Idempotent; overrides
	// a prior local decline.
	OneToOne(ctx context.Context, otherIdentity string) (Space, error)

	// AcceptOneToOne approves an incoming pending 1-1 by space id (as
	// surfaced in List with Status == StatusOneToOnePending): materializes
	// and activates it. The peer identity is read off the row, so the
	// caller needn't re-derive it. Equivalent to OneToOne(peer).
	AcceptOneToOne(ctx context.Context, spaceId string) (Space, error)

	// DeclineOneToOne rejects an incoming 1-1. Writes a synced sticky
	// marker so the request is suppressed on all the account's devices and
	// never auto-resurfaces; a later explicit OneToOne(peer) overrides it.
	DeclineOneToOne(ctx context.Context, spaceId string) error

	// RegisterIncoming records an incoming 1-1 request learned out-of-band
	// (no coordinator) as a pending row for the user to approve, without
	// materializing storage. displayHint is an optional name/icon snapshot
	// for the UI. No-op if a row for the derived space already exists.
	RegisterIncoming(ctx context.Context, peerIdentity string, displayHint AccountMetadata) error

	// AcceptInvite approves a direct-add invite (a space surfaced in List
	// with Status == StatusInvitePending or StatusInviteDeclined — the
	// account is already an ACL member; accept is a local materialization
	// gate). Flips the synced status to active (all the account's devices
	// converge) and loads the space. When the content isn't pullable yet
	// it returns ErrInviteAcceptPending and loading continues durably in
	// the background (crash/restart-safe); poll Get or Subscribe for the
	// flip. Idempotent; overrides a prior decline.
	AcceptInvite(ctx context.Context, spaceId string) (Space, error)

	// DeclineInvite rejects a direct-add invite. Writes a synced sticky
	// marker so the request is suppressed on all the account's devices; a
	// later AcceptInvite overrides it. No ACL write happens — the account
	// remains a member on the space's ACL. Nothing was materialized, so
	// nothing is removed.
	DeclineInvite(ctx context.Context, spaceId string) error

	// Get returns an already-joined space by id. Fails if the space is
	// unknown locally, with ErrSpaceNotAccepted for a known row whose
	// acceptance is still pending (joining / incoming 1-1 / direct-add
	// invite) — those must never be materialized by a read — and with
	// ErrSpaceDeleted for a deleted row. A 1-1 accepted or initiated on
	// another of the account's devices (synced remote=active) is adopted
	// transparently: Get materializes it locally, no per-device
	// re-accept needed.
	//
	// The account's own tech space id (SDK.TechSpaceId) returns a
	// restricted handle: reads, dataset declarations on bundle roots,
	// derived-only Bundles() and generic record writes work; the
	// system datasets are read-only through it and every lifecycle
	// surface (objects, types, members, ACL, files, history, …)
	// returns ErrUnsupported. It never appears in List / Subscribe.
	Get(ctx context.Context, spaceId string) (Space, error)

	// Track registers a foreign spaceId in the local space index without
	// joining it, so a later Get can open it — any-sync bootstraps the
	// space from its responsible nodes when local storage is missing.
	// The caller does not become a member and holds no keys: synced
	// content stays sealed. Idempotent; a no-op when the id is already
	// indexed (including own/joined spaces — Track never downgrades a
	// membership row).
	//
	// The broker path (headless + selective sync): Track the spaceId,
	// Get it, read the payloads index via Space.Payloads.
	Track(ctx context.Context, spaceId string) error

	// Evict closes a space without deleting anything: per-space watchers
	// stop, the in-memory store and the any-sync space are released. All
	// disk state stays — a later Get reopens the space from local
	// storage. Idempotent; evicting a space that isn't open is a no-op.
	//
	// This is close-on-demand for embedders that hold many spaces (the
	// filenode-v2 broker); Delete is the destructive sibling.
	Evict(ctx context.Context, spaceId string) error

	// List returns a point-in-time snapshot of all known spaces.
	// Mirror of the tech space's space index.
	List(ctx context.Context) ([]SpaceInfo, error)

	// SyncSpaceList forces an immediate head-sync round on the tech
	// space so spaces added or removed on other devices land in the
	// local index, instead of waiting for the periodic timer. Call it
	// before List to converge the space list on demand. Blocks until
	// the round completes.
	SyncSpaceList(ctx context.Context) error

	// WaitListSynced blocks until the tech space (the account's space
	// list) has completed a clean head-sync round with no trees parked
	// for retry — the restore-path gate before deciding "does space X
	// exist on this account" (creation-vs-restore split): after it
	// returns, List reflects the responsible node's converged view.
	// Retries rounds until ctx expires; unlike SyncSpaceList (one round,
	// error verbatim) a transiently offline node keeps it waiting rather
	// than failing.
	WaitListSynced(ctx context.Context) error

	// Delete tears down a space locally. For regular spaces this also
	// flags the space as deleted on the network; for 1-1 spaces it is
	// local-only (the space is always re-derivable). The record stays
	// in List with Status = StatusDeleted. Seed-derived spaces are
	// refused with ErrIsDerivedSpace (permanent), the tech space with
	// ErrIsTechSpace, and an id with no index row with ErrSpaceUnknown.
	// A row in StatusJoining is withdrawn (CancelJoin) rather than
	// tombstoned: the request leaves the chain and the row reads
	// StatusDeleted but stays re-joinable — a tombstone would leave the
	// request pending and the space unjoinable for this account forever.
	// If the owner accepted meanwhile, the delete proceeds as for any
	// member's space.
	Delete(ctx context.Context, spaceId string) error

	// SetSettings patches the account-private per-space client settings
	// — a free-form object on the space's tech-space row, synced across
	// the account's devices (owner-only ACL: other space members never
	// see it). Each set entry lands as its own $set at settings.<key>
	// and each unset key as a $unset, all in one change — so devices
	// editing DIFFERENT keys converge without clobbering each other;
	// the same key is per-key LWW.
	//
	// Keys are the caller's vocabulary: non-empty, dot-free (one level
	// under `settings` in v1). Values are scalars — string, bool, or
	// any numeric type (stored as float64, JSON semantics). At least
	// one set or unset entry is required; a key may not appear in both.
	// The spaceId must be known to the account (any row in List,
	// deleted included — a tombstone's settings stay editable).
	//
	// Read back via List / Get → SpaceInfo.Settings, or live via the
	// raw spaces-dataset query (Query(SpaceIndexObjectId(), "spaces"))
	// where the subtree appears under the row's `settings` field.
	SetSettings(ctx context.Context, spaceId string, set map[string]any, unset []string) error

	// SetDevice upserts THIS device's row in the account's devices
	// registry — a system dataset in the tech space, one row per device,
	// synced account-wide (SYN-165). The row id is always the local peer
	// id (SDK.PeerId()), never caller-supplied. Only non-empty fields are
	// written; each Apps entry lands per-slug (nil value removes the
	// slug), so writes touching different fields merge. At least one
	// field must be non-empty (ErrDeviceEmptyUpsert). ErrDevicePruned
	// when this device's row was deleted — the sticky tombstone
	// absorbs the write and the id can never re-register.
	//
	// Read back via ListDevices, or generically via
	// Query(SpaceIndexObjectId(), "devices").
	SetDevice(ctx context.Context, up DeviceUpsert) error

	// ClaimActive marks THIS device as the active instance of app: it
	// writes an activeClaims.<app> = {seq, at} claim on the own row
	// (seq = max existing + 1). Conflict-resolution semantics live in
	// the reader — resolve the winner with ActiveDevice, never by
	// comparing claims ad hoc. There is no un-claim: only a higher
	// claim from another device or a row deletion moves the winner.
	// ErrDevicePruned when this device's row was deleted (see
	// SetDevice).
	ClaimActive(ctx context.Context, app string) error

	// DeleteDevice prunes peerId's row — the "device doesn't exist"
	// signal that moves the active election away from it. The tombstone
	// is sticky: the peer id can never re-register (a pruned device
	// that comes back stays unlisted until it re-derives its peer
	// keys). ErrDeviceUnknown when the row doesn't exist;
	// ErrDeviceSelfDelete for the local device's own row (self-pruning
	// would permanently lock this installation out of the registry —
	// prune it from another device).
	DeleteDevice(ctx context.Context, peerId string) error

	// ListDevices returns a point-in-time snapshot of the devices
	// registry (pruned rows excluded). Feed it to ActiveDevice to
	// resolve the active instance of an app. Unavailability (tech
	// space not open yet) is an error, never an empty snapshot — an
	// election consumer must not mistake a closed service for an
	// empty registry.
	ListDevices(ctx context.Context) ([]Device, error)

	// Subscribe delivers space-list changes (added / updated / removed).
	// Returns a cancel function.
	Subscribe(cb func(SpaceListEvent)) (cancel func())

	// SpaceIndexObjectId returns the id of the tech-space index object —
	// the handle for generic Query/Subscribe over the system datasets
	// (spaces, profile, devices). Future system objects expose their own ids.
	SpaceIndexObjectId() string

	// Query builds a generic read query over a system object's dataset
	// (e.g. SpaceIndexObjectId() + "spaces"), with the same chainable
	// Filter / Sort / Limit / Snapshot / Subscribe surface as
	// Space.Query. The bespoke List / Subscribe methods are convenience
	// wrappers over this.
	Query(objectId, dataset string) Query

	// Datasets returns the JSON-Schema description of the tech-space
	// system datasets (spaces, profile, devices) — field names, value shapes, and
	// per-field class (synced / derived / local) via `x-scope`. For
	// discovery, mirroring Space.Datasets.
	Datasets() []DatasetSchema

	// Status returns a snapshot of one space's rolled-up sync state.
	// Cheap; safe to call on every render tick. Spaces unknown to
	// the SDK return SpaceSyncStatus{SpaceId: spaceId,
	// State: SyncStateUnknown}.
	Status(spaceId string) SpaceSyncStatus

	// SubscribeStatus delivers SpaceSyncStatus events whenever any
	// known space's rollup transitions. Account-wide — one cb sees
	// every space. cb runs synchronously on the dispatcher
	// goroutine; keep work small or hand off.
	SubscribeStatus(cb func(SpaceSyncStatus)) (cancel func())
}

type SetMetadataRequest struct {
	Name        *string
	Description *string
	IconCID     *string
}

type Space interface {
	// Id returns the space identifier (any-sync CID-based).
	Id() string

	// Info returns a point-in-time snapshot of space metadata.
	Info() SpaceInfo

	// Objects is the object lifecycle API (Create / Derive / Delete).
	Objects() ObjectService

	// ACL exposes the full any-sync ACL feature set: invite, accept,
	// decline, change permissions, ownership transfer, self-remove.
	ACL() ACL

	// Members returns the members-collection view.
	Members() MembersAPI

	// Types manages type objects (and, through PropertyDefsAPI, the
	// property definitions of types and collections alike).
	Types() TypesAPI

	// Collections manages collection objects — definitions with
	// properties only, which objects are filed under.
	Collections() CollectionsAPI

	// Properties reads computed property values and performs
	// base/account/device scope writes.
	Properties() PropertiesAPI

	// SyncStatus exposes per-space/object/peer status.
	SyncStatus() SyncStatusAPI

	// Changes exposes the change-index surface: a live feed and a
	// "changed since cursor N" query over the objects in this space,
	// for consumer-side incremental indexers (full-text / vector
	// search). See ChangeIndexAPI.
	Changes() ChangeIndexAPI

	// History exposes version history: list an object's changes (who
	// changed what, when), view objects/records at past versions, and
	// diff versions. See HistoryAPI and
	// docs/version-history-proposal.md.
	History() HistoryAPI

	// Payloads is the read-only view over the space's file payloads
	// index — the cleartext row fields only, readable without any
	// space key. See PayloadsView.
	Payloads() PayloadsView

	// Files is the file surface: attach content to objects, with the
	// storage tiers (inline / content-addressed + node backup) hidden.
	// See Files.
	Files() Files

	// PubSub is ephemeral space-scoped pub/sub — fire-and-forget,
	// at-most-once messages between the space's online members, never
	// persisted. See PubSubAPI.
	PubSub() PubSubAPI

	// ReadState tracks read/unread changes for datasets registered
	// with handler.Dataset.ReadTracking. Methods return
	// ErrReadTrackingDisabled when nothing in the space opted in.
	ReadState() ReadStateAPI

	// Debug returns the diagnostic surface for this space. See
	// DebugAPI — not a stable interface, intended for tooling and
	// inspection.
	Debug() DebugAPI

	// Query builds a read query against (objectId, dataset). Used for
	// per-object datasets that exist on the object's own controller —
	// e.g. a type object's `properties` (definitions) dataset.
	Query(objectId, dataset string) Query

	// QueryObjects builds a read query against the per-space `objects`
	// collection — one row per regular object in the space, holding
	// computed property values. Use this for cross-object queries
	// like "find every Movie with Title containing X".
	QueryObjects() Query

	// Aggregate builds a MongoDB-style aggregation pipeline against
	// (objectId, dataset) — the aggregation sibling of Query. The
	// pipeline is accepted in the same forms Query.Filter takes a
	// condition: a JSON string, *fastjson.Value, *anyenc.Value,
	// marshaled-anyenc []byte, or a Go value converted like a record
	// value (see Op.Value). A Go map has no key order, so a stage whose
	// key order matters ($sort over several keys) is given as JSON
	// text or *fastjson.Value. Snapshot-only. See Agg.
	Aggregate(objectId, dataset string, pipeline any) Agg

	// AggregateObjects builds an aggregation pipeline against the
	// per-space `objects` collection — the aggregation sibling of
	// QueryObjects. See Agg.
	AggregateObjects(pipeline any) Agg

	// Datasets returns the JSON-Schema description of every dataset in
	// this space — field names, value shapes, and per-field class
	// (synced / derived / local) via the `x-scope` keyword. For
	// discovery; per-type object property schemas are also available
	// through Types().
	Datasets() []DatasetSchema

	// Modify applies a write batch. Returns the VersionId, ChangeId,
	// and resolved per-record ids (auto-derived ids surface here for
	// callers who submitted records with empty Id — propId / shortId
	// convention).
	Modify(ctx context.Context, batch ModifyBatch) (ModifyResult, error)

	// ModifyMany applies multiple write batches in one logical
	// submission, with pre-validation as the atomicity boundary:
	// every batch is structurally validated up-front, and if ANY
	// validation fails NONE are written to any-sync. Otherwise
	// each batch produces its own DAG change in input order.
	//
	// All batches MUST target the same ObjectId — cross-object
	// atomicity is not supported (each object's tree signs its own
	// changes). Datasets may differ across batches; this is the
	// supported way to land properties + a user dataset together
	// in a single client submission.
	//
	// Per-op handler rejections at apply time still surface as
	// ModifyResult.Rejections, same as Modify — the apply layer is
	// per-op by design (convergent across peers regardless of
	// arrival order).
	//
	// The returned slice is aligned to input order. Validation
	// failure returns an empty slice and the joined error.
	ModifyMany(ctx context.Context, batches []ModifyBatch) ([]ModifyResult, error)

	// Delete produces sticky tombstones for the listed record ids.
	// Returned RecordIds mirror the input order.
	Delete(ctx context.Context, batch DeleteBatch) (ModifyResult, error)

	// Upsert is the generic schema-driven batch ingest: upsert by
	// record id, diff only declared-mutable fields against stored
	// values, skip identical records, one change per page. Requires an
	// id:user dataset (the caller id is the idempotency key). See
	// UpsertBatch for per-record semantics.
	Upsert(ctx context.Context, batch UpsertBatch) (UpsertResult, error)

	// SetMetadata mutates this space's display metadata (name,
	// description, icon) by writing to the per-space `spaceIndex`
	// derived object. The write is CRDT-replicated to every member;
	// each device's indexer hook mirrors the converged state into its
	// own tech-space row.
	//
	// Pointer-to-string semantics: a nil pointer means "leave
	// unchanged"; a non-nil pointer to an empty string means "set to
	// empty". This lets callers patch a single field without
	// clobbering the others.
	//
	// SpaceType is intentionally not settable — it's pinned by the
	// initial Create write on the spaceIndex object.
	//
	// v1 has no caller-side permission gate; non-writers are rejected
	// downstream by the ACL at apply time on peers.
	SetMetadata(ctx context.Context, req SetMetadataRequest) error

	// SetP2PAdvertise switches per-space p2p advertising
	// (SpaceInfo.P2PAdvertise). On republishes this device's global p2p
	// record into the space right away; off stops the heartbeat — the
	// account's other devices follow within a day, and rows already
	// written age out on the other members' devices over 30 days. Synced
	// account-wide; a read-only member can flip it, but readers never
	// write rows, so for them it changes nothing.
	SetP2PAdvertise(ctx context.Context, on bool) error

	// SpaceIndexObjectId returns the deterministic id of the in-space
	// `spaceIndex` derived object. Stable across peers and across
	// SDK reboots — same id on every member's device. Useful for
	// wrappers that want to attach a Query.Subscribe stream on the
	// spaceIndex's `objects` dataset for live UI updates.
	SpaceIndexObjectId() string

	// Bundles is the typed surface over the per-space installed-bundles
	// registry on the spaceIndex object. See BundlesAPI.
	Bundles() BundlesAPI

	// WaitIndexSynced blocks until the local view of the space's index
	// is trustworthy — the gate the restore path takes before reading
	// the bundles registry ("wait for the space index, then see what is
	// set up"). Two exits: the seeded metadata row is already projected
	// locally (immediate, no network — offline-first), or a clean
	// head-sync round completes with the sync-status rollup at Synced,
	// which also covers spaces that never seed metadata (1-1 / nameless
	// derived spaces) — there an absent index after convergence is the
	// valid answer "nothing set up yet", not a wait-forever. While
	// waiting it forces head-sync rounds; bounded only by ctx (an
	// offline device with no local index keeps waiting).
	WaitIndexSynced(ctx context.Context) error

	// SyncHeads forces an immediate head-sync (diff) round on this
	// space against its responsible nodes, instead of waiting for the
	// periodic timer. Blocks until the round completes. Use it to
	// converge on demand (e.g. tests, or a manual "sync now"); normal
	// operation does not need it — periodic and reactive sync keep the
	// space up to date on their own.
	SyncHeads(ctx context.Context) error

	// TreeHeads returns the space's current sync frontier: the head
	// change ids of every live (non-deleted) tree known locally — one
	// entry per tree, materialized trees and heads-only stubs alike
	// (under selective sync every tree head-syncs even when its
	// content is not pulled), including system trees such as settings.
	// A causal-attestation primitive for embedders: a peer holding
	// every head of another peer's entry has seen at least that peer's
	// change set for the tree. Used by the filenode-v2 broker's GC
	// gate (CheckRefs).
	TreeHeads(ctx context.Context) ([]TreeHeads, error)
}

type SpaceDebug struct {
	SpaceId string
	Peers   []PeerSyncStats
}

type SpaceInfo struct {
	Id   string
	Type string // on-wire header type (any.space, any.onetoone, …; the tech type only on the tech handle)
	// SpaceType is the app-level tag set via DeriveRequest.SpaceType,
	// read from the in-space spaceIndex. Independent of the header Type;
	// use it for client-side classification/filtering. Untagged spaces
	// carry SpaceTypeAny.
	SpaceType string
	// Author is the space owner's account identity, resolved from the
	// ACL. Best-effort: empty when the ACL is not loadable.
	//
	// For a 1-1 (SpaceTypeOneToOne) space the ACL owner is a synthetic
	// shared key nobody holds, so Author instead carries the OTHER
	// participant's account identity — the friend this 1-1 is with.
	// Available even while the space is only pending (not materialized),
	// so clients can identify and resolve the friend's profile from the
	// space list directly.
	Author      string
	Name        string
	Description string
	IconCID     string
	Status      Status
	// OwnRole is this account's ACL permission in the space, mirrored
	// from ACL state onto the tech-space row by the per-space ACL
	// mirror (same trigger model as PushKeys: one pass at space load
	// plus a kick per applied ACL record). PermissionNone until the
	// mirror first runs — notably on rows whose space was never loaded
	// by this device — so treat "none" on an active space as
	// "unknown yet", not a verdict; Space.Members().Me stays the
	// authoritative per-space read.
	//
	// For a 1-1 (SpaceTypeOneToOne) space the ACL owner is the
	// synthetic shared key, so both participants mirror the role the
	// ACL actually grants them — never PermissionOwner.
	OwnRole   Permission
	CreatedAt time.Time
	// Settings is the account-private, client-owned per-space settings
	// object: free-form keys with scalar values (string / float64 /
	// bool — numbers decode as float64, JSON semantics). Written per
	// key via Service.SetSettings; synced across the account's devices
	// through the tech space, never visible to other space members.
	// Nil when never written.
	Settings map[string]any
	// PushKeys is the space's push-notification key material, mirrored
	// from ACL state so clients can cache it and decrypt push payloads
	// while the SDK process is down (see docs/tech-space.md
	// § "Space Index"). Nil until the per-space mirror has run —
	// notably on a joiner whose access is still pending (no read key
	// yet) and on rows whose space was never loaded by this device.
	PushKeys *PushKeys
	// Derived marks a space created by the account's own
	// Service.Derive — Delete refuses it (see ErrIsDerivedSpace).
	// Always false on created / joined / tracked / 1-1 spaces.
	Derived bool
	// P2PAdvertise is the per-space p2p advertising switch (on by
	// default): while on, this account's devices publish their global p2p
	// record into the space so the other members can dial them; off
	// hides them from those members. Own devices find each other through
	// the account's discovery record either way. Synced account-wide;
	// written via Space.SetP2PAdvertise.
	P2PAdvertise bool
}

type SpaceListEvent struct {
	Added   []SpaceInfo
	Updated []SpaceInfo
	Removed []string
}

type SpaceSyncStatus struct {
	SpaceId      string
	State        SyncState
	Synced       int
	Total        int
	NetworkPeers int
	LocalPeers   int
	GlobalPeers  int
	P2P          P2PState
	LastSyncedAt time.Time
}

type Stamp = handler.Stamp

type Status uint8

type SubRecord struct {
	Id  string
	Doc *anyenc.Value
	Ops []EventOp
}

type SubscriptionEvent struct {
	VersionId crdt.VersionId
	Added     []SubRecord
	Updated   []SubRecord
	Removed   []RemovedRecord
}

type SyncState uint8

type SyncStatusAPI interface {
	// Space returns the rolled-up state for this space. Cheap; safe
	// to call on every UI render.
	Space() SpaceSyncStatus

	// Object returns the state for a specific objectId. Unknown ids
	// return ObjectSyncStatus{State: SyncStateUnknown}.
	Object(objectId string) ObjectSyncStatus

	// SubscribeObject delivers an ObjectSyncStatus event for
	// objectId on every state flip. cb runs synchronously on the
	// dispatcher goroutine — keep it small or hand off.
	SubscribeObject(objectId string, cb func(ObjectSyncStatus)) (cancel func())
}

type TouchedRecord struct {
	Dataset  string
	RecordId string
	Ops      []string
}

type TreeHeads struct {
	TreeId string
	Heads  []string
}

type TypeCreateParams struct {
	Name        string
	Description string
	IconCID     string

	// XKey is an optional stable, caller-side "programmatic" name for
	// the type (e.g. for generated client code mapping). Client-set,
	// not unique, not enforced by the SDK. Unlike Name/Description it
	// is stored in the meta-type's own namespace (`type.xkey`), so
	// only rows carrying the type marker can hold one.
	XKey string

	// Layout seeds the rendering metadata — see TypeInfo. Mutable
	// through Patch.
	Layout map[string]any

	// Hidden and Meta seed the listing flag and the consumer flag bag —
	// see TypeInfo. Both mutable through Patch.
	Hidden bool
	Meta   map[string]any
}

type TypeInfo struct {
	Id          string
	Name        string
	Description string
	IconCID     string
	// XKey is the optional caller-side "programmatic" name set at
	// Create, stored at `type.xkey` on the type object. Empty if
	// unset.
	XKey string
	// Layout is how the type's header and parts compose — a slug plus
	// config in the x-format shape ({type, config}), opaque to the
	// SDK. Lives in the meta-type's namespace (`type.layout`).
	Layout map[string]any
	// Hidden keeps the type out of default listings and pickers: a
	// client shows it only on request. A bundle root asks for it
	// (EnsureBundleRequest.Hidden) when it exists to host its bundle's
	// records rather than to be attached elsewhere; a registered type
	// declares it (handler.Type.Hidden). `type.hidden`.
	Hidden bool
	// Meta is the open bag of consumer flags on the type — one scalar
	// (string, bool, number) per single-level key, written per key so
	// concurrent writers merge. Opaque to the SDK; consumers read the
	// keys they own (an indexer's `index`, a client's tags).
	// `type.meta`.
	Meta map[string]any
	// BuiltIn marks the synthetic types — `any`, `spaceIndex`, `type`,
	// `collection` and every caller-registered type (immutable,
	// always-present). User types return false.
	BuiltIn bool
}

type TypePatch struct {
	Name        *string
	Description *string
	IconCID     *string
	Layout      map[string]any
	ClearLayout bool
	Hidden      *bool
	// Meta patches the flag bag per key: a scalar value sets the key,
	// a nil value unsets it. Keys not named are untouched, so writers
	// on different devices touching different keys merge.
	Meta map[string]any
}

type TypesAPI interface {
	PropertyDefsAPI

	List(ctx context.Context) ([]TypeInfo, error)
	Get(ctx context.Context, typeId string) (TypeInfo, error)

	// Create a new user-defined type in this space. Returns the new
	// type object's id.
	Create(ctx context.Context, params TypeCreateParams) (typeId string, err error)

	// Delete a type. Objects naming it in `any.type` keep the
	// reference (orphan), per docs §"read tolerance".
	Delete(ctx context.Context, typeId string) error

	// Patch edits a user type's display and rendering metadata: name,
	// description, icon, layout, hidden, meta. Absent fields keep
	// their value. Registered built-ins refuse (ErrTypeRegistered); a
	// collection id refuses (ErrNotAType).
	Patch(ctx context.Context, typeId string, patch TypePatch) error

	// Parts returns the type's parts with their datasets (the compiled
	// view — duplicate keys folded, orphan records dropped, invalid
	// datasets flagged).
	Parts(ctx context.Context, typeId string) ([]PartDef, error)

	// AddPart declares a part with its initial datasets in one change.
	// Returns the part's stable id. The key is pinned; the display
	// slice patches via PatchPart; datasets evolve via AddDataset /
	// RemoveDataset on the part.
	AddPart(ctx context.Context, typeId string, draft PartDraft) (partId string, err error)

	// PatchPart edits a part's mutable leaves: name, icon, pos, hidden,
	// ui (written whole), uses. The key is pinned (ErrPinnedField).
	PatchPart(ctx context.Context, typeId, partId string, patch DatasetDefPatch) error

	// RemovePart tombstones a part and every dataset declared under it.
	// Record data is NOT cleaned up (the RemoveProperty stance);
	// subsequent writes to the datasets drop once peers apply the
	// removal, and a shared dataset's removal only withdraws this
	// type's ownership of the canonical collection.
	RemovePart(ctx context.Context, typeId, partId string) error

	// Datasets returns the type's dataset definitions across every part
	// (the compiled view — orphan/invalid records folded out).
	Datasets(ctx context.Context, typeId string) ([]DatasetDef, error)

	// AddDataset declares a dataset on an existing part. The definition
	// syncs like any space data; peers register the dataset (the
	// generic schema handler for records, the module's handler
	// otherwise) as it applies. Returns the definition's stable id.
	// Behavioral parts of the declaration (key, module, shared, id
	// rule, delete gate, field kinds/flags) are pinned — remove and
	// re-add to change them; display parts patch via PatchDataset.
	AddDataset(ctx context.Context, typeId, partId string, draft DatasetDraft) (datasetDefId string, err error)

	// AddDatasetField appends a field to an existing records dataset
	// (additive evolution). Returns the field definition's id. Additive
	// fields cannot be Required — validation always runs against the
	// current schema, so a required field added later would reject the
	// dataset's own history on fresh devices. Declare required fields
	// at AddDataset. A module-served dataset refuses (ErrModuleOwned).
	AddDatasetField(ctx context.Context, typeId, datasetDefId string, draft DatasetFieldDraft) (fieldDefId string, err error)

	// RemoveDataset drops a dataset definition. Existing record data is
	// NOT cleaned up (the RemoveProperty stance); subsequent writes to
	// the dataset drop once peers apply the removal.
	RemoveDataset(ctx context.Context, typeId, datasetDefId string) error

	// RemoveDatasetField drops one field definition. Existing values
	// stay stored; subsequent writes to the field are rejected as
	// undeclared (non-dynamic datasets).
	RemoveDatasetField(ctx context.Context, typeId, fieldDefId string) error

	// PatchDataset edits a definition's mutable leaves: displayName,
	// description, name (field records' display label), search.title,
	// search.text (a field key string or a non-empty array of unique
	// keys; single-element arrays canonicalize to the bare string on
	// the wire, and clearing the mapping is Unset's job), search.scope.
	// Pinned paths are rejected up-front (ErrPinnedField); malformed
	// values on mutable search leaves return ErrInvalidFieldValue.
	PatchDataset(ctx context.Context, typeId, defId string, patch DatasetDefPatch) error

	// PatchDatasetField edits one field definition's mutable leaves:
	// name, description, x-format and every path under it. The
	// behavioral parts (key, kind, shape, scope, required, mutableBy,
	// stamp) are pinned (ErrPinnedField). Unknown fieldDefId →
	// ErrNotFound.
	PatchDatasetField(ctx context.Context, typeId, fieldDefId string, patch DatasetDefPatch) error
}

type UnreadChange struct {
	ObjectId string
	// Dataset the change applied to (a tracked dataset).
	Dataset string
	// ChangeId is the DAG change (cross-peer identity); VersionId is
	// its peer-local order key — for a record-creating change it
	// equals the record's `_ver.id`, so entries join to records with
	// no extra lookup.
	ChangeId  string
	VersionId crdt.VersionId
	AddSeq    uint64
	ApplySeq  uint64
	// RecordIds are the records the change touched; Tags the
	// classifier's labels ("message", "mention", ...).
	RecordIds []string
	Tags      []string
	// StateSeq is the feed watermark at which this entry became
	// unread.
	StateSeq uint64
}

type UpsertBatch struct {
	ObjectId string
	Dataset  string
	Records  []UpsertRecord
	// PageSize caps records per emitted change. 0 = 500.
	PageSize int
	TraceIds []string
}

type UpsertRecord struct {
	Id     string
	Fields map[string]any
}

type UpsertRejection struct {
	Index int
	Id    string
	Err   error
}

type UpsertResult struct {
	Pages      []ModifyResult
	Created    int
	Updated    int
	Skipped    int
	Rejections []UpsertRejection
}

type Variant string

type Version = string

type VersionId = crdt.VersionId