A type declares what its objects carry beyond properties as parts:
display units, each owning one or more datasets. A dataset is
served by a module: the built-in records module (a
schema-enforced dataset the client fully describes) or a compiled-in
module the embedder registers (an editor, a chat). Everything is
declarative and definable at runtime, per space, by clients. A records
schema expresses required fields, write-once vs author-mutable fields,
author-only delete, apply-time stamps, record-id rules and a
search-extraction annotation without a compiled-in handler; a module
declaration instantiates the module's compiled-in behaviour on a
collection of the type's own.
Related docs: crdt-spec.md §7–8 (apply gates,
handler registration), types-properties-proposal.md
(the property machinery this reuses), data-structure.md
(the type meta-type's datasets and rendering metadata),
bundles.md (bundle roots declaring parts).
Type
├─ properties (docs/data-structure.md)
├─ layout (rendering metadata, docs/data-structure.md)
└─ parts[] display units, keyed
├─ name/icon/pos/hidden/ui/uses
└─ datasets[] keyed; module; the declaration
- A part is what a client renders: a key (slug, pinned), the
display slice (
name,icon,pos,hidden), the widget descriptorui({type, config}, the x-format shape, written whole, opaque to the SDK) anduses, keys of other datasets of the same type the part renders without owning. - A dataset is keyed inside its type (slug, pinned) and names a
module(pinned). The key decides its collection (§ The collection rule). Arecordsdataset carries the behavioural declaration below; a module-served dataset carries none: the module owns the schema, and field declarations on it are refused (ErrModuleOwned). - A module (
handler.Module, registered viaconfig.Config.Modules) is a factory:New(ModuleInstance) handler.Datasetreturns the handler, schema, indexes, read-tracking and history flags for one collection. A module may own a canonical collection (Canonical);CanonicalOnlyrefuses namespaced instances so an object carries at most one collection of the module;NoCopykeeps its datasets out of an object copy (§ NoCopy modules). A module may also declare a namespace on the objects row (Properties); see docs/data-structure.md § Module namespaces.
A reserved module (Reserved, requires CanonicalOnly) cannot be
declared at runtime: AddPart, AddDataset and a bundle's Parts
naming it fail with space.ErrModuleReserved. Only a bundle install
made with the space.SystemInstall() ensure option, or a registered
type's static part, may declare it. The check is draft-time only:
compile keeps an applied declaration valid, since the peer that admitted
it was the consumer's own install.
The install root is the module's only carrier. A local write that sets a
user type declaring a reserved module as the type of any row other than
the type's own (Objects().Create with Type, SetType, an any.type
op through Modify) fails with handler.ErrValidationReservedCarrier
(reason reserved_carrier), so a client cannot mint a second instance
by retyping an object. SystemInstall does not bypass this. A
registered type's static declaration is not a carrier: any object may
take it as its type.
Limits:
- The guard reads this device's catalog snapshot, so a declaration not yet compiled locally is not protected.
- Inbound apply is read-tolerant: a peer that lands the type on another row is applied, and that row keeps writing (only additions are checked).
A NoCopy module keeps its datasets out of Objects().Create with
From: the copy carries the type's other datasets (an invalid
declaration's and a reserved module's are skipped as well) and starts
this module's collection empty, writable like any other. It
is for records whose author and time are the content — a chat
transcript, whose creator and createdAt come from the change
envelope — which a copy would re-attribute to the copier.
Limits:
- The flag is the copying process's own module registration, not space state: a consumer build that registers the module without it copies the records.
A registered type (config.Config.Types) declares its parts at boot
(handler.Type.Parts) in the shape of a runtime declaration. Each part
names entries of the type's Datasets (PartDataset.Name: the
collection is the dataset's name; the module reads as records on the
generic schema handler, none for a bespoke handler) or module datasets
(PartDataset.Module + Key, per the collection rule below).
- Module datasets enter the catalog as if a type object had declared
them: a canonical one adds the type to that collection's owner
set; a namespaced one registers
<typeId>_<key>on every controller with the module'sDataVersion(registered types mint no schema state to gate on). The module namespace on the objects row follows (Store.ModuleGrants), and discovery lists them underOwners = [typeId]. - Static declarations are validated at
sdk.Open(ValidateExternalTypes/ValidateExternalModules: slug keys, each static dataset named by exactly one part once parts are declared, the collection rule, minted names free) and never change at runtime:AddPartand the other definition writes returnErrTypeRegistered.Types().Parts/Datasetsreturn the compiled view with the keys as ids. - A type with
Datasetsand noPartsreads back one implicit part per dataset, keyed by the dataset name. handler.Type.Hiddenkeeps the type out of default listings (TypeInfo.Hidden).
The key decides:
key = <module canonical> → <module canonical> editor_blocks
any other key → <typeId>_<key> bafyrei…_segments
- A draft with no key takes its module's canonical name. A module
without a canonical collection,
recordsamong them, requires a key. - A
CanonicalOnlymodule admits no key but its canonical name. - The canonical collection is one name per module per space: every type that declares it addresses the same collection, so retyping an object between two such types keeps its records. A namespaced dataset belongs to its type alone: two types with namespaced editor datasets give two collections; nothing merges.
- Keys are unique within a type, so a type declares a module's canonical dataset at most once.
- The head record stores the outcome as a pinned marker (
shared), set exactly when the key is the module's canonical name. The compile resolves the collection from the marker: a stored head keyed by the canonical name without it is namespaced,<typeId>_<key>. - Namespaced names cannot collide: type ids are content-addressed CIDs
without
_, so<typeId>_<key>splits at the first_and no two types can produce the same collection. The catalog needs no first-writer resolution and bundles need no name preflight. - Keys are slugs (
[a-z][a-z0-9_]*, ≤ 64 bytes,schema.ValidateSlug): a collection segment and a wire path segment, nothing that needs quoting.
A write to a storage collection is admitted at local write time when
the object's one type declares it (the one owner of a namespaced
collection, any owner of a canonical one), or when the object is a
declaring type, which implicitly implements itself (docs/data-structure.md § Type and
collections). That is how a bundle root writes its own records
(Store.DatasetOwners, spaceImpl.checkDatasetMembership).
Collections (any.collections) declare properties only and never a
dataset. No type is set on write: a write to a storage collection the
object's type does not declare fails with
space.ErrDatasetNotDeclared. Inbound apply is read-tolerant:
canonical collections register statically on every controller
(a peer applies an inbound editor_blocks change without the
declaring type's definitions), namespaced instances go through the
catalog and park until the declaring type's schema state arrives
(below). Removing a canonical dataset withdraws that type's ownership
of the collection and nothing else.
schema.Dataset / schema.Field (re-exported through handler and
space) carry the behavioral declaration. Every zero value is the
unconstrained default.
Per field:
| Declaration | Meaning |
|---|---|
Scope |
write/sync class (synced/derived/local/account); zero = synced |
Schema |
value shape (recursive JSON-Schema subset); nil = unconstrained |
Required |
must be present in the create payload; create-only check |
MutableBy |
post-create write rule: never (zero) / author / any |
Stamp |
apply-time derived value: creator / createTime / modifyTime; forces derived scope, and the time stamps force kind datetime (the value is handler-produced, so a declared kind would only be a way to get it wrong) |
Additive |
compiler-set: not declared with the dataset (added by AddDatasetField, or by only some of, or differently by, concurrent declarations). Never required; on a Dynamic dataset synced, unstamped and mutable by anyone, its shape enforced by the local pre-flight only; see § Evolution rules |
Per dataset:
| Declaration | Meaning |
|---|---|
Dynamic |
free-form keyspace next to declared fields |
IdRule |
auto (zero: ids derived from the change, the empty-id sugar) / user (caller ids, pattern + max length constrained) |
DeleteBy |
record-delete gate: anyone (zero) / author / none (no record delete at all: the local pre-flight refuses with ErrDatasetUndeletable, apply drops one written elsewhere, so the dataset never writes a tombstone and none of its ids is burned by a delete; a key declared again after removal keeps the earlier declaration's rows, § Limitations; object deletion still purges) |
SkipHistory |
keep out of the version-history index |
Shared |
every object's records in one collection per space (§ Shared datasets); pinned |
Search |
{title, text} field mapping plus an optional scope slug (which index scope the entries land under), surfaced as x-search for external indexers; SDK-opaque. text names one or more field keys, which the indexer joins into one body; on the wire a single key is a bare string, several are an array (a single-element array marshals as the string) |
Declaration well-formedness (schema.ValidateDatasetDecl, shared by
every entry path so a bad declaration can neither register nor sync):
stamps force derived scope; at most one field per stamp kind;
Required excludes Stamp and requires synced scope; any
MutableBy: author field or DeleteBy: author requires a
Stamp: creator field (the authorship fact must live ON the record so
apply-time checks read only ctx.Before, with zero extra reads); id
constraints only under IdRule: user; a search.text mapping names at
least one field key with no empty or duplicate keys (mapped keys are
not required to be declared fields; the annotation is opaque).
crdt.SchemaHandler interprets a declaration. A handler.Dataset
with a declared Schema and Handler: nil gets one automatically:
compiled-in types, module instances that return a nil handler, and
records datasets all use the same enforcement.
The declaration compiles once at construction into a flat rule table;
the accept path of BeforeModify is one map lookup with zero
allocations, asserted by a benchmark (cold restore replays millions of
ops through these hooks).
Enforcement:
- BeforeCreate (whole-record drop): id rule; required fields
(satisfied only by whole-field content-adding ops; dotted keys
don't count); declared value shapes; stamps derived from
Change.Creator/Change.Timestampvia the sink (zero DB reads). - BeforeModify (per-op drop; multi-field ops salvage per key via
the controller's probe): mutability gate, value shapes,
modifyTimebump on accepted mutable writes. Writes descending below the declared shape (under a scalar, into an undeclared closed-object property) are rejected. - BeforeDelete: the
DeleteBy: authorgate; underDeleteBy: noneevery delete is dropped. - PreValidateMulti: the strict local mirror with caller-readable
errors (spec §7.2 disposition split); under
DeleteBy: noneit refuses a delete before the change enters the DAG.
Every verdict is arrival-order independent (the replica-determinism contract of spec §8):
- Write-once = create-only. A
MutableBy: neverfield is writable only in the record's creating change. There is no late fill: a presence-based rule ("reject iff the field already has a value") would accept/reject concurrent fills in opposite orders on different replicas. Fields that must stay settable declareMutableBy. - Author gates read the creator stamp, a derived-at-create, immutable record fact, so the verdict is identical wherever the record exists.
DeleteBy: authorrejects deletes of never-created records (no creation marker yet). Convergent because an author's own create→delete is self-causally ordered: a delete arriving before its record's create can only be a non-author's, which both orderings reject.DeleteBy: nonerejects every delete, whoever wrote it and whether or not the record exists here, so no replica ever writes a tombstone for the dataset. It reads no record fact and needs no creator stamp.- Stamps come from the change envelope, never from replica state.
- An additive field of a Dynamic dataset is free keyspace at apply time (§ Evolution rules): a declaration that arrives after a change's writes cannot change their verdict.
- Concurrent creates of one caller-supplied id are the exception: which one a replica runs as the create depends on arrival order (§ The IdRule: user contract).
Members can create one caller-supplied id concurrently (the id doubles
as the upsert idempotency key). Only the first create of an id that a
replica applies runs BeforeCreate; a later concurrent
one is screened as a modify (BeforeModify, per key). The ops merge
per field through gating and _ver.id takes the minimum creating
version (spec §3.3, §3.5). The first-applied create decides, so these
depend on arrival order:
- Write-once fields (
MutableBy: never, the zero value): only the first-applied create sets them; the other's writes to them are rejected. - Stamps (
creator,createTime,modifyTime): taken from the first-applied create's envelope. - Author gates (
MutableBy: author,DeleteBy: author): they read that creator stamp.
A dataset that declares none of these converges on concurrent creates of one id by different members, in every delivery order: one record, merged per field. A dataset that declares any of them needs one writer per id: one ingest writer per dataset (or per id range).
Required and value shapes screen the first-applied create whole and
a later one per key, so a create that fails them diverges too. The
local pre-flight refuses such a create; only a writer that skips it
produces one.
The type meta-type owns a third built-in dataset, datasets (next to
properties and shortIds), registered compiled-in like any other. A
type's parts are CRDT records there:
- Part record (one per part; id minted client-side, unique):
def:"part",key(slug, pinned);name,icon,pos,hidden,ui(an object, created whole) anduses(an array of dataset keys) mutable. - Head record (one per dataset; id minted client-side, unique):
def:"dataset",key(slug),module,shared(the canonical marker),perSpace(a shared dataset),part(the owning part record id),dynamic,idRule/idPattern/idMaxLen,deleteBy,skipHistory, all pinned first-write;displayName,description, and thesearch.title/search.text/search.scopeleaves stay mutable (leaves mutate, a broadsearchreplace is pinned).title/scopeare scalar strings;textis a bare field key or a non-empty array of unique keys. The head carries nocollection: the collection is computed at compile from the collection rule. - Field record (one per field of a
recordsdataset; id derived from the change):def:"field",dataset(owning head id),key,kind,scope,stamp,required,mutableBy,items/propertiesare pinned;name,descriptionand the opaquex-formatdescriptor (every path under it, any value; the same bag a property definition carries, docs/data-structure.md § "Thex-formatdescriptor") mutable viaPatchDatasetField. The descriptive slice never enters the schema revision: editing it re-registers nothing. - Index record (one per declared index of a
recordsdataset; id derived from the change):def:"index",dataset(owning head id),key(slug),fields(an array of paths),sparse, all pinned. See § Declared indexes.
A bundle root that declares Parts is a type object (any.type = "__type__", typeId == objectId) and hosts these records itself under
the implicit self grant; they evolve through Types().AddPart /
AddDataset / AddDatasetField / PatchDataset / PatchDatasetField
with typeId = rootId. See bundles.md § Bundle-declared definitions.
One record per definition makes concurrent edits merge: creates are
stateless-accepted records, pinning is stateless per path, and distinct
adds converge as distinct records, as in the properties dataset.
Cross-record consistency (orphans, author rules without a creator stamp,
the collection rule, module existence) is resolved at catalog compile,
never in hooks: hooks that read sibling
records would take arrival-order-dependent verdicts, and a handler
cannot see the module catalog (a peer without a module still stores
the declaration).
AddPart writes the part, its heads, their fields and their indexes in
one change (the ids are minted client-side so records can reference
each other), so a crash can never strand an orphan. AddDataset on an
existing part writes the head, its fields and its indexes the same way.
Every part, head and field create, and every definition delete,
projects a shortId row into the type's <typeId>_shortIds collection
(with a src: "datasets" discriminator), so the DataVersion gate
covers dataset-schema state with no extra lookups. An index record's
creation projects none: an index changes no apply verdict, so no data
change waits for one. An SDK that predates index records drops them at
apply and holds no index until its type object is next rebuilt; its
reads stay correct.
types.CompileTypeParts folds a type's records in one storage pass,
deterministically on converged records (CompileDatasetDefs is the
flat dataset view of the same fold):
- tombstoned records are skipped;
- duplicate part keys fold into one: the display slice from the
smallest creation
_ver.id, datasets andusesunioned; - a head whose part is absent, or a field whose head is absent, is an orphan and is skipped;
- duplicate dataset keys name the same collection by construction:
the smallest creation
_ver.idis the definition's identity and display, fields union by key across every head (smallest_ver.idper key), and a disagreement on a pinned leaf marks the definition invalid. This is sound within one tree: orderId values are peer-local but their relative order converges; - the collection rule decides the collection from the head's canonical
marker; an unknown module or a rule violation marks the definition
invalid; a type holding two canonical datasets of one module keeps
the smallest
_ver.idand marks the rest invalid; - a module-served dataset carries no fields and no delete policy: field and index records under it are orphans;
- index records attach to their head like fields and dedup by index
key (smallest
_ver.id); one whose paths are not declared scalar fields of the folded declaration, or that is past the per-dataset limit in creation order, is emitted invalid and never built; - a
recordsfold that failsValidateDatasetDeclis emitted invalid, visible throughTypes().Datasets(with the reason) so it can be repaired or removed, but never registered.
Validation runs against the current compiled schema, so evolution is additive-only with pinned behavior, and a declaration that rows may predate is enforced on this device's writes only:
- Add parts, datasets and fields freely at runtime; edits sync and apply like any space data.
- A part's key; a dataset's key, module, canonical marker and part; a
field's
kind,scope,stamp,required,mutableBy; the id rule and the delete gate are pinned for the life of the definition; remove and re-add under a new key to change them. A dataset never moves between parts. - Additive fields cannot be
Required. Fresh devices replay the dataset's own history against the current schema; a required field added later would reject every historical create. Required fields exist only fromAddPart/AddDataset. RemoveDatasetFieldre-validates the remaining declaration and refuses removals that would invalidate it (e.g. the creator stamp of an author-gated dataset). Already-invalid definitions stay removable. A field a valid declared index names is refused until the index is removed.- A field not declared with its dataset is additive — added by
AddDatasetField, or declared by only some of the dataset's concurrent declarations, or differently by them. Rows may already hold the key, and a change written before the declaration is valid under the schema its writer had, so an additive field is never required, and on a Dynamic dataset it is synced, unstamped and mutable by anyone whatever its draft says (AddDatasetFieldrefuses a draft asking for more there): the apply path keeps treating the key as free keyspace (no shape check, nomodifyTimebump), every replica keeps such a change whether the declaration or the change arrived first, and the local pre-flight enforces the shape on this device's writes. Discovery renders the field withx-additive. A non-Dynamic dataset rejects undeclared keys at write time, so its additive fields keep their shape, scope, stamp and mutability; two concurrent declarations of one of its fields that disagree are converged by the earlier one, and records written under the other may be rejected. - An index is replaced, never edited:
RemoveDatasetIndex, thenAddDatasetIndex. A removal takes every concurrent declaration of the key with it. RemoveDataset/RemovePartdo not clean up record data (as withRemoveProperty); subsequent writes drop once peers apply the removal, and a canonical dataset's removal only withdraws this type's ownership.
Controllers' handler maps stay immutable after construction; runtime declarations reach them through a store-level catalog:
- The catalog is a copy-on-write snapshot (
atomic.Pointer), built once at store open (one indexed scan of live__type__rows + one compile per type object) and refreshed only when adatasetschange applies. Controller construction reads it with one atomic load, with no storage scans or declaration compiles (registrations are pre-built per snapshot and shared; handlers are read-only after construction). A namespaced dataset gets one registration: the generic schema handler over its declaration forrecords, the module'sNew(instance)output otherwise, with the module'sHandlerVersioncomposed in. A canonical dataset adds its type to that collection's owner set and registers nothing; the canonical collection is on every controller from store open, with the module'sDataVersion. - Eviction is lazy. Schema apply evicts nothing. Each registration carries a
SchemaRevfingerprint of its compiled declaration (for a module instance: the module and key, since the schema is the module's; for a per-object records dataset: its declared indexes too); a resident controller whose rev differs from the catalog's (dataset added, field added/removed, index added/removed, definition removed) is stale. Local touch (Modify/Upsert/Query) drops and reloads it; user-facing write paths retry once on the resultingobject.ErrClosed, so the eviction never surfaces as a caller error. - Inbound: the apply gate parks a change whose dataset this
controller doesn't currently carry (unknown or stale rev) into the
_detachedcollection (spec §8.2 persist-but-skip). When the definition applies, the catalog refreshes and the drainer wakes; the drain evicts exactly the parked objects' stale controllers before replaying. Rows whose dataset is still unregistered are skipped before the payload decode. Stale-rev parks with no missing shortId pairs nudge the drainer at park time: the schema may already be fully applied, and nothing else would wake it.
Changes on a namespaced dataset stamp typeId:latestShortId: the
declaring type's whole schema state (properties, parts and dataset
definitions share one shortId stream). A peer that hasn't applied the
writer's schema state parks the data change until it has, so the
detached-changes machinery handles schema and data arriving in either
order.
Changes on a module's canonical collection stamp the module's opaque
DataVersion, like compiled-in datasets. The gate lets opaque strings
through: one declaring type's state is the wrong gate for a collection
several types own. Definition writes stamp the hardcoded
typeDatasetHandler-v1 and are never gated on their own state.
Space.Upsert(UpsertBatch) is the schema-driven ingest endpoint for
any IdRule: user dataset:
- per page (default 500 records): one
$inquery for current values, in-memory structural diff, one DAG change; - absent → create (screened client-side by the same rules the handler enforces: per-record rejections, never a page abort);
- present → diff declared-mutable fields only; identical records
skipped; a differing write-once field rejects the record
(
ErrImmutableFieldChanged; a silent skip would hide data loss); author-mutable fields pre-checked against the local identity; - modifies emit single-path
$setper changed field (per-op handler granularity); - apply-time rejections fold into
UpsertResult.Rejections; counters advance only after the page write commits; - re-running the same batch is a no-op (all skipped, no changes).
Not transactional against concurrent writers: the read-diff-write window resolves by per-path LWW; the deployment model is one ingest writer per dataset (see the IdRule contract above).
Space.Datasets() lists every collection the store hosts. Each
DatasetSchema carries Owners, the declaring types: one for a
registered-type or namespaced dataset, every type declaring it
for a canonical collection (empty while nothing declares it), none for
space-level built-ins; plus Module, Shared and the declared
Indexes that are built. Consumer indexers
gate on Owners (an object may hold the dataset when it carries one
of them).
The JSON Schema document carries the behavioral keywords:
standard required, per-field x-mutable-by / x-stamp / x-additive,
dataset-level x-delete-by, x-id / x-id-pattern / x-id-max-length,
and x-search {title, text, scope} (text: a field key or an array of
keys; a single key marshals as the bare string). Defaults are omitted.
Each field node also carries its descriptive slice when set: standard
description and the opaque x-format bag, verbatim. Compiled-in
datasets carry the same: a handler.Field declares Description /
XFormat, and every SDK-declared dataset (tech space, bundles,
payloads, the objects row's derived root fields) has a description
on each field and a descriptor where one fits (docs/data-structure.md § The x-format
descriptor).
Types().Parts(typeId) and Types().Datasets(typeId) return the
management views: definition ids, invalid state, display fields, the
computed Collection, the full value shape, the descriptor.
A records dataset declared Shared keeps the records of every object
that holds it in one any-store collection per space,
<spaceId>_<typeId>_<key>, where a per-object dataset uses one
collection per object. Nothing else moves: a record is written on an
object, through that object's tree, and belongs to that object alone.
Version ids order changes within one tree, so no record is ever
written by two objects.
<spaceId>_<typeId>_<key>
id "<objectId>/<recordId>" primary key
_objectId "<objectId>" stamped by the Controller
<fields…>, _ver, _traces?, _deletedAt?, _addSeq, _applySeq
- The record id inside a change is the plain id the dataset's
IdRuleproduces, so a peer on an SDK without shared datasets applies the same changes to a per-object collection. The stored document id is the object's prefix plus that id, whatever the id holds; an object id holds no/, so the first one splits. - Reads return the stored id:
Space.Query(objectId, dataset)reads the object's rows — a range of the primary key — each withid = <objectId>/<recordId>and_objectId. Subscription events,ModifyResult.RecordIds, rejections and version history carry the same id. - Writes take the plain record id, or the stored id of the batch's
own object. A
/anywhere else isErrRecordIdOfAnotherObject— a failed call onModifyandDelete, a per-record rejection onUpsert.Upsertis keyed by the plain id: a rejection names it, and each page'sRecordIdsare stored ids like any write result's. - Handlers see the record id the change carries.
space.SharedRecordId/space.PlainRecordIdconvert between the two forms.- Object deletion and re-index delete the object's key range from the collection; deleting the space drops the collection.
_objectIdis reserved like every_field: input ops cannot write it.
Space.QueryDataset(dataset) and Space.AggregateDataset(dataset, pipeline) read the whole collection: every object's records, with the
same builders and terminals as Query and Aggregate.
- No object is loaded. The read sees the space's materialized
state, as
QueryObjectsdoes.Query(objectId, dataset)loads its object first and stays the read for one known object: it reads the object's key range, where a filter on_objectIdhere scans the collection unless a declared index leads with it. Subscribedelivers the changes of every object's records. Deleting an object arrives as removals of its rows, with noVersionId. A subscription without a filter or a sorted limit holds the whole collection in memory.- A dataset that is not shared, or that the space does not hold,
fails the terminal call with
ErrDatasetNotShared. - Version ids order one object's changes. Rows of different objects
are not ordered by
_ver;_applySeqorders them as this device applied them.
The marker is stored on the head record as perSpace. An SDK that
predates it ignores the leaf and materializes the dataset per object.
A records dataset declares secondary indexes: DatasetDraft.Indexes
at creation, Types().AddDatasetIndex later — also on a dataset that
holds records. An index is an ordered list of paths any-store keeps
sorted, so a filter or sort on a leading run of them is a range read.
IndexDraft{Key: "by_start", Fields: []string{"start", "_objectId"}}
IndexDraft{Key: "top", Fields: []string{"-score"}, Sparse: true}- Paths: one to
MaxIndexFields(4), each a declared field of kind string, number, boolean or datetime, or_ver.id(creation order within one object); a shared dataset also takes_objectId. A-prefix keeps a path descending. An indexed field's key is letters, digits and_, starts with a letter and is at most 48 bytes, so every index has a valid store name of its own. - Values of another type still index. A synced write is checked against the declared shape; a local-scope value, a value a dynamic dataset held before the field was declared, and any value of a dynamic dataset's additive field, are not. any-store orders keys by type, so reads stay correct.
Sparseleaves a record out unless it carries every indexed field.- Limits:
MaxDatasetIndexes(8) per dataset; every index is written on every record write. No unique index — replicas cannot enforce one convergently — and no full-text or vector index. - Definitions sync, so every device holds the same set. They stay out of the DataVersion gate.
- The any-store index is named from what it indexes
(
dx_start,_objectId), not from the key: two definitions of one shape are one index, and a replaced definition is another index. - A per-object dataset carries its indexes on its registration: an object's collection gets them when it is next opened, and loses a removed one the same way.
- A shared dataset has one collection per space, which the store
indexes: when a definition applies, and at open when an index is
missing, a background worker builds it; a removed definition drops
it. While a type object replays, its datasets wait for the replay to
end. A build scans the collection in one write transaction, so every
write to the account's database waits for it. It never runs on the
apply path, and
Closewaits for one in flight.Types().SubscribeIndexBuildsreports each build (Started, thenDoneorFailed), a build in flight to a new subscriber too; a definition whose index the collection already holds builds nothing. Until a build ends, reads scan. - An invalid index — a path that names no declared scalar field —
is listed by
Types().Datasetswith its reason and built nowhere.
- A shared dataset is declared shared. The flag is pinned. Removing a dataset and declaring its key again in the other mode leaves the records a device already materialized where they were. Declaring a removed key again is a new declaration: the earlier one's records stay, and its changes that reach a device only afterwards are checked against the new one.
- Rows of a shared dataset are purged best-effort. An object's
rows are deleted from the shared datasets the catalog knows and the
ones the store has opened. Rows of a dataset whose definition was
removed before the store opened stay, as record data does after
RemoveDataset; so do rows of a purge that failed part way, until the space's deletions are reconciled again. - A shared dataset declared concurrently in both modes follows the earlier declaration. An SDK that predates the marker reads neither.
- No computed fields. Apply hooks must be replica-deterministic; a user-facing expression form is a versioned-determinism problem. Stamps cover the security-relevant derivations; other derivation hooks stay built-in-only.
- Deep shape/size validation is garbage-tolerant per spec §7.2: declared value shapes are enforced, byte caps and exotic layouts are a consumer concern.
SkipHistoryon a dataset defined after the history index opened applies from the next index open.- A declaration change refreshes the registration (SchemaRev) but never
rebuilds stored rows. Rows rebuild only when a registration's handler
version changes (the generic schema handler's version or a module's
HandlerVersion), through the lazy per-object re-index on load. - A module's
CanonicalOnlyis the only per-object cardinality rule: a type declaring two namespaced datasets of one module gives its objects two storage collections of it.
// definitions (space.TypesAPI)
Patch(ctx, typeId, TypePatch) error // name/description/icon/layout/hidden/meta
Parts(ctx, typeId) ([]PartDef, error)
AddPart(ctx, typeId, PartDraft) (partId, error) // part + datasets + fields + indexes, one change
PatchPart(ctx, typeId, partId, DatasetDefPatch) error // display slice, ui (whole), uses
RemovePart(ctx, typeId, partId) error // part + its datasets
AddDataset(ctx, typeId, partId, DatasetDraft) (datasetDefId, error)
AddDatasetField(ctx, typeId, datasetDefId, DatasetFieldDraft) (fieldDefId, error) // records only
RemoveDataset(ctx, typeId, datasetDefId) error
RemoveDatasetField(ctx, typeId, fieldDefId) error
AddDatasetIndex(ctx, typeId, datasetDefId, IndexDraft) (indexDefId, error) // records only
RemoveDatasetIndex(ctx, typeId, indexDefId) error
SubscribeIndexBuilds(cb func(IndexBuild)) (cancel func()) // shared datasets
PatchDataset(ctx, typeId, defId, DatasetDefPatch) error // mutable leaves
PatchDatasetField(ctx, typeId, fieldDefId, DatasetDefPatch) error
Datasets(ctx, typeId) ([]DatasetDef, error) // flat, with Collection
// modules (config.Config.Modules)
handler.Module{Name, Canonical, CanonicalOnly, Reserved, NoCopy, DataVersion, HandlerVersion, Properties, New}
// static parts (config.Config.Types)
handler.Type{…, Parts: []handler.Part{{Key, Name, Icon, Pos, Hidden, UI, Uses,
Datasets: []handler.PartDataset{{Name} | {Module, Key}}}}, Hidden}
// bundles declaring a definition (space.EnsureBundleRequest)
EnsureBundleRequest{…, XKey, Parts, Properties /* XKey required, deterministic ids */, Layout, Hidden}
EnsureBundleRequest{…, Collection: true, XKey, Properties, Hidden} // Parts/Layout refused with it
Bundles().Ensure(ctx, req, space.SystemInstall()) // the consumer's own install: may name a reserved module
// data (space.Space), next to Modify/Query
Upsert(ctx, UpsertBatch) (UpsertResult, error)
QueryDataset(dataset) Query // a shared dataset, every object's records
AggregateDataset(dataset, pipeline) Agg