An object is the stable unit of knowledge in Kival. It keeps the same identity as its content changes, allowing relationships, access, discussions, and history to remain associated with the same thing over time.
The editable content of an object is stored in versions. Each version is an immutable snapshot containing a title, body, metadata, author, creation time, and a monotonically increasing version number. The object points to one of those versions as its current state.
Stable identity, changing content
Creating an object creates both its stable identity and its first version. Later edits do not replace that object or mutate an existing version. When the title, body, or metadata changes, Kival appends a new version and makes it current.
This separation means links and other state can continue to refer to the object itself rather than to one particular snapshot of its content.
Historical versions remain readable independently of the current version. They can be addressed by their immutable version ID or by their version number within the object.
What belongs to a version
A version contains three pieces of user-authored content:
Title: the name of the object at that point in its history.
Body: the object's textual content.
Metadata: a compact set of structured attributes associated with that version.
Metadata must be a flat JSON object. Values can be JSON scalars or one-dimensional arrays of scalars; nested objects and nested arrays are intentionally not part of the metadata model. This keeps metadata useful for attributes without turning it into a second document structure.
Because all three fields are versioned together, changing only the title or metadata still represents a new state of the object.
Updating an object
Updates are based on the version the editor originally read. Kival checks that the expected current version is still current before publishing the change. If another edit has already moved the object forward, the update is rejected as a conflict rather than silently overwriting newer work.
Fields omitted from an update inherit their values from the current version. If the resulting title, body, and metadata are identical to the current version, Kival treats the update as a no-op and does not append another version.
A successful content change therefore produces one new immutable version and advances the object's current-version pointer to it.
Versions are append-only
Published versions are not edited or deleted. Corrections are represented by later versions instead.
This gives Kival a durable content history: the current object can continue developing while earlier states remain available for inspection and provenance.
Version history records who created each version and when. Later changes to a user's account or current access do not rewrite that historical authorship.
Object lifecycle is separate
Objects can be active or archived. Archiving changes the lifecycle state of the stable object; it does not create a content version or remove the versions that already exist.
An archived object cannot be edited as an active object. Restoring it returns the same object, with the same identity and version history, to the active lifecycle.
Keeping lifecycle separate from content history allows Kival to distinguish what the object contained from whether the object is currently active.
Why the distinction matters
An object is not just its latest document body. It is the durable identity around which Kival can accumulate versions, relationships, references, access, discussions, attachments, and events.
Versions capture how the object's authored content changes. The object gives that changing content continuity.