handler

type Change = crdt.Change

type ChangeCtx = crdt.ChangeCtx

type Collection struct {
	// Id is the collection identifier — a stable id the caller
	// controls. Must be non-empty and distinct from every registered
	// type and reserved id.
	Id string

	// Name / Description / IconCID are the display slice; Name falls
	// back to Id when empty.
	Name        string
	Description string
	IconCID     string

	// Properties declares the collection's property definitions for
	// the per-space `objects` namespace keyed by Id — validated on
	// write exactly like a registered type's.
	Properties []PropertyDecl

	// Hidden keeps the collection out of default listings and pickers
	// (space.CollectionInfo.Hidden).
	Hidden bool
}

type Dataset struct {
	// Name is the dataset's collection name. Required, unique across
	// the catalog; reserved names ("objects", "properties", "shortIds")
	// are rejected.
	Name string

	// DataVersion is stamped on every change emitted on this dataset and
	// is what peers gate against. Required (non-empty). Convention:
	// "<name>-v<n>" — but any opaque string unique to a (handler logic,
	// dataset) pair works. Bump the suffix when changing validation in a
	// way that must reject older writers.
	DataVersion string

	// HandlerVersion is the LOCAL version of this dataset's handler
	// logic. Bump it when a change to that logic makes rows already
	// materialized on disk wrong — a derived field that now holds a
	// different shape, a stamp computed differently. The next load of
	// each object wipes its materialized rows and replays its tree
	// through the current handlers. Zero means 1.
	//
	// This is not DataVersion. DataVersion gates PEERS: bumping it parks
	// this dataset's changes on every peer still running older code.
	// HandlerVersion never leaves the device and gates nothing — it only
	// decides whether local state has to be rebuilt.
	HandlerVersion int

	// Handler implements the dataset's lifecycle (Init / Before*).
	// Optional when Schema declares fields: a nil Handler gets the SDK's
	// generic schema handler, which enforces the declaration (required,
	// mutability, stamps, id rules, delete gates) with no bespoke code.
	// Bespoke handlers remain for cross-field rules.
	Handler Handler

	// Indexes are ensured on the dataset's collection the first time it
	// is opened. Optional. Idempotent across restarts.
	Indexes []anystore.IndexInfo

	// Schema declares this dataset's fields and their classes (synced /
	// derived / local) — the source of truth the apply path enforces and
	// consumers discover via Space.Datasets() / Service.Datasets().
	//
	// Optional for backward compatibility: a zero Schema (no Fields, not
	// Dynamic) is treated as Dynamic — a free-form synced keyspace, the
	// pre-schema behavior. Declare Fields to get apply-time enforcement
	// (undeclared fields rejected, derived fields handler-only) and a
	// meaningful discovery document; set Dynamic to keep a free-form
	// keyspace explicit.
	Schema Schema

	// ReadTracking opts the dataset into read/unread tracking: the
	// Classify callback tags each applied change, the SDK maintains
	// the per-object unread set / frontier / counters, and marking is
	// forward-only (Space read-state API). Optional; nil = untracked.
	// Fields named in RecordFlags must be declared local-scope in
	// Schema. See docs/read-tracking-proposal.md.
	ReadTracking *ReadTracking

	// SkipHistory keeps this dataset out of the version-history index:
	// no index rows are written and the dataset is invisible in
	// Space.History() listings. For chatty machine-written datasets
	// (presence-like state) whose permanent index would leak disk for
	// history nobody asks for. DAG changes still retain everything —
	// flipping the flag later just requires an index backfill. See
	// docs/version-history-proposal.md §4.4.
	SkipHistory bool

	// DisableFilteredReplay opts the dataset out of the record-scope
	// history fast path (History().RecordAt), forcing the full-object
	// slow path. Set it when the dataset's Handler reads OTHER records
	// during apply — the fast path is sound only for record-local
	// hooks. See docs/version-history-proposal.md §4.2.
	DisableFilteredReplay bool
}

type DefaultHandler = crdt.DefaultHandler

type DeletePolicy = schema.DeletePolicy

type Field = schema.Field

type FieldShape = schema.Schema

type Handler = crdt.Handler

type IdRule = schema.IdRule

