Enum PreparedWrite 

#[non_exhaustive]
pub enum PreparedWrite {
    Node {
        kind: String,
        body: String,
        source_id: SourceId,
        logical_id: Option<String>,
        state: InitialState,
        reason: Option<String>,
        valid_from: Option<i64>,
        valid_until: Option<i64>,
    },
    Edge {
        kind: String,
        from: String,
        to: String,
        source_id: SourceId,
        logical_id: Option<String>,
        body: Option<String>,
        t_valid: Option<i64>,
        t_invalid: Option<i64>,
        confidence: Option<f64>,
        extractor_model_id: Option<String>,
        temporal_fallback: Option<bool>,
    },
    OpStore {
        collection: String,
        record_key: String,
        schema_id: Option<String>,
        body: String,
    },
    AdminSchema {
        name: String,
        kind: String,
        schema_json: String,
        retention_json: String,
    },
}

Batch input shape for Engine::write.

Marked #[non_exhaustive] per ADR-0.6.0-prepared-write-shape; new entity variants land in 0.6.x without a major bump. Adding fields to existing variants remains a binding-coordination change.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Node

Fields

kind: String

body: String

source_id: SourceId

REQ-026 / AC-028 / AC-042 recovery seam, made structurally mandatory in 0.8.20 (R-20-E3). Was Option<String>; a None landed NULL on disk and produced a row no excise_source call could reach. See SourceId for why the fix is a type change rather than a validation check.

logical_id: Option<String>

G0 (Slice 15) — stable cross-re-ingestion identity. Some(id) makes this write a transaction-time supersession of the prior active version of (logical_id, kind) (tombstone-then-insert). None is the legacy/own-identity default: a plain insert with a NULL logical_id (NULL-safe — never collides with other NULLs).

state: InitialState

OPP-12 Phase-1 (0.8.19 Slice 5) — the create-time existence state. InitialState::Active (the Default) is the back-compat default and lands state = 'active' on disk (value-identical to the migration step-20 column DEFAULT). InitialState::Pending creates a quarantined node excluded from default retrieval. A deleted/purged node is UNREPRESENTABLE at create time (the InitialState type is the typed rejection) — those states are reachable only via the Slice-10 transition/purge verbs.

reason: Option<String>

OPP-12 Phase-1 (0.8.19 Slice 5) — advisory cause for the create-time state (e.g. the quarantine cause for a pending node), stored verbatim in canonical_nodes.reason. Engine never interprets it. None lands NULL (the back-compat default).

valid_from: Option<i64>

0.8.20 Slice 15b (TC-34) — world-time validity window, INCLUSIVE lower bound, INTEGER epoch SECONDS UTC. None lands NULL = unbounded below.

Slice 10b added the valid_from/valid_until columns, the ReadView validity predicate and Engine::crossed_boundary_since but NO writer, so a window could only be authored with raw SQL. These two fields are that writer. They are deliberately FIELDS rather than a new verb, exactly as PreparedWrite::Edge already carries t_valid/t_invalid: the governed command surface is unchanged.

The pair is validated together — see valid_until.

valid_until: Option<i64>

0.8.20 Slice 15b (TC-34) — world-time validity window, EXCLUSIVE upper bound, INTEGER epoch SECONDS UTC. None lands NULL = unbounded above.

The window is half-open [valid_from, valid_until), matching the read predicate in ReadView::validity_sql exactly. Because it is half-open, a pair with valid_from >= valid_until describes an EMPTY window that no instant can ever satisfy — so Engine::write refuses it with EngineError::WriteValidation rather than storing a row that no default read could ever return. A ONE-SIDED window is never empty and is never refused, however extreme its single bound.

BREAKING (0.8.20 Slice 22, decision #18). This refusal used to be EngineError::InvalidArgument NAMING both bounds. It is now the message-less WriteValidation unit variant — the one family the taxonomy of record assigns to a malformed submitted write SHAPE — so the offending bounds are no longer carried in the error. A caller that parsed them out must validate the pair before calling.

Edge

Fields

kind: String

from: String

to: String

source_id: SourceId

REQ-026 / AC-028 / AC-042 recovery seam — see Node. Structurally mandatory since 0.8.20 (R-20-E3).

logical_id: Option<String>

G0 (Slice 15) — see Node. Supersession semantics are identical on edges (keyed by (logical_id, kind)).

body: Option<String>

G11 (Slice 15) — the fact/relationship text. When Some, triggers FTS projection into search_index_edges and vector projection via the projection scheduler (kind "edge_fact"). Also triggers invalidate-not-accumulate on (from_id, to_id, kind).

t_valid: Option<i64>

G11 (Slice 15) — event valid-time. NULL = unknown / still valid.

TC-33 (HITL-RATIFIED 2026-07-21): INTEGER epoch seconds (UTC), not ISO-8601. This is the GOVERNED SDK WRITE SURFACE, which carries the same representation as storage. ISO-8601 survives ONLY on the BYO-LLM extractor wire (fathomdb.extract.v1), where normalize_extractor_timestamp converts it with hard rejection.

t_invalid: Option<i64>

G11 (Slice 15) — event invalid-time. NULL = still valid.

TC-33: INTEGER epoch seconds (UTC) — see t_valid. The NULL-means-still-valid semantic is load-bearing and unchanged, which is why the schema pins the type with a typeof CHECK rather than NOT NULL.

confidence: Option<f64>

G11 (Slice 15) — extraction confidence ∈ [0.0, 1.0]. NULL for non-BYO-LLM-ingested edges.

extractor_model_id: Option<String>

G11 (Slice 15) — opaque model/provider id from the BYO-LLM harness ready.model field. NULL for non-BYO-LLM edges.

temporal_fallback: Option<bool>

R3 (Slice 30, SCHEMA-GATE-1, HITL-SIGNED 2026-06-13) — set when the ELPS extractor defaulted this edge’s t_valid to created_at rather than deriving it from the document text. Such edges have untrustworthy event times and are excluded from graph-arm BFS temporal queries. None/false = not a fallback; Some(true) = fallback.

OpStore

Fields

collection: String

record_key: String

schema_id: Option<String>

body: String

AdminSchema

Fields

name: String

kind: String

schema_json: String

retention_json: String

Trait Implementations

impl Clone for PreparedWrite

fn clone(&self) -> PreparedWrite

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PreparedWrite

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for PreparedWrite

fn eq(&self, other: &PreparedWrite) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PreparedWrite