1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
//! Schema-definition accessors on `DirGraph` — set/get/clear the declared
//! `SchemaDefinition` and resolve a node type's declared PRIMARY KEY. Split
//! out of `mod.rs` to keep it under the god-file LoC ceiling; these are a
//! small, cohesive group with no other dependencies.
use std::collections::HashMap;
use super::DirGraph;
use crate::datatypes::values::Value;
use crate::graph::schema::SchemaDefinition;
impl DirGraph {
/// Run one write with caller-supplied freshness provenance, restoring the
/// prior context after the callback returns (including `Result::Err`).
/// This is shared by Cypher execution and direct bulk mutation bindings;
/// nested scopes restore their caller rather than clearing it.
pub fn with_write_provenance<R>(
&mut self,
git_sha: Option<&str>,
modified_by: Option<&str>,
write: impl FnOnce(&mut Self) -> R,
) -> R {
let previous_git_sha =
std::mem::replace(&mut self.active_git_sha, git_sha.map(str::to_string));
let previous_modified_by = std::mem::replace(
&mut self.active_modified_by,
modified_by.map(str::to_string),
);
let result = write(self);
self.active_git_sha = previous_git_sha;
self.active_modified_by = previous_modified_by;
result
}
/// Set the schema definition for this graph
pub fn set_schema(&mut self, schema: SchemaDefinition) {
self.schema_definition = Some(schema);
}
/// Get the schema definition if one is set
pub fn get_schema(&self) -> Option<&SchemaDefinition> {
self.schema_definition.as_ref()
}
/// Clear the schema definition
pub fn clear_schema(&mut self) {
self.schema_definition = None;
}
/// The declared PRIMARY KEY property for `node_type`, if one is set via
/// `define_schema`. `Some("id")` means uniqueness on the type's identity
/// key is enforced at the write path (CREATE rejects a duplicate); `None`
/// means the permissive default. Single source of truth for the
/// enforcement check and for introspection, so they never diverge.
pub fn primary_key_for(&self, node_type: &str) -> Option<&str> {
self.schema_definition
.as_ref()?
.node_schemas
.get(node_type)?
.primary_key
.as_deref()
}
/// Set the free-text instructions/briefing rendered verbatim at the top of
/// `describe()`. `channel` selects an audience slot; `None` = the default
/// (the only one the v1 surface uses). Empty text clears the slot.
pub fn set_instructions(&mut self, text: &str, channel: Option<&str>) {
let key = channel.unwrap_or("").to_string();
if text.is_empty() {
self.graph_instructions.remove(&key);
} else {
self.graph_instructions.insert(key, text.to_string());
}
}
/// The declared ownership layer (`"managed"`/`"runtime"`) for `node_type`,
/// if set via `define_schema`. Drives the managed-reload guard.
pub fn layer_for(&self, node_type: &str) -> Option<&str> {
self.schema_definition
.as_ref()?
.node_schemas
.get(node_type)?
.layer
.as_deref()
}
/// Whether `node_type` opted into freshness auto-stamping via
/// `define_schema({..., auto_timestamp: True})`. Drives the `updated_at` /
/// `git_sha` provenance stamp on writes. `false` (the default) keeps writes
/// deterministic.
pub fn auto_timestamp_for(&self, node_type: &str) -> bool {
self.schema_definition
.as_ref()
.and_then(|s| s.node_schemas.get(node_type))
.and_then(|n| n.auto_timestamp)
.unwrap_or(false)
}
/// Whether `conn_type` (an edge/connection type) opted into
/// `auto_timestamp`. The edge sibling of [`Self::auto_timestamp_for`].
pub fn auto_timestamp_for_connection(&self, conn_type: &str) -> bool {
self.schema_definition
.as_ref()
.and_then(|s| s.connection_schemas.get(conn_type))
.and_then(|c| c.auto_timestamp)
.unwrap_or(false)
}
/// The reserved provenance properties to stamp on a write: `updated_at`
/// (wall-clock now, a `Timestamp` matching `datetime()`) plus the
/// caller-supplied `git_sha`/`modified_by` when set on the current mutation
/// (via `ExecuteOptions` or [`Self::with_write_provenance`]). One clock read
/// per call. Engine owns these keys — callers overwrite any user value.
pub(crate) fn provenance_props(&self) -> Vec<(&'static str, Value)> {
let mut v = Vec::with_capacity(3);
v.push((
"updated_at",
Value::Timestamp(chrono::Local::now().naive_local()),
));
if let Some(sha) = &self.active_git_sha {
v.push(("git_sha", Value::String(sha.clone())));
}
if let Some(mb) = &self.active_modified_by {
v.push(("modified_by", Value::String(mb.clone())));
}
v
}
/// Inject the freshness-provenance properties into `props` when `node_type`
/// opted into `auto_timestamp`. A no-op (one bool check, no clock read) for
/// types that didn't opt in — so writes stay deterministic by default.
/// Shared by the create path (`insert_node_routed`) and the SET path.
pub(crate) fn inject_provenance(&self, node_type: &str, props: &mut HashMap<String, Value>) {
if !self.auto_timestamp_for(node_type) {
return;
}
for (k, v) in self.provenance_props() {
props.insert(k.to_string(), v);
}
}
/// Edge sibling of [`Self::inject_provenance`]: stamp the reserved
/// provenance keys into an edge's property map when `conn_type` opted in
/// (engine owns the keys — replaces any user value).
pub(crate) fn inject_edge_provenance(
&self,
conn_type: &str,
props: &mut HashMap<String, Value>,
) {
if !self.auto_timestamp_for_connection(conn_type) {
return;
}
for (k, v) in self.provenance_props() {
props.insert(k.to_string(), v);
}
}
/// The instructions for `channel`, falling back to the default slot.
pub fn get_instructions(&self, channel: Option<&str>) -> Option<&str> {
self.graph_instructions
.get(channel.unwrap_or(""))
.or_else(|| self.graph_instructions.get(""))
.map(String::as_str)
}
}
#[cfg(test)]
mod provenance_scope_tests {
use super::*;
#[test]
fn nested_scope_restores_prior_context_after_error() {
let mut graph = DirGraph::new();
graph.active_git_sha = Some("outer".to_string());
graph.active_modified_by = Some("owner".to_string());
let result: Result<(), &str> =
graph.with_write_provenance(Some("inner"), Some("worker"), |graph| {
assert_eq!(graph.active_git_sha.as_deref(), Some("inner"));
assert_eq!(graph.active_modified_by.as_deref(), Some("worker"));
Err("failed")
});
assert_eq!(result, Err("failed"));
assert_eq!(graph.active_git_sha.as_deref(), Some("outer"));
assert_eq!(graph.active_modified_by.as_deref(), Some("owner"));
}
}