Crate khive_changeset 

KG change-set op-list model and NDJSON-delta codec. See README.md.

Structs

ChangeSet

A staged change-set: envelope metadata plus an ordered list of operations.

CreateOp

Create a new entity or note. id is minted at stage time and is stable across however long the change-set sits before it is applied.

DeleteOp

Remove an existing entity, note, or edge. preimage captures the full prior record state at stage time — required, not optional, so a delete op without a captured preimage is unrepresentable. target_id is validated against the embedded preimage’s own record id at deserialize time; a mismatched pair is a parse error, not a silently-accepted op.

EdgePatch

weight, when present, must be finite and in [0.0, 1.0] — the same invariant LinkOp/khive_types::Link enforce, so a staged edge update can never target a weight the live graph would itself reject.

EdgePreimage

Prior value of exactly the fields an UpdateOp’s patch touches; mirrors EdgePatch the same way EntityPreimage mirrors EntityPatch. A captured weight value, when present, must satisfy the same finite/[0.0, 1.0] invariant EdgePatch/LinkOp/ khive_types::Link enforce on a live edge weight.

EntityCreateFields

EntityPatch

Absent field = unchanged. description distinguishes explicit-null (clear) from absent (unchanged) via Option<Option<String>>.

EntityPreimage

Prior value of exactly the fields an UpdateOp’s patch touches, captured at stage time. Mirrors EntityPatch’s field shape one-to-one: a populated preimage field means “the patch touches this field, and this was its value before the patch”; an absent preimage field means “the patch leaves this field unchanged.” UpdateOp’s custom Deserialize enforces that this field set exactly equals EntityPatch’s touched-field set.

Envelope

Change-set-level metadata block. Carries producer identity and model family; individual ops never reference it and stay producer-agnostic.

LinkOp

Create a new directed, typed edge. id is minted at stage time; source and target may resolve to another op’s stage-time id in the same or a different change-set.

MergeOp

Merge two entities. preimage captures both prior entities and the incident edges the merge will rewire — required, not optional, so a merge op without a captured preimage is unrepresentable. into_id / from_id are validated against preimage.into / preimage.from’s own record ids, and every incident edge is validated to actually touch one of the two merge participants, at deserialize time.

MergePreimage

NoteCreateFields

NotePatch

NotePreimage

Prior value of exactly the fields an UpdateOp’s patch touches; mirrors NotePatch the same way EntityPreimage mirrors EntityPatch. A captured salience/decay_factor value, when present, must satisfy the same finite/range invariant khive_types::Note::is_valid enforces on a live note — a prior value outside that range could never have been real.

UpdateOp

Patch an existing entity, note, or edge’s mutable fields, carrying a stage-time preimage scoped to exactly the fields the patch touches. preimage’s populated fields must equal patch’s touched fields — every field the patch sets or explicitly clears to null, and no field the patch leaves unchanged — enforced at deserialize time, the same discipline DeleteOp and MergeOp apply to their own preimages below. An UpdateOp whose preimage and patch disagree on which fields changed is unrepresentable — both the checked constructor and Deserialize enforce the same congruence validation, so there is no construction path that bypasses it.

Enums

ChangeSetError

Errors from NDJSON-delta encode/decode. No variant touches the filesystem or performs any I/O — every value here is constructed from in-memory input.

CreateTarget

The substrate a create op targets, with its own field surface.

DeletePreimage

Op

One staged mutation. Tagged internally by "op" so every NDJSON-delta line self-describes its kind without a wrapping envelope.

UpdatePatch

UpdatePreimage

The field-scoped preimage for one UpdateOp, tagged by the same target discriminant UpdatePatch uses so a preimage’s substrate is self-describing on the wire.

Constants

CURRENT_SCHEMA_VERSION

The NDJSON-delta schema version this crate currently emits and accepts.

Functions

from_ndjson

Decode NDJSON-delta text into a ChangeSet. Line 1 must parse as the envelope; every subsequent non-empty line must parse as one Op, in stage order. Rejects an envelope whose schema_version this crate does not recognize, and rejects any line carrying an unknown field (fail-loud, matching the deny_unknown_fields posture the rest of the codebase uses for configuration surfaces).

to_ndjson

Encode a ChangeSet as NDJSON-delta: the envelope as line 1, then one line per op in stage order. No filesystem access — returns an in-memory String; the caller decides what to do with it.