type Module struct {
	// Name is the slug types name in their dataset declarations
	// ("editor", "chat"). Required; "records" is reserved.
	Name string

	// Canonical is the shared collection name ("editor_blocks"): a type
	// declaring `shared: true` for this module participates in it.
	// Empty means the module has no shared collection and every
	// instance is namespaced.
	Canonical string

	// SharedOnly refuses namespaced instances, so an object carries at
	// most one collection of the module — the invariant behind a single
	// read frontier and a single push group per object. Requires
	// Canonical.
	SharedOnly bool

	// Reserved keeps the module out of runtime declarations: a part or
	// dataset draft naming it — through TypesAPI.AddPart / AddDataset or
	// a bundle's Parts — is refused with space.ErrModuleReserved, unless
	// the Ensure call carries the space.SystemInstall option (the
	// consumer's own catalog install). Registered types may still
	// declare it statically, and a declaration that reached the DAG
	// stays valid on apply (a peer that admitted it was the consumer's
	// own install). Requires SharedOnly. The install root is also the
	// module's only carrier: a local write attaching a user type that
	// declares a reserved module to any other row is refused
	// (ErrValidationReservedCarrier) — no SystemInstall escape, the
	// consumer's install attaches the type through its root alone. A
	// registered type's static declaration stays attachable.
	Reserved bool

	// DataVersion is stamped on changes to the Canonical collection —
	// the same opaque string a Dataset carries. Namespaced instances
	// stamp the declaring type's schema state instead.
	DataVersion string

	// HandlerVersion is the LOCAL logic version of the module's handler,
	// applied to every instance: bumping it replays every collection
	// the module serves. Zero means 1. See Dataset.HandlerVersion.
	HandlerVersion int

	// Properties declares the module's namespace on the objects row —
	// values stored under `<module name>.<propId>` (a chat's unread
	// counters, its notify mode). A row may carry the namespace when one
	// of its types declares a dataset of this module; the read-tracking
	// service writes the counters there.
	Properties []PropertyDecl

	// New builds the registration for one instance: Handler (nil for
	// the generic schema handler), Schema, Indexes, ReadTracking,
	// SkipHistory, DisableFilteredReplay. Name and DataVersion on the
	// returned value are ignored — the SDK fills them from the instance.
	// The handler must be safe to share across controllers: the SDK
	// builds one per collection per catalog snapshot and reuses it,
	// exactly as it shares the generic schema handler.
	New func(ModuleInstance) Dataset
}

type ModuleInstance struct {
	TypeId     string
	Key        string
	Collection string
	Shared     bool
}

type Mutability = schema.Mutability

type Op = crdt.Op

type OpType = crdt.OpType

type Part struct {
	Key    string
	Name   string
	Icon   string
	Pos    string
	Hidden bool
	// UI is the widget descriptor — {type, config} in the x-format
	// shape, opaque to the SDK.
	UI map[string]any
	// Uses names other datasets of this type (their key) the part
	// renders without owning them.
	Uses []string
	// Datasets are the part's datasets — at least one.
	Datasets []PartDataset
}

type PartDataset struct {
	Name   string
	Module string
	Shared bool
	Key    string
}

type PropertyDecl struct {
	Id          string
	Name        string
	Description string
	Kind        PropertyKind
	Scope       Scope
	XFormat     map[string]any
}

type PropertyKind uint8

type ReadClassification = crdt.ReadClassification

type ReadClassifier = crdt.ReadClassifier

type ReadSeedMode = crdt.ReadSeedMode

type ReadTracking = crdt.ReadTracking

type RecordChange = crdt.RecordChange

type Schema = schema.Dataset

type Scope = schema.Scope

type SearchFields = schema.SearchFields

type Sink = crdt.Sink

type Stamp = schema.Stamp

type Type struct {
	// Id is the type identifier this catalog entry registers under.
	// For built-in well-known types this is the reserved id ("any",
	// "type"); for caller-defined types it should be a stable
	// identifier the caller controls. Must be non-empty.
	Id string

	// Name is the display label surfaced through the public Types
	// API. Optional — when empty, the API returns the Id as the
	// label.
	Name string

	// Description is the long-form display text. Optional.
	Description string

	// IconCID is an optional icon reference (CID into the file
	// service). Opaque to the SDK.
	IconCID string

	// Datasets is the self-contained dataset registrations this type
	// owns (zero or more). Each Dataset.Name must be unique across the
	// whole catalog (built-ins + every external Type); the SDK rejects
	// collisions at sdk.Open.
	Datasets []Dataset

	// Properties declares this type's property definitions for the
	// per-space `objects` namespace keyed by Type.Id. The SDK
	// validates writes to `{typeId}.{propId}` against these: the
	// propId must be declared here and the value's kind must match.
	//
	// Optional. A type that only owns separate datasets (e.g. an
	// editor body tree) and contributes no values to the `objects`
	// record leaves this empty. Built-in `any` / `spaceIndex` carry
	// the equivalent tables internally; external types declare theirs
	// here so the SDK can resolve and enforce their schema.
	Properties []PropertyDecl

	// Parts are the type's display units, declared statically — the
	// shape a user type declares at runtime through
	// space.TypesAPI.AddPart. Each part names one or more datasets:
	// entries of Datasets by Name, or module datasets (a shared
	// canonical collection, or a namespaced `<typeId>_<key>` instance)
	// the SDK instantiates exactly as it does for a runtime declaration
	// — the write gate, discovery ownership and the module namespace on
	// the objects row all follow. With Parts set, every entry of
	// Datasets must be named by exactly one part (sdk.Open rejects the
	// rest). Without Parts, a type with Datasets gets one implicit part
	// per dataset, keyed by the dataset name. Read back through
	// space.TypesAPI.Parts / Datasets; never mutable at runtime.
	Parts []Part

	// Hidden keeps the type out of default listings and pickers
	// (space.TypeInfo.Hidden): a client shows it only on request. For a
	// capability type an object opts into rather than a class a user
	// picks.
	Hidden bool
}

type ValidationReason string