@@ -10,6 +10,7 @@
1010// without benefit since they are never called from safe Rust.
1111#![allow(clippy::not_unsafe_ptr_arg_deref)]
1212
13+pub mod db_dump;
1314pub mod log;
1415mod tui;
1516
@@ -1077,11 +1078,13 @@ impl Arena {
10771078 Value::Function(f) => {
10781079 let ne = self.promote_value(f.env);
10791080 if ne != f.env {
1081+ unsafe { code_handle_retain(f.code) };
10801082 self.alloc_pinned(Value::Function(Box::new(FunctionInner {
10811083 fn_ptr: f.fn_ptr,
10821084 env: ne,
10831085 source: f.source.clone(),
10841086 extract_source: f.extract_source.clone(),
1087+ code: f.code,
10851088 })))
10861089 } else {
10871090 val
@@ -1090,10 +1093,12 @@ impl Arena {
10901093 Value::IO(io) => {
10911094 let ne = self.promote_value(io.env);
10921095 if ne != io.env {
1096+ unsafe { code_handle_retain(io.code) };
10931097 self.alloc_pinned(Value::IO(Box::new(IOInner {
10941098 fn_ptr: io.fn_ptr,
10951099 env: ne,
10961100 source: io.source.clone(),
1101+ code: io.code,
10971102 })))
10981103 } else {
10991104 val
@@ -1220,17 +1225,25 @@ impl Arena {
12201225 Value::Constructor(tag, inner) => {
12211226 Value::Constructor(tag.clone(), self.promote_value(*inner))
12221227 }
1223− Value::Function(f) => Value::Function(Box::new(FunctionInner {
1224− fn_ptr: f.fn_ptr,
1225− env: self.promote_value(f.env),
1226− source: f.source.clone(),
1227− extract_source: f.extract_source.clone(),
1228− })),
1229− Value::IO(io) => Value::IO(Box::new(IOInner {
1230− fn_ptr: io.fn_ptr,
1231− env: self.promote_value(io.env),
1232− source: io.source.clone(),
1233− })),
1228+ Value::Function(f) => {
1229+ unsafe { code_handle_retain(f.code) };
1230+ Value::Function(Box::new(FunctionInner {
1231+ fn_ptr: f.fn_ptr,
1232+ env: self.promote_value(f.env),
1233+ source: f.source.clone(),
1234+ extract_source: f.extract_source.clone(),
1235+ code: f.code,
1236+ }))
1237+ }
1238+ Value::IO(io) => {
1239+ unsafe { code_handle_retain(io.code) };
1240+ Value::IO(Box::new(IOInner {
1241+ fn_ptr: io.fn_ptr,
1242+ env: self.promote_value(io.env),
1243+ source: io.source.clone(),
1244+ code: io.code,
1245+ }))
1246+ }
12341247 Value::Pair(a, b) => Value::Pair(self.promote_value(*a), self.promote_value(*b)),
12351248 };
12361249 self.alloc_pinned(cloned)
@@ -1304,17 +1317,25 @@ impl Arena {
13041317 Value::Constructor(tag, inner) => {
13051318 Value::Constructor(tag.clone(), self.clone_from_child(*inner, child))
13061319 }
1307− Value::Function(f) => Value::Function(Box::new(FunctionInner {
1308− fn_ptr: f.fn_ptr,
1309− env: self.clone_from_child(f.env, child),
1310− source: f.source.clone(),
1311− extract_source: f.extract_source.clone(),
1312− })),
1313− Value::IO(io) => Value::IO(Box::new(IOInner {
1314− fn_ptr: io.fn_ptr,
1315− env: self.clone_from_child(io.env, child),
1316− source: io.source.clone(),
1317− })),
1320+ Value::Function(f) => {
1321+ unsafe { code_handle_retain(f.code) };
1322+ Value::Function(Box::new(FunctionInner {
1323+ fn_ptr: f.fn_ptr,
1324+ env: self.clone_from_child(f.env, child),
1325+ source: f.source.clone(),
1326+ extract_source: f.extract_source.clone(),
1327+ code: f.code,
1328+ }))
1329+ }
1330+ Value::IO(io) => {
1331+ unsafe { code_handle_retain(io.code) };
1332+ Value::IO(Box::new(IOInner {
1333+ fn_ptr: io.fn_ptr,
1334+ env: self.clone_from_child(io.env, child),
1335+ source: io.source.clone(),
1336+ code: io.code,
1337+ }))
1338+ }
13181339 Value::Pair(a, b) => Value::Pair(
13191340 self.clone_from_child(*a, child),
13201341 self.clone_from_child(*b, child),
@@ -2127,6 +2148,32 @@ fn get_source_schema(name: &str) -> Option<Arc<RecordSchema>> {
21272148 .cloned()
21282149}
21292150
2151+/// `base.compile` host-relation check: does the host have relation `name`, and
2152+/// does its registered schema match the snippet's declared `descriptor`?
2153+/// Returns 0 = match, 1 = shape mismatch, 2 = host has no such relation.
2154+/// Called by the JIT *before* it runs the snippet, so a foreign or
2155+/// shape-drifted relation is rejected as a clean compile error rather than a
2156+/// SQL panic when the snippet's `main` touches the (missing/wrong) table.
2157+#[unsafe(no_mangle)]
2158+pub extern "C-unwind" fn knot_compile_host_rel_matches(
2159+ name_ptr: *const u8,
2160+ name_len: usize,
2161+ desc_ptr: *const u8,
2162+ desc_len: usize,
2163+) -> i32 {
2164+ let name = unsafe { str_from_raw(name_ptr, name_len) };
2165+ let desc = unsafe { str_from_raw(desc_ptr, desc_len) };
2166+ let host_rels = SOURCE_SCHEMAS.read().unwrap_or_else(|e| e.into_inner());
2167+ let Some(host_schema) = host_rels.get(name) else {
2168+ return 2;
2169+ };
2170+ if parse_record_schema(desc) == **host_schema {
2171+ 0
2172+ } else {
2173+ 1
2174+ }
2175+}
2176+
21302177/// Registry of columns stored as genuine TEXT (BINARY collation in SQLite) —
21312178/// `ColType::Text`, `Tag`, or `Json` — keyed by `(source, column)`. Int columns
21322179/// are native INTEGERs, so they never appear here.
@@ -3504,8 +3551,7 @@ fn debug_sql_params(sql: &str, params: &[rusqlite::types::Value]) {
35043551/// scalar overrides only the last occurrence is meaningful (last-wins,
35053552/// matching the previous single-slot behavior). `is_bool` enables the
35063553/// bare-flag-means-true two-arg disambiguation.
3507−fn override_flag_values(name: &str, is_bool: bool) -> Vec<String> {
3508− let flag = format!("--{}", name);
3554+fn override_flag_values(name: &str, is_bool: bool) -> Vec<String> { let flag = format!("--{}", name);
35093555 // Use args_os and skip non-UTF-8 entries: std::env::args() panics on
35103556 // non-UTF-8 argv, which would crash before any override lookup runs.
35113557 let args: Vec<String> = std::env::args_os()
@@ -3564,6 +3610,23 @@ fn override_parse_error(name: &str, val: &str, expected: &str) -> ! {
35643610/// Scans `std::env::args()` for `--{name}=value` or `--{name} value`.
35653611/// `type_tag`: 0=Int, 1=Float, 2=Text, 3=Bool, 4=Maybe Int, 5=Maybe Float, 6=Maybe Text, 7=Maybe Bool.
35663612/// Maybe tags automatically wrap the parsed value in `Just`.
3613+/// Forbid a CLI flag for a `#`-argument whose type isn't CLI-settable (a
3614+/// record, a function, a collection of non-scalars). When such an arg has a
3615+/// default, codegen routes here so a passed flag aborts loudly instead of
3616+/// silently falling through to the default. No-op when the flag is absent.
3617+#[unsafe(no_mangle)]
3618+pub extern "C-unwind" fn knot_override_forbid(name_ptr: *const u8, name_len: usize) -> *mut Value {
3619+ let name = unsafe { str_from_raw(name_ptr, name_len) };
3620+ if !override_flag_values(name, false).is_empty() {
3621+ eprintln!(
3622+ "Error: argument --{} has a type that cannot be set from the command line",
3623+ name
3624+ );
3625+ std::process::exit(1);
3626+ }
3627+ alloc(Value::Unit)
3628+}
3629+
35673630/// Returns a boxed `Value` if found, or null if absent.
35683631/// On parse error, prints a message and exits.
35693632#[unsafe(no_mangle)]
@@ -3641,14 +3704,47 @@ pub extern "C-unwind" fn knot_override_lookup(
36413704 }
36423705}
36433706
3707+/// The element type of a collection override (`Vec`/`Rel`/`List <elem>`).
3708+enum ElemKind<'a> {
3709+ /// A CLI-parseable scalar: "Int" | "Float" | "Text" | "Bool".
3710+ Scalar(&'a str),
3711+ Bytes,
3712+ Uuid,
3713+ /// All-nullary ADT: valid constructor names.
3714+ Enum(&'a [String]),
3715+ /// Refined element: the base scalar it parses as. The per-element
3716+ /// predicate check runs in generated code, not here.
3717+ Refined(&'a str),
3718+}
3719+
3720+impl<'a> ElemKind<'a> {
3721+ fn is_bool(&self) -> bool {
3722+ matches!(self, ElemKind::Scalar("Bool"))
3723+ }
3724+ fn expected(&self) -> String {
3725+ match self {
3726+ ElemKind::Scalar(s) => s.to_string(),
3727+ ElemKind::Bytes => "base64url-encoded Bytes".to_string(),
3728+ ElemKind::Uuid => "a Uuid".to_string(),
3729+ ElemKind::Enum(ctors) => format!("one of: {}", ctors.join(", ")),
3730+ ElemKind::Refined(base) => base.to_string(),
3731+ }
3732+ }
3733+}
3734+
36443735/// The override kinds that go through `knot_override_lookup_ex` rather than
36453736/// the tag-based `knot_override_lookup`. Parsed from the compiler-emitted
36463737/// descriptor string.
36473738enum ExKind<'a> {
36483739 Bytes,
36493740 Uuid,
3650− /// Element scalar for `Rel <scalar>` ("Int" | "Float" | "Text" | "Bool").
3651− Rel(&'a str),
3741+ /// Element type for `Rel <elem>`. A relation is a SET: rows are deduped.
3742+ Rel(ElemKind<'a>),
3743+ /// `Vec <elem>` — ordered, allows duplicates. Shares the relation
3744+ /// representation but skips dedup.
3745+ Vec(ElemKind<'a>),
3746+ /// `List <elem>` — a Cons/Nil chain.
3747+ List(ElemKind<'a>),
36523748 /// All-nullary ADT: valid constructor names.
36533749 Enum(&'a [String]),
36543750 /// Refined scalar: the base scalar ("Int" | "Float" | "Text" | "Bool").
@@ -3659,10 +3755,11 @@ enum ExKind<'a> {
36593755impl<'a> ExKind<'a> {
36603756 /// Whether the flag takes a bare `--name` form (bools only).
36613757 fn is_bool(&self) -> bool {
3662− matches!(
3663− self,
3664− ExKind::Rel("Bool") | ExKind::Refined("Bool")
3665− )
3758+ match self {
3759+ ExKind::Rel(e) | ExKind::Vec(e) | ExKind::List(e) => e.is_bool(),
3760+ ExKind::Refined(b) => *b == "Bool",
3761+ _ => false,
3762+ }
36663763 }
36673764
36683765 /// Expected-type wording for parse errors.
@@ -3670,7 +3767,9 @@ impl<'a> ExKind<'a> {
36703767 match self {
36713768 ExKind::Bytes => "base64url-encoded Bytes".to_string(),
36723769 ExKind::Uuid => "a Uuid (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)".to_string(),
3673− ExKind::Rel(e) => format!("a comma-separated list of {}", e),
3770+ ExKind::Rel(e) | ExKind::Vec(e) | ExKind::List(e) => {
3771+ format!("a comma-separated list of {}", e.expected())
3772+ }
36743773 ExKind::Enum(ctors) => format!("one of: {}", ctors.join(", ")),
36753774 ExKind::Refined(b) => b.to_string(),
36763775 }
@@ -3678,8 +3777,8 @@ impl<'a> ExKind<'a> {
36783777}
36793778
36803779/// Parse the compiler-emitted descriptor: `Bytes`, `Uuid`, `Rel <scalar>`,
3681−/// `enum:<Name>(<Ctor>,<Ctor>,…)`, `refined:<Name>(<base-scalar>)`, each
3682−/// optionally prefixed by `Maybe `.
3780+/// `Vec <scalar>`, `List <scalar>`, `enum:<Name>(<Ctor>,<Ctor>,…)`,
3781+/// `refined:<Name>(<base-scalar>)`, each optionally prefixed by `Maybe `.
36833782fn parse_ex_descriptor(desc: &str) -> Option<(bool, ExKind<'_>)> {
36843783 let (is_maybe, base) = match desc.strip_prefix("Maybe ") {
36853784 Some(rest) => (true, rest),
@@ -3688,7 +3787,9 @@ fn parse_ex_descriptor(desc: &str) -> Option<(bool, ExKind<'_>)> {
36883787 let kind = match base {
36893788 "Bytes" => ExKind::Bytes,
36903789 "Uuid" => ExKind::Uuid,
3691− _ if base.starts_with("Rel ") => ExKind::Rel(&base[4..]),
3790+ _ if base.starts_with("Rel ") => ExKind::Rel(parse_elem_descriptor(&base[4..])?),
3791+ _ if base.starts_with("Vec ") => ExKind::Vec(parse_elem_descriptor(&base[4..])?),
3792+ _ if base.starts_with("List ") => ExKind::List(parse_elem_descriptor(&base[5..])?),
36923793 _ if base.starts_with("enum:") => {
36933794 let rest = &base[5..];
36943795 let open = rest.find('(')?;
@@ -3715,6 +3816,36 @@ fn parse_ex_descriptor(desc: &str) -> Option<(bool, ExKind<'_>)> {
37153816 Some((is_maybe, kind))
37163817}
37173818
3819+/// Parse a collection element descriptor into an `ElemKind`: a bare scalar
3820+/// (`Int`/`Float`/`Text`/`Bool`), `Bytes`, `Uuid`, an enum (`enum:Name(Ctor,…)`),
3821+/// or a refined type (`refined:Name(base)`).
3822+fn parse_elem_descriptor(elem: &str) -> Option<ElemKind<'_>> {
3823+ match elem {
3824+ "Int" | "Float" | "Text" | "Bool" => Some(ElemKind::Scalar(elem)),
3825+ "Bytes" => Some(ElemKind::Bytes),
3826+ "Uuid" => Some(ElemKind::Uuid),
3827+ _ if elem.starts_with("enum:") => {
3828+ let rest = &elem[5..];
3829+ let open = rest.find('(')?;
3830+ let close = rest.rfind(')')?;
3831+ let ctor_str = &rest[open + 1..close];
3832+ let ctors: Vec<String> = if ctor_str.is_empty() {
3833+ Vec::new()
3834+ } else {
3835+ ctor_str.split(',').map(|s| s.to_string()).collect()
3836+ };
3837+ Some(ElemKind::Enum(Box::leak(ctors.into_boxed_slice())))
3838+ }
3839+ _ if elem.starts_with("refined:") => {
3840+ let rest = &elem[8..];
3841+ let open = rest.find('(')?;
3842+ let close = rest.rfind(')')?;
3843+ Some(ElemKind::Refined(&rest[open + 1..close]))
3844+ }
3845+ _ => None,
3846+ }
3847+}
3848+
37183849/// Decode URL-safe base64 (RFC 4648 §5, `-`/`_`, padding optional). Returns
37193850/// None on any invalid character or length. Rejecting standard-alphabet
37203851/// characters (`+`/`/`) is deliberate: the CLI accepts base64url only.
@@ -3749,24 +3880,56 @@ fn decode_base64url(s: &str) -> Option<Vec<u8>> {
37493880 Some(out)
37503881}
37513882
3752−/// Parse one scalar element for a `Rel <scalar>` override.
3753−fn parse_rel_element(name: &str, val: &str, elem: &str) -> *mut Value {
3883+/// Parse one element for a `Vec`/`Rel`/`List <elem>` override.
3884+fn parse_rel_element(name: &str, val: &str, elem: &ElemKind) -> *mut Value {
37543885 match elem {
3755− "Int" => match val.parse::<i64>() {
3756− Ok(n) => alloc_int(n),
3757− Err(_) => override_parse_error(name, val, "Int"),
3758− },
3759− "Float" => match val.parse::<f64>() {
3760− Ok(n) if n.is_finite() => alloc_float(n),
3761− _ => override_parse_error(name, val, "Float"),
3886+ ElemKind::Scalar(s) => match *s {
3887+ "Int" => match val.parse::<i64>() {
3888+ Ok(n) => alloc_int(n),
3889+ Err(_) => override_parse_error(name, val, "Int"),
3890+ },
3891+ "Float" => match val.parse::<f64>() {
3892+ Ok(n) if n.is_finite() => alloc_float(n),
3893+ _ => override_parse_error(name, val, "Float"),
3894+ },
3895+ "Text" => alloc(Value::Text(Arc::from(val))),
3896+ "Bool" => match val {
3897+ "true" | "True" | "1" => encode_bool(true),
3898+ "false" | "False" | "0" => encode_bool(false),
3899+ _ => override_parse_error(name, val, "true or false"),
3900+ },
3901+ _ => override_parse_error(name, val, "a scalar"),
37623902 },
3763− "Text" => alloc(Value::Text(Arc::from(val))),
3764− "Bool" => match val {
3765− "true" | "True" | "1" => encode_bool(true),
3766− "false" | "False" | "0" => encode_bool(false),
3767− _ => override_parse_error(name, val, "true or false"),
3903+ ElemKind::Bytes => match decode_base64url(val) {
3904+ Some(bytes) => alloc(Value::Bytes(Arc::from(bytes))),
3905+ None => override_parse_error(name, val, "base64url-encoded Bytes"),
37683906 },
3769− _ => override_parse_error(name, val, "a scalar"),
3907+ ElemKind::Uuid => {
3908+ let valid = val.len() == 36
3909+ && val.as_bytes().iter().enumerate().all(|(i, &b)| {
3910+ if i == 8 || i == 13 || i == 18 || i == 23 {
3911+ b == b'-'
3912+ } else {
3913+ b.is_ascii_hexdigit()
3914+ }
3915+ });
3916+ if valid {
3917+ alloc(Value::Text(Arc::from(val)))
3918+ } else {
3919+ override_parse_error(name, val, "a Uuid")
3920+ }
3921+ }
3922+ ElemKind::Enum(ctors) => {
3923+ if ctors.iter().any(|c| c == val) {
3924+ let tag = intern_str(val);
3925+ alloc(Value::Constructor(tag, alloc(Value::Unit)))
3926+ } else {
3927+ override_parse_error(name, val, &format!("one of: {}", ctors.join(", ")))
3928+ }
3929+ }
3930+ // A refined element parses as its base scalar; the per-element
3931+ // predicate check runs in generated code.
3932+ ElemKind::Refined(base) => parse_rel_element(name, val, &ElemKind::Scalar(base)),
37703933 }
37713934}
37723935
@@ -3794,21 +3957,13 @@ pub extern "C-unwind" fn knot_override_lookup_ex(
37943957
37953958 let values = override_flag_values(name, kind.is_bool());
37963959
3797− // A Maybe-wrapped flag explicitly set to "Nothing" means `Nothing {}`.
3798− if is_maybe
3799− && let Some(last) = values.last()
3800− && last == "Nothing"
3801− {
3802− return make_nothing();
3803− }
3804−
3805− if let ExKind::Rel(elem) = &kind {
3960+ if let ExKind::Rel(elem) | ExKind::Vec(elem) | ExKind::List(elem) = &kind {
38063961 if values.is_empty() {
38073962 return std::ptr::null_mut();
38083963 }
38093964 // Each occurrence may be comma-separated; an empty value
38103965 // (`--tag=`) contributes no elements, so `--tag=` alone yields
3811− // the empty relation.
3966+ // the empty collection.
38123967 let mut rows: Vec<*mut Value> = Vec::new();
38133968 for occ in &values {
38143969 for piece in occ.split(',') {
@@ -3818,8 +3973,23 @@ pub extern "C-unwind" fn knot_override_lookup_ex(
38183973 rows.push(parse_rel_element(name, piece, elem));
38193974 }
38203975 }
3821− let rel = alloc(Value::Relation(rows));
3822− return if is_maybe { make_just(rel) } else { rel };
3976+ let v = match &kind {
3977+ // A relation is a set: dedup.
3978+ ExKind::Rel(_) => alloc(Value::Relation(in_memory_dedup(rows))),
3979+ // A vec is ordered and allows duplicates: same representation, no
3980+ // dedup.
3981+ ExKind::Vec(_) => alloc(Value::Relation(rows)),
3982+ // A list is a Cons/Nil chain, built tail-first.
3983+ ExKind::List(_) => {
3984+ let mut acc = list_nil();
3985+ for row in rows.into_iter().rev() {
3986+ acc = list_cons(row, acc);
3987+ }
3988+ acc
3989+ }
3990+ _ => unreachable!(),
3991+ };
3992+ return if is_maybe { make_just(v) } else { v };
38233993 }
38243994
38253995 // Scalar-shaped kinds: last occurrence wins.
@@ -3861,9 +4031,11 @@ pub extern "C-unwind" fn knot_override_lookup_ex(
38614031 ExKind::Refined(base) => {
38624032 // Parse as the base scalar; the refinement predicate is checked
38634033 // by generated code after this returns.
3864− parse_rel_element(name, val_str, base)
4034+ parse_rel_element(name, val_str, &ElemKind::Scalar(base))
4035+ }
4036+ ExKind::Rel(_) | ExKind::Vec(_) | ExKind::List(_) => {
4037+ unreachable!("handled above")
38654038 }
3866− ExKind::Rel(_) => unreachable!("handled above"),
38674039 };
38684040
38694041 if is_maybe {
@@ -3938,6 +4110,74 @@ pub extern "C-unwind" fn knot_override_check_refined(
39384110 }
39394111}
39404112
4113+/// Apply a refined predicate to every element of a collection override
4114+/// (`Vec`/`Rel` — the relation representation — or `List`, a Cons/Nil chain).
4115+/// `pred_fn` is the compiled predicate (a function value); `db` is the live db
4116+/// handle for the call. Aborts naming the flag and type on the first element
4117+/// that fails. No-op when the override is null (flag absent — the default was
4118+/// already checked at compile time).
4119+#[unsafe(no_mangle)]
4120+pub extern "C-unwind" fn knot_override_check_refined_each(
4121+ db: *mut std::ffi::c_void,
4122+ coll: *mut Value,
4123+ pred_fn: *mut Value,
4124+ flag_ptr: *const u8,
4125+ flag_len: usize,
4126+ ty_ptr: *const u8,
4127+ ty_len: usize,
4128+) {
4129+ if coll.is_null() {
4130+ return;
4131+ }
4132+ let flag = unsafe { str_from_raw(flag_ptr, flag_len) }.to_string();
4133+ let ty = unsafe { str_from_raw(ty_ptr, ty_len) }.to_string();
4134+ let check = |elem: *mut Value| {
4135+ let res = knot_value_call(db, pred_fn, elem);
4136+ let ok = matches!(unsafe { as_ref(res) }, Value::Bool(true));
4137+ if !ok {
4138+ eprintln!(
4139+ "Error: value '{}' for --{} does not satisfy predicate for type '{}'",
4140+ display_value(elem),
4141+ flag,
4142+ ty
4143+ );
4144+ std::process::exit(1);
4145+ }
4146+ };
4147+ match unsafe { as_ref(coll) } {
4148+ Value::Relation(rows) => {
4149+ for &row in rows {
4150+ check(row);
4151+ }
4152+ }
4153+ // A List is a Cons/Nil chain: Cons {head, tail}.
4154+ Value::Constructor(..) => {
4155+ let mut cur = coll;
4156+ loop {
4157+ match unsafe { as_ref(cur) } {
4158+ Value::Constructor(tag, payload) if ctor_leaf(tag) == "Cons" => {
4159+ if let Value::Record(fields) = unsafe { as_ref(*payload) } {
4160+ let head = fields.iter().find(|f| &*f.name == "head").map(|f| f.value);
4161+ let tail = fields.iter().find(|f| &*f.name == "tail").map(|f| f.value);
4162+ if let Some(h) = head {
4163+ check(h);
4164+ }
4165+ match tail {
4166+ Some(t) => cur = t,
4167+ None => break,
4168+ }
4169+ } else {
4170+ break;
4171+ }
4172+ }
4173+ _ => break,
4174+ }
4175+ }
4176+ }
4177+ _ => {}
4178+ }
4179+}
4180+
39414181/// Decode a default-value string emitted by the compiler.
39424182///
39434183/// The compiler escapes `\` as `\\` and `,` as `\c` so the entry
@@ -4392,6 +4632,10 @@ pub struct FunctionInner {
43924632 /// qualified, re-parseable `Maybe.Nothing {}`). `None` → extract derives
43934633 /// from `source` + `env` as usual.
43944634 pub extract_source: Option<Arc<str>>,
4635+ /// Keep-alive handle for the JIT module this function's `fn_ptr` points
4636+ /// into. Null for natively-compiled (AOT) functions, whose code lives in
4637+ /// the process image and never needs freeing. See [`CodeHandle`].
4638+ pub code: *const CodeHandle,
43954639}
43964640
43974641/// Payload for `Value::IO`: boxed to keep `Value` compact. `source` is the
@@ -4402,6 +4646,128 @@ pub struct IOInner {
44024646 pub fn_ptr: *const u8,
44034647 pub env: *mut Value,
44044648 pub source: Arc<str>,
4649+ /// Keep-alive handle for the JIT module this thunk's `fn_ptr` points into.
4650+ /// Null for AOT-compiled actions. See [`CodeHandle`].
4651+ pub code: *const CodeHandle,
4652+}
4653+
4654+/// A type-erased, refcounted keep-alive handle for a JIT'd code module.
4655+///
4656+/// A `Value::Function`/`Value::IO` produced by `base.compile` holds a `fn_ptr`
4657+/// into the JIT module's executable memory, which must stay mapped while any
4658+/// such value is reachable. But knot-runtime can't name the JIT's module type
4659+/// (that would be a dependency cycle), so the module's lifetime is exposed as
4660+/// two function pointers plus an opaque refcount word:
4661+///
4662+/// - `refcount` is a `*const AtomicUsize` owned by the JIT side.
4663+/// - `free` reclaims the module; the caller (here, on drop of the last
4664+/// function/IO referencing it) invokes it exactly once, when the shared
4665+/// refcount reaches zero.
4666+///
4667+/// Cloning a function/IO increments the refcount; dropping one decrements it.
4668+/// The arena's `reset_to`/frame-drop paths run value destructors, which is what
4669+/// drives the decrement — so a JIT module is freed precisely when the last
4670+/// closure pointing into it is reclaimed.
4671+///
4672+/// # Safety
4673+/// `refcount` and `free` must remain valid until the refcount reaches zero and
4674+/// `free` has been called. The JIT side guarantees this by leaking the handle's
4675+/// storage into the module's own lifetime.
4676+///
4677+/// `repr(C)` pins the field order — knot-jit constructs this layout via a
4678+/// mirror struct, so the two must agree byte-for-byte.
4679+#[repr(C)]
4680+pub struct CodeHandle {
4681+ pub refcount: *const std::sync::atomic::AtomicUsize,
4682+ pub free: unsafe extern "C" fn(*const std::sync::atomic::AtomicUsize),
4683+}
4684+
4685+/// Increment a code handle's refcount (a new function/IO now references the
4686+/// module). Null-safe: a null handle (AOT code) is a no-op.
4687+///
4688+/// # Safety
4689+/// `handle` must be null or point to a live [`CodeHandle`].
4690+pub unsafe fn code_handle_retain(handle: *const CodeHandle) {
4691+ if handle.is_null() {
4692+ return;
4693+ }
4694+ unsafe {
4695+ (*(*handle).refcount).fetch_add(1, std::sync::atomic::Ordering::Relaxed);
4696+ }
4697+}
4698+
4699+/// Decrement a code handle's refcount; on the last drop, free the module.
4700+/// Null-safe.
4701+///
4702+/// # Safety
4703+/// `handle` must be null or a [`CodeHandle`] whose refcount is above zero.
4704+pub unsafe fn code_handle_release(handle: *const CodeHandle) {
4705+ if handle.is_null() {
4706+ return;
4707+ }
4708+ unsafe {
4709+ // Release so prior writes are visible to whoever frees; Acquire on the
4710+ // final decrement pairs with it. On zero, hand the refcount word to the
4711+ // JIT's free routine, which reclaims the module (and the word).
4712+ if (*(*handle).refcount).fetch_sub(1, std::sync::atomic::Ordering::AcqRel) == 1 {
4713+ ((*handle).free)((*handle).refcount);
4714+ }
4715+ }
4716+}
4717+
4718+/// Recursively stamp a JIT code handle onto every `Function`/`IO` reachable
4719+/// from `v` that doesn't already have one (those have `code == null`). Sets the
4720+/// refcount to the number of values stamped, so the count matches the number of
4721+/// code-bearing values sharing the module. Called once by the JIT right after a
4722+/// `base.compile` body returns, before the value escapes to the host.
4723+///
4724+/// Depth-bounded against pathological values. Values that already carry a
4725+/// handle (e.g. a closure captured from an earlier `compile`) are left alone —
4726+/// their module is already accounted for.
4727+///
4728+/// # Safety
4729+/// `v` must be a live `Value*` produced by this runtime; `handle` a valid
4730+/// [`CodeHandle`] whose refcount is about to be initialized by this call.
4731+#[unsafe(no_mangle)]
4732+pub unsafe extern "C-unwind" fn knot_value_set_code(v: *mut Value, handle: *const CodeHandle) {
4733+ if v.is_null() || handle.is_null() {
4734+ return;
4735+ }
4736+ fn stamp(v: *mut Value, handle: *const CodeHandle, depth: usize) -> usize {
4737+ if v.is_null() || depth > 512 {
4738+ return 0;
4739+ }
4740+ match unsafe { as_ref(v) } {
4741+ Value::Function(f) => {
4742+ if f.code.is_null() {
4743+ // Cast away the shared ref to write the field once.
4744+ unsafe { (*(f.as_ref() as *const FunctionInner as *mut FunctionInner)).code = handle };
4745+ 1
4746+ } else {
4747+ 0
4748+ }
4749+ }
4750+ Value::IO(io) => {
4751+ if io.code.is_null() {
4752+ unsafe { (*(io.as_ref() as *const IOInner as *mut IOInner)).code = handle };
4753+ 1
4754+ } else {
4755+ 0
4756+ }
4757+ }
4758+ Value::Record(fields) => fields.iter().map(|f| stamp(f.value, handle, depth + 1)).sum(),
4759+ Value::Relation(elems) => elems.iter().map(|e| stamp(*e, handle, depth + 1)).sum(),
4760+ Value::Constructor(_, payload) => stamp(*payload, handle, depth + 1),
4761+ Value::Pair(a, b) => stamp(*a, handle, depth + 1) + stamp(*b, handle, depth + 1),
4762+ _ => 0,
4763+ }
4764+ }
4765+ let stamped = stamp(v, handle, 0);
4766+ if stamped > 0 {
4767+ unsafe {
4768+ (*(*handle).refcount).store(stamped, std::sync::atomic::Ordering::Relaxed);
4769+ }
4770+ }
44054771}
44064772
44074773pub struct RecordField {
@@ -4412,6 +4778,87 @@ pub struct RecordField {
44124778 pub value: *mut Value,
44134779}
44144780
4781+// Dropping a function/IO releases its JIT code handle; when the last value
4782+// referencing a module drops, the module's code memory is freed. The arena
4783+// runs these destructors on every reclaim path (`reset_to`, frame drop), so a
4784+// JIT module lives exactly as long as its longest-lived closure.
4785+impl Drop for FunctionInner {
4786+ fn drop(&mut self) {
4787+ unsafe { code_handle_release(self.code) };
4788+ }
4789+}
4790+
4791+impl Drop for IOInner {
4792+ fn drop(&mut self) {
4793+ unsafe { code_handle_release(self.code) };
4794+ }
4795+}
4796+
4797+#[cfg(test)]
4798+mod code_handle_tests {
4799+ use super::*;
4800+ use std::sync::atomic::{AtomicUsize, Ordering};
4801+
4802+ // A fake "module": a boxed (refcount, freed-flag, handle). `free` flips the
4803+ // freed flag via the refcount's container, mirroring how the JIT's block
4804+ // reclaims its module when the last closure drops.
4805+ #[repr(C)]
4806+ struct FakeBlock {
4807+ refcount: AtomicUsize,
4808+ freed: std::sync::atomic::AtomicBool,
4809+ handle: CodeHandle,
4810+ }
4811+
4812+ unsafe extern "C" fn fake_free(refcount: *const AtomicUsize) {
4813+ let block = refcount as *mut FakeBlock;
4814+ unsafe {
4815+ (*block).freed.store(true, Ordering::SeqCst);
4816+ drop(Box::from_raw(block));
4817+ }
4818+ }
4819+
4820+ fn new_block(count: usize) -> (*mut FakeBlock, *const CodeHandle) {
4821+ let mut b = Box::new(FakeBlock {
4822+ refcount: AtomicUsize::new(count),
4823+ freed: std::sync::atomic::AtomicBool::new(false),
4824+ handle: CodeHandle {
4825+ refcount: std::ptr::null(),
4826+ free: fake_free,
4827+ },
4828+ });
4829+ b.handle.refcount = &raw const b.refcount;
4830+ let handle = &raw const b.handle;
4831+ (Box::into_raw(b), handle)
4832+ }
4833+
4834+ #[test]
4835+ fn release_to_zero_frees() {
4836+ let (block, handle) = new_block(2);
4837+ unsafe { code_handle_release(handle) }; // 2 -> 1
4838+ assert!(!unsafe { (*block).freed.load(Ordering::SeqCst) });
4839+ let freed_flag = unsafe { (*block).freed.load(Ordering::SeqCst) };
4840+ assert!(!freed_flag);
4841+ unsafe { code_handle_release(handle) }; // 1 -> 0 → free
4842+ // block is now freed; we can't read it. The test not crashing/hanging is
4843+ // the assertion; freed was set inside fake_free before the Box drop.
4844+ }
4845+
4846+ #[test]
4847+ fn retain_then_release_balances() {
4848+ let (block, handle) = new_block(1);
4849+ unsafe { code_handle_retain(handle) }; // 1 -> 2
4850+ unsafe { code_handle_release(handle) }; // 2 -> 1
4851+ assert!(!unsafe { (*block).freed.load(Ordering::SeqCst) });
4852+ unsafe { code_handle_release(handle) }; // 1 -> 0 → free
4853+ }
4854+
4855+ #[test]
4856+ fn null_handle_is_noop() {
4857+ unsafe { code_handle_retain(std::ptr::null()) };
4858+ unsafe { code_handle_release(std::ptr::null()) };
4859+ }
4860+}
4861+
44154862impl Drop for Value {
44164863 fn drop(&mut self) {
44174864 // Custom Drop intercepts `Value::Relation` / `Value::Record` to
@@ -4958,6 +5405,7 @@ fn alloc_io(fn_ptr: *const u8, env: *mut Value, source: Arc<str>) -> *mut Value
49585405 fn_ptr,
49595406 env,
49605407 source,
5408+ code: std::ptr::null(),
49615409 })))
49625410}
49635411
@@ -5592,6 +6040,7 @@ pub extern "C-unwind" fn knot_value_function(
55926040 env,
55936041 source,
55946042 extract_source: None,
6043+ code: std::ptr::null(),
55956044 })))
55966045}
55976046
@@ -5615,6 +6064,7 @@ pub extern "C-unwind" fn knot_value_function_full(
56156064 env,
56166065 source,
56176066 extract_source,
6067+ code: std::ptr::null(),
56186068 })))
56196069}
56206070
@@ -8574,6 +9024,11 @@ pub extern "C-unwind" fn knot_value_call(
85749024) -> *mut Value {
85759025 match unsafe { as_ref(func) } {
85769026 Value::Function(f) => {
9027+ // Establish the callee's db as this thread's current-db for the
9028+ // duration of the call, so a `base.compile` inside it (or inside a
9029+ // deeper call) runs its snippet on this handle — sharing any
9030+ // enclosing `atomic` SAVEPOINT — then restore the caller's.
9031+ let _db_scope = RestoreDb::new(db);
85779032 let fun: extern "C-unwind" fn(*mut c_void, *mut Value, *mut Value) -> *mut Value =
85789033 unsafe { std::mem::transmute(f.fn_ptr) };
85799034 fun(db, f.env, arg)
@@ -9242,6 +9697,9 @@ pub extern "C-unwind" fn knot_io_pure(val: *mut Value) -> *mut Value {
92429697/// Execute an IO thunk. If the value is not IO, return it as-is.
92439698#[unsafe(no_mangle)]
92449699pub extern "C-unwind" fn knot_io_run(db: *mut c_void, val: *mut Value) -> *mut Value {
9700+ // Current-db for the whole IO chain: any `base.compile` reached while
9701+ // running these thunks runs on this handle (sharing an enclosing atomic).
9702+ let _db_scope = RestoreDb::new(db);
92459703 let mut current = val;
92469704 loop {
92479705 // Cooperative cancellation: a `race` loser exits its IO chain at the
@@ -9458,19 +9916,23 @@ fn deep_clone_with(val: *mut Value, mut alloc_node: impl FnMut(Value) -> *mut Va
94589916 }
94599917 Value::Function(f) => {
94609918 to_alloc.push(f.env);
9919+ unsafe { code_handle_retain(f.code) };
94619920 Value::Function(Box::new(FunctionInner {
94629921 fn_ptr: f.fn_ptr,
94639922 env: std::ptr::null_mut(),
94649923 source: f.source.clone(),
94659924 extract_source: f.extract_source.clone(),
9925+ code: f.code,
94669926 }))
94679927 }
94689928 Value::IO(io) => {
94699929 to_alloc.push(io.env);
9930+ unsafe { code_handle_retain(io.code) };
94709931 Value::IO(Box::new(IOInner {
94719932 fn_ptr: io.fn_ptr,
94729933 env: std::ptr::null_mut(),
94739934 source: io.source.clone(),
9935+ code: io.code,
94749936 }))
94759937 }
94769938 Value::Pair(a, b) => {
@@ -10740,6 +11202,7 @@ pub extern "C-unwind" fn knot_trace(
1074011202 env,
1074111203 source: Arc::from("trace"),
1074211204 extract_source: None,
11205+ code: std::ptr::null(),
1074311206 })))
1074411207}
1074511208
@@ -11586,43 +12049,112 @@ type CompileImpl = unsafe extern "C" fn(
1158612049static COMPILE_IMPL: std::sync::atomic::AtomicPtr<c_void> =
1158712050 std::sync::atomic::AtomicPtr::new(std::ptr::null_mut());
1158812051
11589−/// Registered by knot-compile-rt at program startup to install the compile
11590−/// implementation. Called from the generated program's `main`.
11591−#[unsafe(no_mangle)]
11592−pub extern "C-unwind" fn knot_register_compile_impl(f: *mut c_void) {
11593− COMPILE_IMPL.store(f, std::sync::atomic::Ordering::Release);
12052+/// The successful result of running a compile closure: the value plus the
12053+/// optional body-type descriptor and the snippet's declared relations, to hand
12054+/// back through the FFI out-params.
12055+pub struct CompileOutcome {
12056+ pub value: *mut Value,
12057+ pub ty: Option<String>,
12058+ pub relations: Vec<String>,
1159412059}
1159512060
11596−/// Is `v` free of any JIT'd code reference? A compiled snippet's JIT module
11597−/// may be freed only when its result cannot re-enter the module's code. Only
11598−/// `Function` and `IO` values carry a `fn_ptr` into that code (a lambda or an
11599−/// IO thunk); every other variant is pure data whose children are values, not
11600−/// code. Recurses through records, relations, constructor payloads, and pairs.
11601−/// `1` = code-free (module safe to free), `0` = holds code (must keep the
11602−/// module alive).
12061+/// Null the three out-param pairs so a compile error leaves them well-defined.
1160312062///
1160412063/// # Safety
11605−/// `v` must be a live `Value*` produced by this runtime.
11606−#[unsafe(no_mangle)]
11607−pub extern "C-unwind" fn knot_value_is_code_free(v: *mut Value) -> i32 {
11608− if v.is_null() {
11609− return 1;
12064+/// Each non-null pointer must be valid for writes of its payload.
12065+pub unsafe fn compile_out_params_init(pairs: [(*mut *mut u8, *mut usize); 3]) {
12066+ unsafe {
12067+ for (p, l) in pairs {
12068+ if !p.is_null() {
12069+ *p = std::ptr::null_mut();
12070+ }
12071+ if !l.is_null() {
12072+ *l = 0;
12073+ }
12074+ }
1161012075 }
11611− // Depth-bounded: a pathological cyclic value can't overflow the stack.
11612− fn go(v: *mut Value, depth: usize) -> bool {
11613− if v.is_null() || depth > 512 {
11614− return depth > 512; // too deep to prove code-free → keep the module
12076+}
12077+
12078+/// Hand a string back as a malloc'd buffer (C ABI — the caller frees it).
12079+///
12080+/// # Safety
12081+/// `ptr`/`len`, if non-null, must be valid for writes.
12082+pub unsafe fn compile_write_out(s: &str, ptr: *mut *mut u8, len: *mut usize) {
12083+ if ptr.is_null() || len.is_null() {
12084+ return;
12085+ }
12086+ let buf = unsafe { libc::malloc(s.len().max(1)) as *mut u8 };
12087+ if buf.is_null() {
12088+ return;
12089+ }
12090+ unsafe {
12091+ std::ptr::copy_nonoverlapping(s.as_ptr(), buf, s.len());
12092+ *ptr = buf;
12093+ *len = s.len();
12094+ }
12095+}
12096+
12097+/// Run a `base.compile` compile+run closure behind the FFI boundary, containing
12098+/// any panic. `compile` is the compiler- and backend-specific work; it returns
12099+/// `Ok(Some(outcome))` on success, `Ok(None)` on a clean compile error, and any
12100+/// panic is caught here. On success the outcome's ty/relations are written to
12101+/// the out-params and the value returned; on error or panic the (already
12102+/// nulled) out-params get the message in `out_err` and null is returned, so the
12103+/// runtime surfaces a `Result.Err` instead of unwinding into the host.
12104+///
12105+/// This is the single containment point shared by every `knot_compile_impl`
12106+/// (the compiler binary's and the `knot-compile-rt` one a compiled program
12107+/// links), so the two cannot drift apart.
12108+///
12109+/// # Safety
12110+/// `db` must be a live db handle; the out-param pointers, if non-null, must be
12111+/// valid for writes of their payload. They must already be nulled via
12112+/// [`compile_out_params_init`] by the caller.
12113+#[allow(clippy::too_many_arguments)]
12114+pub unsafe fn run_compile_contained(
12115+ db: *mut c_void,
12116+ out_ty_ptr: *mut *mut u8,
12117+ out_ty_len: *mut usize,
12118+ out_rels_ptr: *mut *mut u8,
12119+ out_rels_len: *mut usize,
12120+ out_err_ptr: *mut *mut u8,
12121+ out_err_len: *mut usize,
12122+ compile: impl FnOnce(*mut c_void) -> Option<CompileOutcome>,
12123+) -> *mut Value {
12124+ // The raw pointers are !UnwindSafe, so assert it; the closure only reads
12125+ // them and the out-params were nulled by the caller, so no broken state is
12126+ // observable across a caught panic.
12127+ let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| compile(db)));
12128+ match r {
12129+ Ok(Some(outcome)) => {
12130+ if let Some(ty) = &outcome.ty {
12131+ unsafe { compile_write_out(ty, out_ty_ptr, out_ty_len) };
12132+ }
12133+ let csv = outcome.relations.join(",");
12134+ unsafe { compile_write_out(&csv, out_rels_ptr, out_rels_len) };
12135+ outcome.value
1161512136 }
11616− match unsafe { as_ref(v) } {
11617− Value::Function(_) | Value::IO(_) => false,
11618− Value::Record(fields) => fields.iter().all(|f| go(f.value, depth + 1)),
11619− Value::Relation(elems) => elems.iter().all(|e| go(*e, depth + 1)),
11620− Value::Constructor(_, payload) => go(*payload, depth + 1),
11621− Value::Pair(a, b) => go(*a, depth + 1) && go(*b, depth + 1),
11622− _ => true,
12137+ Ok(None) => std::ptr::null_mut(),
12138+ Err(payload) => {
12139+ let msg = payload
12140+ .downcast_ref::<&str>()
12141+ .map(|s| (*s).to_string())
12142+ .or_else(|| payload.downcast_ref::<String>().cloned())
12143+ .unwrap_or_else(|| "unknown panic".to_string());
12144+ unsafe {
12145+ compile_write_out(&format!("compile panicked: {msg}"), out_err_ptr, out_err_len)
12146+ };
12147+ std::ptr::null_mut()
1162312148 }
1162412149 }
11625− go(v, 0) as i32
12150+}
12151+
12152+
12153+/// Registered by knot-compile-rt at program startup to install the compile
12154+/// implementation. Called from the generated program's `main`.
12155+#[unsafe(no_mangle)]
12156+pub extern "C-unwind" fn knot_register_compile_impl(f: *mut c_void) {
12157+ COMPILE_IMPL.store(f, std::sync::atomic::Ordering::Release);
1162612158}
1162712159
1162812160/// Look up the registered compile implementation, if any.
@@ -11654,16 +12186,28 @@ fn compile_run(
1165412186 Some("no JIT linked (knot-compile-rt not registered)".into()),
1165512187 );
1165612188 };
11657− // Open a db handle for the snippet. knot_db_open records the path on first
11658− // open (DB_PATH), so reuse it; a pure program (no store) gets :memory:.
11659− // A snippet reading the host's persisted relations thus sees real data.
11660− let db_path = DB_PATH.lock().unwrap_or_else(|e| e.into_inner()).clone();
11661− let (pstr, plen) = if db_path.is_empty() {
11662− (":memory:".as_bytes().as_ptr(), ":memory:".len())
11663− } else {
11664− (db_path.as_ptr(), db_path.len())
12189+ // Run the snippet on the CALLER's live db handle when one is active
12190+ // (the normal case: the host program called `base.compile` from running
12191+ // code, so CURRENT_DB holds its handle). This makes the compiled value
12192+ // share the host's connection — and any enclosing `atomic` SAVEPOINT — so
12193+ // its reads see uncommitted writes and its writes roll back with the
12194+ // transaction. When there is no caller (the compiler's const-eval thread),
12195+ // fall back to opening a connection: reuse the recorded host path so a
12196+ // snippet reading persisted relations sees real data, else `:memory:`.
12197+ let db = {
12198+ let cur = current_db();
12199+ if !cur.is_null() {
12200+ cur
12201+ } else {
12202+ let db_path = DB_PATH.lock().unwrap_or_else(|e| e.into_inner()).clone();
12203+ let (pstr, plen) = if db_path.is_empty() {
12204+ (":memory:".as_bytes().as_ptr(), ":memory:".len())
12205+ } else {
12206+ (db_path.as_ptr(), db_path.len())
12207+ };
12208+ knot_db_open(pstr, plen)
12209+ }
1166512210 };
11666− let db = knot_db_open(pstr, plen);
1166712211
1166812212 // The host's expected type (source-annotation string) forwarded to the JIT,
1166912213 // which runs the real-type subsumption. Empty → unpinned.
@@ -11723,12 +12267,15 @@ fn compile_run(
1172312267 free_ty(ty_ptr);
1172412268 return (std::ptr::null_mut(), None, err);
1172512269 }
11726− // Foreign-`*rel` guard.
12270+ // Foreign-`*rel` guard (defense-in-depth — the JIT already validated each
12271+ // relation's name AND shape against the host before running the snippet;
12272+ // see knot_compile_host_rel_matches). Each entry is `name\tdescriptor`.
1172712273 if !rels_csv.is_empty() {
1172812274 let host_rels = SOURCE_SCHEMAS.read().unwrap_or_else(|e| e.into_inner());
11729− let foreign = rels_csv
11730− .split(',')
11731− .any(|r| !r.is_empty() && !host_rels.contains_key(r));
12275+ let foreign = rels_csv.split(',').filter(|e| !e.is_empty()).any(|entry| {
12276+ let name = entry.split_once('\t').map(|(n, _)| n).unwrap_or(entry);
12277+ !host_rels.contains_key(name)
12278+ });
1173212279 drop(host_rels);
1173312280 if foreign {
1173412281 free_ty(ty_ptr);
@@ -13641,6 +14188,73 @@ fn read_schema_cursor(conn: &rusqlite::Connection, name: &str) -> Option<(String
1364114188 .ok()
1364214189}
1364314190
14191+/// One migration step baked into the binary, recorded at startup for
14192+/// `db info`: the `from`/`to` descriptors and the migration fn source.
14193+#[derive(Clone, Debug)]
14194+pub struct MigrationStep {
14195+ pub step_idx: i64,
14196+ pub from_schema: String,
14197+ pub to_schema: String,
14198+ pub using_src: String,
14199+}
14200+
14201+/// The migration chain per source, recorded as the binary registers each step
14202+/// at startup. Lets `db info` show the full migration history (which lives in
14203+/// the binary, not the db) alongside the db's current cursor.
14204+static MIGRATION_CHAINS: std::sync::LazyLock<RwLock<HashMap<String, Vec<MigrationStep>>>> =
14205+ std::sync::LazyLock::new(|| RwLock::new(HashMap::new()));
14206+
14207+/// Record one migration step for `db info`. Idempotent per (source, step_idx)
14208+/// — re-registration (e.g. a rebuilt binary with the same chain) replaces it.
14209+fn register_migration_step(source: &str, step: MigrationStep) {
14210+ let mut chains = MIGRATION_CHAINS.write().unwrap_or_else(|e| e.into_inner());
14211+ let chain = chains.entry(source.to_string()).or_default();
14212+ match chain.iter_mut().find(|s| s.step_idx == step.step_idx) {
14213+ Some(existing) => *existing = step,
14214+ None => chain.push(step),
14215+ }
14216+ chain.sort_by_key(|s| s.step_idx);
14217+}
14218+
14219+/// `<program>` startup registers each baked-in migration step so `db info` can
14220+/// show the full per-source chain (which lives in the binary, not the db).
14221+/// `from`/`to` are the step's descriptors, `using_src` the migration fn source.
14222+#[unsafe(no_mangle)]
14223+pub extern "C-unwind" fn knot_register_migration_step(
14224+ source_ptr: *const u8,
14225+ source_len: usize,
14226+ step_idx: i64,
14227+ from_ptr: *const u8,
14228+ from_len: usize,
14229+ to_ptr: *const u8,
14230+ to_len: usize,
14231+ using_ptr: *const u8,
14232+ using_len: usize,
14233+) {
14234+ let source = unsafe { str_from_raw(source_ptr, source_len) };
14235+ register_migration_step(
14236+ source,
14237+ MigrationStep {
14238+ step_idx,
14239+ from_schema: unsafe { str_from_raw(from_ptr, from_len) }.to_string(),
14240+ to_schema: unsafe { str_from_raw(to_ptr, to_len) }.to_string(),
14241+ using_src: unsafe { str_from_raw(using_ptr, using_len) }.to_string(),
14242+ },
14243+ );
14244+}
14245+
14246+
14247+/// Read the recorded chain for a source (empty if none registered).
14248+fn migration_chain_for(source: &str) -> Vec<MigrationStep> {
14249+ MIGRATION_CHAINS
14250+ .read()
14251+ .unwrap_or_else(|e| e.into_inner())
14252+ .get(source)
14253+ .cloned()
14254+ .unwrap_or_default()
14255+}
14256+
14257+
1364414258/// Apply a migration to a source relation.
1364514259///
1364614260/// Checks the stored schema in `_knot_schema`:
@@ -14069,6 +14683,9 @@ pub extern "C-unwind" fn knot_run_user_main(
1406914683) -> *mut c_void {
1407014684 let f: extern "C-unwind" fn(*mut c_void) -> *mut c_void =
1407114685 unsafe { std::mem::transmute(main_fn) };
14686+ // Establish the program's db as current-db so a top-level `base.compile`
14687+ // (before any knot_value_call/knot_io_run) runs its snippet on this handle.
14688+ let _db_scope = RestoreDb::new(db);
1407214689 match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| f(db))) {
1407314690 Ok(v) => v,
1407414691 Err(payload) => {
@@ -19049,6 +19666,7 @@ fn build_request_ctx(
1904919666 env: header_env,
1905019667 source: intern_str("RequestCtx.header"),
1905119668 extract_source: None,
19669+ code: std::ptr::null(),
1905219670 })));
1905319671 let mut fields = vec![
1905419672 RecordField {
@@ -19490,6 +20108,46 @@ pub extern "C-unwind" fn knot_constraint_register(
1949020108
1949120109// ── Atomic (transactions) ─────────────────────────────────────────
1949220110
20111+thread_local! {
20112+ /// The db handle of the knot code currently executing on this thread —
20113+ /// the handle the innermost active `knot_user_main`/`knot_value_call`/
20114+ /// `knot_io_run` was invoked with. `base.compile` runs its snippet on this
20115+ /// handle (rather than opening a fresh connection) so a compiled value used
20116+ /// inside the host's `atomic` block shares the host's SAVEPOINT: its reads
20117+ /// see uncommitted writes and its own writes roll back with the transaction.
20118+ ///
20119+ /// Set on entry to the foreign-boundary crossings (`knot_run_user_main`,
20120+ /// `knot_value_call`, `knot_io_run`) and restored on return, so a nested
20121+ /// `compile`'s snippet doesn't clobber the host's current-db after the
20122+ /// snippet returns. Null outside any knot execution (e.g. the compiler's
20123+ /// const-eval thread), where `compile` falls back to its own connection.
20124+ static CURRENT_DB: std::cell::Cell<*mut c_void> = const { std::cell::Cell::new(std::ptr::null_mut()) };
20125+}
20126+
20127+/// Set the current-db for this thread, returning the previous value so the
20128+/// caller can restore it on scope exit (see [`RestoreDb`]).
20129+fn set_current_db(db: *mut c_void) -> *mut c_void {
20130+ CURRENT_DB.with(|c| c.replace(db))
20131+}
20132+
20133+/// RAII guard restoring the previous current-db on drop.
20134+struct RestoreDb(*mut c_void);
20135+impl RestoreDb {
20136+ fn new(db: *mut c_void) -> Self {
20137+ RestoreDb(set_current_db(db))
20138+ }
20139+}
20140+impl Drop for RestoreDb {
20141+ fn drop(&mut self) {
20142+ set_current_db(self.0);
20143+ }
20144+}
20145+
20146+/// The current thread's db handle, or null when outside knot execution.
20147+fn current_db() -> *mut c_void {
20148+ CURRENT_DB.with(|c| c.get())
20149+}
20150+
1949320151#[unsafe(no_mangle)]
1949420152pub extern "C-unwind" fn knot_atomic_begin(db: *mut c_void) {
1949520153 let _guard = write_lock_guard();
@@ -23077,6 +23735,231 @@ pub extern "C-unwind" fn knot_api_handle(argc: i32, argv: *const *const u8) -> i
2307723735/// Handle `<program> db` subcommand: launch TUI database explorer.
2307823736/// Returns 1 if handled (caller should exit), 0 otherwise.
2307923737#[unsafe(no_mangle)]
23738+/// Read a NUL-terminated C-string argument (arg index `i`) from argv.
23739+unsafe fn c_arg(argv: *const *const u8, i: i32) -> String {
23740+ unsafe {
23741+ let ptr = *argv.add(i as usize);
23742+ let mut len = 0;
23743+ while *ptr.add(len) != 0 {
23744+ len += 1;
23745+ }
23746+ String::from_utf8_lossy(std::slice::from_raw_parts(ptr, len)).to_string()
23747+ }
23748+}
23749+
23750+/// Minimal ANSI styling for `db info`, applied only on a TTY (plain otherwise,
23751+/// so piped output stays clean).
23752+#[derive(Clone, Copy)]
23753+struct Style {
23754+ tty: bool,
23755+}
23756+
23757+impl Style {
23758+ fn detect() -> Self {
23759+ Style {
23760+ tty: std::io::IsTerminal::is_terminal(&std::io::stdout()),
23761+ }
23762+ }
23763+ fn wrap(&self, code: &str, s: &str) -> String {
23764+ if self.tty {
23765+ format!("\x1b[{}m{}\x1b[0m", code, s)
23766+ } else {
23767+ s.to_string()
23768+ }
23769+ }
23770+ fn bold(&self, s: &str) -> String {
23771+ self.wrap("1", s)
23772+ }
23773+ fn dim(&self, s: &str) -> String {
23774+ self.wrap("2", s)
23775+ }
23776+ fn cyan(&self, s: &str) -> String {
23777+ self.wrap("36", s)
23778+ }
23779+ fn green(&self, s: &str) -> String {
23780+ self.wrap("32", s)
23781+ }
23782+ fn yellow(&self, s: &str) -> String {
23783+ self.wrap("33", s)
23784+ }
23785+}
23786+
23787+/// Human-readable byte size (e.g. `56.0 KB`).
23788+fn human_bytes(n: u64) -> String {
23789+ const KB: u64 = 1024;
23790+ const MB: u64 = KB * 1024;
23791+ const GB: u64 = MB * 1024;
23792+ if n >= GB {
23793+ format!("{:.1} GB", n as f64 / GB as f64)
23794+ } else if n >= MB {
23795+ format!("{:.1} MB", n as f64 / MB as f64)
23796+ } else if n >= KB {
23797+ format!("{:.1} KB", n as f64 / KB as f64)
23798+ } else {
23799+ format!("{} B", n)
23800+ }
23801+}
23802+
23803+/// `<program> db info` — print a human-readable report of the database in knot
23804+/// terms: file summary, then per source its current schema descriptor (the db's
23805+/// actual state), the full baked-in migration chain, and the row count.
23806+fn db_info(db_path: &str) {
23807+ let st = Style::detect();
23808+ let conn = match Connection::open(db_path) {
23809+ Ok(c) => c,
23810+ Err(e) => {
23811+ eprintln!("knot db info: cannot open {}: {}", db_path, e);
23812+ std::process::exit(1);
23813+ }
23814+ };
23815+
23816+ // ── Header: file summary ──
23817+ let size = std::fs::metadata(db_path).map(|m| m.len()).unwrap_or(0);
23818+ let pages: i64 = conn
23819+ .query_row("PRAGMA page_count", [], |r| r.get(0))
23820+ .unwrap_or(0);
23821+ let page_size: i64 = conn
23822+ .query_row("PRAGMA page_size", [], |r| r.get(0))
23823+ .unwrap_or(0);
23824+ let journal: String = conn
23825+ .query_row("PRAGMA journal_mode", [], |r| r.get(0))
23826+ .unwrap_or_default();
23827+ println!("{}", st.bold(db_path));
23828+ println!(
23829+ "{}",
23830+ st.dim(&format!(
23831+ "{} · {} pages × {} B · {}",
23832+ human_bytes(size),
23833+ pages,
23834+ page_size,
23835+ journal
23836+ ))
23837+ );
23838+ println!();
23839+
23840+ // ── Sources ──
23841+ let mut stmt = match conn
23842+ .prepare("SELECT name, schema, applied FROM _knot_schema ORDER BY name")
23843+ {
23844+ Ok(s) => s,
23845+ Err(_) => {
23846+ println!("{}", st.dim("(empty database — no sources)"));
23847+ return;
23848+ }
23849+ };
23850+ let sources: Vec<(String, String, i64)> = stmt
23851+ .query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
23852+ .map(|r| r.filter_map(|x| x.ok()).collect())
23853+ .unwrap_or_default();
23854+
23855+ if sources.is_empty() {
23856+ println!("{}", st.dim("(empty database — no sources)"));
23857+ return;
23858+ }
23859+
23860+ println!("{}", st.bold(&format!("{} source{}", sources.len(), if sources.len() == 1 { "" } else { "s" })));
23861+ println!();
23862+
23863+ // Per-relation on-disk footprint: every physical table/index belonging to a
23864+ // source, summed from dbstat. A source `users` owns `_knot_users` (main
23865+ // table), `_knot_users/…` (child/link tables for nested fields), and
23866+ // `_knot_users_…` (its indexes). We match against the *known* source names
23867+ // (longest prefix wins) so a source name containing `_`/`/` isn't split
23868+ // wrongly. Falls back to None when dbstat isn't compiled in.
23869+ let source_names: Vec<&str> = sources.iter().map(|(n, _, _)| n.as_str()).collect();
23870+ let relation_bytes: Option<std::collections::HashMap<String, u64>> = conn
23871+ .prepare("SELECT name, pgsize FROM dbstat")
23872+ .ok()
23873+ .map(|mut s| {
23874+ let mut map: std::collections::HashMap<String, u64> = std::collections::HashMap::new();
23875+ let rows = s.query_map([], |r| Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)?)));
23876+ if let Ok(rows) = rows {
23877+ for r in rows.flatten() {
23878+ let (tbl, bytes) = (r.0, r.1 as u64);
23879+ let Some(rest) = tbl.strip_prefix("_knot_") else { continue };
23880+ if rest == "schema" {
23881+ continue;
23882+ }
23883+ // Longest known source that is `rest` exactly, or a prefix
23884+ // followed by `_` (index) or `/` (child table).
23885+ let owner = source_names
23886+ .iter()
23887+ .filter(|src| {
23888+ let s: &str = src;
23889+ rest == s
23890+ || rest
23891+ .strip_prefix(s)
23892+ .is_some_and(|t| t.starts_with('_') || t.starts_with('/'))
23893+ })
23894+ .max_by_key(|src| src.len());
23895+ if let Some(owner) = owner {
23896+ *map.entry(owner.to_string()).or_insert(0) += bytes;
23897+ }
23898+ }
23899+ }
23900+ map
23901+ });
23902+
23903+ for (name, schema, applied) in &sources {
23904+ let table = quote_ident(&format!("_knot_{}", name));
23905+ let rows: i64 = conn
23906+ .query_row(&format!("SELECT count(*) FROM {}", table), [], |r| r.get(0))
23907+ .unwrap_or(0);
23908+
23909+ // Source header: *name, size, row count, migration position.
23910+ let size_part = relation_bytes
23911+ .as_ref()
23912+ .and_then(|m| m.get(name.as_str()))
23913+ .map(|b| format!("{} · ", human_bytes(*b)))
23914+ .unwrap_or_default();
23915+ println!(
23916+ "{} {}",
23917+ st.cyan(&format!("*{}", name)),
23918+ st.dim(&format!(
23919+ "{}{} row{} · migration {}",
23920+ size_part,
23921+ rows,
23922+ if rows == 1 { "" } else { "s" },
23923+ applied
23924+ ))
23925+ );
23926+ // Current descriptor (the db's actual state).
23927+ println!("{}", schema);
23928+
23929+ // The full migration chain, each step marked applied / pending.
23930+ let chain = migration_chain_for(name);
23931+ if !chain.is_empty() {
23932+ for (i, step) in chain.iter().enumerate() {
23933+ let last = i + 1 == chain.len();
23934+ let connector = if last { "└─" } else { "├─" };
23935+ if step.step_idx < *applied {
23936+ println!(
23937+ "{} {} {}",
23938+ st.dim(connector),
23939+ st.green("applied"),
23940+ st.dim(&format!("{} → {}", step.from_schema, step.to_schema))
23941+ );
23942+ } else {
23943+ println!(
23944+ "{} {} {}",
23945+ st.dim(connector),
23946+ st.yellow("pending"),
23947+ format!("{} → {}", step.from_schema, step.to_schema)
23948+ );
23949+ }
23950+ }
23951+ }
23952+ println!();
23953+ }
23954+}
23955+
23956+/// `<program> db` subcommands: with no further argument, launch the TUI
23957+/// explorer; `db info` prints a human-readable report (per-source descriptor,
23958+/// migration chain, row counts); `db dump <out>` snapshots the (live) database
23959+/// to a single binary file (`VACUUM INTO`); `db restore <dump>` replaces the
23960+/// database with a dump file (offline). Returns 1 if handled (caller exits), 0
23961+/// to continue.
23962+#[unsafe(no_mangle)]
2308023963pub extern "C-unwind" fn knot_db_handle(
2308123964 argc: i32,
2308223965 argv: *const *const u8,
@@ -23086,21 +23969,64 @@ pub extern "C-unwind" fn knot_db_handle(
2308623969 if argc < 2 {
2308723970 return 0;
2308823971 }
23089− let arg1 = unsafe {
23090− let ptr = *argv.add(1);
23091− let mut len = 0;
23092− while *ptr.add(len) != 0 {
23093− len += 1;
23094− }
23095− String::from_utf8_lossy(std::slice::from_raw_parts(ptr, len)).to_string()
23096− };
23097−
23972+ let arg1 = unsafe { c_arg(argv, 1) };
2309823973 if arg1 != "db" {
2309923974 return 0;
2310023975 }
23101−
2310223976 let db_path = unsafe { str_from_raw(db_path_ptr, db_path_len) };
23977+ let db = std::path::Path::new(db_path);
23978+ let prog = unsafe { c_arg(argv, 0) };
23979+
23980+ // `./app db dump <out>` / `./app db restore <dump>` — binary snapshot.
23981+ if argc >= 3 {
23982+ match unsafe { c_arg(argv, 2) }.as_str() {
23983+ "dump" => {
23984+ if argc < 4 {
23985+ eprintln!("usage: {} db dump <out>", prog);
23986+ std::process::exit(1);
23987+ }
23988+ let out = unsafe { c_arg(argv, 3) };
23989+ match crate::db_dump::dump_db(db, std::path::Path::new(&out)) {
23990+ Ok(()) => {
23991+ println!("Dumped {} -> {}", db.display(), out);
23992+ return 1;
23993+ }
23994+ Err(e) => {
23995+ eprintln!("db dump: {}", e);
23996+ std::process::exit(1);
23997+ }
23998+ }
23999+ }
24000+ "restore" => {
24001+ if argc < 4 {
24002+ eprintln!("usage: {} db restore <dump>", prog);
24003+ std::process::exit(1);
24004+ }
24005+ let dump = unsafe { c_arg(argv, 3) };
24006+ match crate::db_dump::restore_db(std::path::Path::new(&dump), db) {
24007+ Ok(()) => {
24008+ println!("Restored {} -> {}", dump, db.display());
24009+ return 1;
24010+ }
24011+ Err(e) => {
24012+ eprintln!("db restore: {}", e);
24013+ std::process::exit(1);
24014+ }
24015+ }
24016+ }
24017+ "info" => {
24018+ db_info(db_path);
24019+ return 1;
24020+ }
24021+ other => {
24022+ eprintln!("unknown db subcommand: {}", other);
24023+ eprintln!("usage: {} db [info | dump <out> | restore <dump>]", prog);
24024+ std::process::exit(1);
24025+ }
24026+ }
24027+ }
2310324028
24029+ // `./app db` — the TUI explorer.
2310424030 if let Err(e) = tui::run_db_explorer(db_path) {
2310524031 eprintln!("knot db: {}", e);
2310624032 std::process::exit(1);
@@ -23254,68 +24180,40 @@ fn capitalize(s: &str) -> String {
2325424180/// declarations (`name Text`, `age Int`). The descriptor is the knot record
2325524181/// format: fields separated by 2+ spaces, name and type by a single space.
2325624182/// Handles nested relations (`col Rel {inner}`) and ADT tags.
24183+/// Convert a schema descriptor (`{name Text age Int}`) to knot field
24184+/// declarations (`name Text`, `age (Int 1)`). Fields are split with the
24185+/// single-owner `knot-descriptor` grammar (robust to nested `{..}`/`(..)`),
24186+/// then each field's *type* is re-emitted in descriptor form verbatim — except
24187+/// a bare top-level numeric, which gains the dimensionless unit knot source
24188+/// requires (`Int` → `(Int 1)`). Matches the original hand-rolled splitter's
24189+/// output exactly.
2325724190fn schema_descriptor_to_fields(schema: &str) -> Vec<String> {
23258− // Strip ONE outer brace pair.
2325924191 let t = schema.trim();
23260− let inner = if t.starts_with('{') && t.ends_with('}') {
23261− &t[1..t.len() - 1]
24192+ let parsed = if t.starts_with('{') {
24193+ knot_descriptor::parse(t).ok()
2326224194 } else {
23263− t
24195+ // A bare (braceless) field list, e.g. a ctor payload fragment.
24196+ knot_descriptor::parse(&format!("{{{t}}}")).ok()
24197+ };
24198+ let Some(knot_descriptor::Desc::Record(fields)) = parsed else {
24199+ return Vec::new();
2326424200 };
23265− let inner = inner.trim();
23266− // Split on 2+ spaces (the field separator).
23267− let mut fields = Vec::new();
23268− let mut current = String::new();
23269− let mut depth = 0;
23270− let chars: Vec<char> = inner.chars().collect();
23271− let mut i = 0;
23272− while i < chars.len() {
23273− let c = chars[i];
23274− match c {
23275− '{' => { depth += 1; current.push(c); }
23276− '}' => { depth -= 1; current.push(c); }
23277− '[' => { depth += 1; current.push(c); }
23278− ']' => { depth -= 1; current.push(c); }
23279− ' ' if depth == 0 => {
23280− // 2+ spaces separate fields; a single space is within a field.
23281− let mut j = i;
23282− while j < chars.len() && chars[j] == ' ' {
23283− j += 1;
23284− }
23285− if j - i >= 2 {
23286− // A field boundary.
23287− if !current.trim().is_empty() {
23288− fields.push(current.trim().to_string());
23289− }
23290− current = String::new();
23291− i = j;
23292− continue;
23293− }
23294− current.push(c);
23295− }
23296− _ => current.push(c),
23297− }
23298− i += 1;
23299− }
23300− if !current.trim().is_empty() {
23301− fields.push(current.trim().to_string());
23302− }
23303− // The descriptor stores `Int`/`Float` without a unit. Knot requires one —
23304− // emit `Int 1`/`Float 1` (dimensionless) for a bare numeric type.
2330524201 fields
2330624202 .into_iter()
23307− .map(|f| {
23308− let parts: Vec<&str> = f.splitn(2, ' ').collect();
23309− if parts.len() == 2 {
23310− let (name, ty) = (parts[0], parts[1]);
23311− match ty {
23312− "Int" => format!("{} (Int 1)", name),
23313− "Float" => format!("{} (Float 1)", name),
23314− _ => f,
24203+ .map(|(name, ty)| {
24204+ let ty_str = match ty {
24205+ // Bare numerics need a dimensionless unit in knot source.
24206+ knot_descriptor::Desc::Scalar(knot_descriptor::Scalar::Int) => {
24207+ "(Int 1)".to_string()
2331524208 }
23316− } else {
23317− f
23318− }
24209+ knot_descriptor::Desc::Scalar(knot_descriptor::Scalar::Float) => {
24210+ "(Float 1)".to_string()
24211+ }
24212+ // Everything else round-trips to the descriptor spelling
24213+ // (`(Rel T)`, `(A | B)`, nested records) verbatim.
24214+ other => knot_descriptor::emit(&other),
24215+ };
24216+ format!("{} {}", name, ty_str)
2331924217 })
2332024218 .collect()
2332124219}
@@ -23335,51 +24233,39 @@ fn qualify_adt_ctor(value: &str, type_name: &str) -> String {
2333524233}
2333624234
2333724235/// Convert an ADT schema descriptor (`(Circle{radius Int} | Point)`) to knot
23338−/// constructor declarations (`Circle {radius (Int 1)}`, `Point {}`).
24236+/// constructor declarations (`Circle {radius (Int 1)}`, `Point {}`), using the
24237+/// single-owner `knot-descriptor` grammar.
2333924238fn schema_descriptor_to_adt_ctors(schema: &str) -> Vec<String> {
23340− // Strip the outer parens and split on ` | `.
23341− let inner = schema.trim().trim_start_matches('(').trim_end_matches(')').trim();
23342− let mut ctors = Vec::new();
23343− let mut current = String::new();
23344− let mut depth = 0;
23345− let chars: Vec<char> = inner.chars().collect();
23346− let mut i = 0;
23347− while i < chars.len() {
23348− let c = chars[i];
23349− match c {
23350− '{' => { depth += 1; current.push(c); }
23351− '}' => { depth -= 1; current.push(c); }
23352− '|' if depth == 0 => {
23353− if !current.trim().is_empty() {
23354− ctors.push(adt_ctor_to_knot(current.trim()));
23355− }
23356− current = String::new();
23357− i += 1;
23358− continue;
23359− }
23360− _ => current.push(c),
23361− }
23362− i += 1;
23363− }
23364− if !current.trim().is_empty() {
23365− ctors.push(adt_ctor_to_knot(current.trim()));
23366− }
23367− ctors
24239+ let Ok(knot_descriptor::Desc::Variant(ctors)) = knot_descriptor::parse(schema.trim())
24240+ else {
24241+ return Vec::new();
24242+ };
24243+ ctors.iter().map(|(name, fields)| adt_ctor_to_knot(name, fields)).collect()
2336824244}
2336924245
23370−/// Convert one ADT constructor descriptor (`Circle{radius Int}` or `Point`) to
23371−/// the knot form (`Circle {radius (Int 1)}` or `Point {}`).
23372−fn adt_ctor_to_knot(ctor: &str) -> String {
23373− let ctor = ctor.trim();
23374− if let Some(brace) = ctor.find('{') {
23375− let name = ctor[..brace].trim();
23376− let fields_str = &ctor[brace..]; // `{radius Int}`
23377− let fields = schema_descriptor_to_fields(fields_str);
23378− format!("{} {{{}}}", name, fields.join(" "))
23379− } else {
24246+/// Convert one ADT constructor (name + payload fields) to the knot form
24247+/// (`Circle {radius (Int 1)}` or `Point {}`).
24248+fn adt_ctor_to_knot(name: &str, fields: &[(String, knot_descriptor::Desc)]) -> String {
24249+ if fields.is_empty() {
2338024250 // A nullary constructor.
23381− format!("{} {{}}", ctor)
24251+ return format!("{} {{}}", name);
2338224252 }
24253+ let specs: Vec<String> = fields
24254+ .iter()
24255+ .map(|(n, t)| {
24256+ let ty_str = match t {
24257+ knot_descriptor::Desc::Scalar(knot_descriptor::Scalar::Int) => {
24258+ "(Int 1)".to_string()
24259+ }
24260+ knot_descriptor::Desc::Scalar(knot_descriptor::Scalar::Float) => {
24261+ "(Float 1)".to_string()
24262+ }
24263+ other => knot_descriptor::emit(other),
24264+ };
24265+ format!("{} {}", n, ty_str)
24266+ })
24267+ .collect();
24268+ format!("{} {{{}}}", name, specs.join(" "))
2338324269}
2338424270
2338524271fn generate_openapi(name: &str, table: &RouteTable) -> String {
@@ -24312,6 +25198,7 @@ mod extract_source_tests {
2431225198 env,
2431325199 source: intern_str(source),
2431425200 extract_source: None,
25201+ code: std::ptr::null(),
2431525202 })))
2431625203 }
2431725204 fn func_full(source: &str, env: *mut Value, xsrc: &str) -> *mut Value {
@@ -24320,6 +25207,7 @@ mod extract_source_tests {
2432025207 env,
2432125208 source: intern_str(source),
2432225209 extract_source: Some(intern_str(xsrc)),
25210+ code: std::ptr::null(),
2432325211 })))
2432425212 }
2432525213
@@ -24465,6 +25353,7 @@ mod extract_source_tests {
2446525353 fn_ptr: std::ptr::null(),
2446625354 env,
2446725355 source: intern_str(source),
25356+ code: std::ptr::null(),
2446825357 })))
2446925358 }
2447025359 #[test]
@@ -24514,6 +25403,7 @@ mod show_tests {
2451425403 env,
2451525404 source: intern_str(source),
2451625405 extract_source: None,
25406+ code: std::ptr::null(),
2451725407 })))
2451825408 }
2451925409 fn io(source: &str) -> *mut Value {
@@ -24521,6 +25411,7 @@ mod show_tests {
2452125411 fn_ptr: std::ptr::null(),
2452225412 env: std::ptr::null_mut(),
2452325413 source: intern_str(source),
25414+ code: std::ptr::null(),
2452425415 })))
2452525416 }
2452625417
@@ -24558,6 +25449,7 @@ mod show_tests {
2455825449 env: alloc(Value::Unit),
2455925450 source: intern_str("Nothing"),
2456025451 extract_source: Some(intern_str("Maybe.Nothing {}")),
25452+ code: std::ptr::null(),
2456125453 })));
2456225454 assert_eq!(format_value(f), "Nothing");
2456325455 }
@@ -24684,3 +25576,126 @@ mod show_tests {
2468425576 );
2468525577 }
2468625578}
25579+
25580+#[cfg(test)]
25581+mod compile_containment_tests {
25582+ //! `base.compile` runs in the host's process; a panic in compilation or the
25583+ //! generated snippet must surface as an Err, never unwind across `extern
25584+ //! "C"`. These exercise the shared containment point both `knot_compile_impl`
25585+ //! entry points delegate to.
25586+ use super::*;
25587+
25588+ /// Out-param slots for a contained run, mirroring the FFI caller.
25589+ struct Outs {
25590+ ty: *mut u8,
25591+ ty_len: usize,
25592+ rels: *mut u8,
25593+ rels_len: usize,
25594+ err: *mut u8,
25595+ err_len: usize,
25596+ }
25597+ impl Outs {
25598+ fn new() -> Self {
25599+ Outs {
25600+ ty: std::ptr::null_mut(),
25601+ ty_len: 0,
25602+ rels: std::ptr::null_mut(),
25603+ rels_len: 0,
25604+ err: std::ptr::null_mut(),
25605+ err_len: 0,
25606+ }
25607+ }
25608+ unsafe fn init(&mut self) {
25609+ unsafe {
25610+ compile_out_params_init([
25611+ (&mut self.ty, &mut self.ty_len),
25612+ (&mut self.rels, &mut self.rels_len),
25613+ (&mut self.err, &mut self.err_len),
25614+ ]);
25615+ }
25616+ }
25617+ fn err_string(&self) -> Option<String> {
25618+ if self.err.is_null() {
25619+ return None;
25620+ }
25621+ let bytes = unsafe { std::slice::from_raw_parts(self.err, self.err_len) };
25622+ let s = String::from_utf8_lossy(bytes).into_owned();
25623+ unsafe { libc::free(self.err as *mut c_void) };
25624+ Some(s)
25625+ }
25626+ }
25627+
25628+ #[test]
25629+ fn success_writes_out_params_and_returns_value() {
25630+ let mut o = Outs::new();
25631+ unsafe { o.init() };
25632+ let sentinel = 0xdeadbeefusize as *mut Value;
25633+ let v = unsafe {
25634+ run_compile_contained(
25635+ std::ptr::null_mut(),
25636+ &mut o.ty,
25637+ &mut o.ty_len,
25638+ &mut o.rels,
25639+ &mut o.rels_len,
25640+ &mut o.err,
25641+ &mut o.err_len,
25642+ |_| Some(CompileOutcome {
25643+ value: sentinel,
25644+ ty: Some("Int".to_string()),
25645+ relations: vec!["a\t{..}".to_string()],
25646+ }),
25647+ )
25648+ };
25649+ assert_eq!(v, sentinel);
25650+ assert!(!o.ty.is_null(), "ty written");
25651+ assert!(!o.rels.is_null(), "relations written");
25652+ assert!(o.err.is_null(), "no error on success");
25653+ unsafe {
25654+ libc::free(o.ty as *mut c_void);
25655+ libc::free(o.rels as *mut c_void);
25656+ }
25657+ }
25658+
25659+ #[test]
25660+ fn clean_compile_error_returns_null() {
25661+ let mut o = Outs::new();
25662+ unsafe { o.init() };
25663+ let v = unsafe {
25664+ run_compile_contained(
25665+ std::ptr::null_mut(),
25666+ &mut o.ty,
25667+ &mut o.ty_len,
25668+ &mut o.rels,
25669+ &mut o.rels_len,
25670+ &mut o.err,
25671+ &mut o.err_len,
25672+ |_| None,
25673+ )
25674+ };
25675+ assert!(v.is_null(), "compile error returns null");
25676+ }
25677+
25678+ #[test]
25679+ fn panic_is_contained_and_surfaced_as_err() {
25680+ let mut o = Outs::new();
25681+ unsafe { o.init() };
25682+ let v = unsafe {
25683+ run_compile_contained(
25684+ std::ptr::null_mut(),
25685+ &mut o.ty,
25686+ &mut o.ty_len,
25687+ &mut o.rels,
25688+ &mut o.rels_len,
25689+ &mut o.err,
25690+ &mut o.err_len,
25691+ |_| -> Option<CompileOutcome> { panic!("boom in codegen") },
25692+ )
25693+ };
25694+ assert!(v.is_null(), "panic returns null, does not unwind");
25695+ let err = o.err_string().expect("panic message written to out_err");
25696+ assert!(
25697+ err.contains("compile panicked") && err.contains("boom in codegen"),
25698+ "panic payload surfaced: {err}"
25699+ );
25700+ }
25701+}