Coln query/flir query program mapping

packages/coln-flir-rs/Cargo.toml

@@ -12,8 +12,14 @@ exclude = ["/.gitignore"]
 
 [lib]
 
+[features]
+test-utils = []
+
 [dependencies]
-serde = { version = "1.0", features = ["derive"] }
+serde = { workspace = true }
+serde_json = { workspace = true }
 
 [dev-dependencies]
-serde_json = "1.0"
+# This is a self-referential dev-dependency to have the feature-gated
+# test-utils be available in this crate's integration tests, too.
+coln-flir-rs = { path = ".", features = ["test-utils"] }

packages/coln-flir-rs/src/ir/mod.rs

@@ -16,8 +16,17 @@ pub type QName = Vec<String>;
 #[serde(transparent)]
 pub struct Path(pub Vec<QName>);
 
-type ColName = Path;
-pub type FId = i64;
+/// A column name is given by a [`Path`].
+pub type ColName = Path;
+
+/// An index into the [`varNames`](Rule::var_names) and
+/// [`varTypes`](Rule::var_types) arrays of a [`Rule`].
+///
+/// Note: An `FId` in `coln-compiler`.
+pub type VarIdx = u64;
+
+/// An index into a relation's physical [`columns`](Schema::columns).
+pub type ColumnIdx = u64;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BuiltinTy {
@@ -62,9 +71,10 @@ impl<'de> Deserialize<'de> for BuiltinTy {
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "tag", rename_all = "camelCase")]
 pub enum ColType {
-    RowId {
-        path: Path,
-    },
+    /// A foreign key into another table by referencing its _row id_ through
+    /// the provided path.
+    RowId { path: Path },
+    /// A data column with the scalar type [`BuiltinTy`].
     #[serde(rename = "builtin")]
     BuiltinTy {
         #[serde(rename = "type")]
@@ -89,8 +99,11 @@ pub enum IndexMethod {
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "tag", rename_all = "camelCase")]
 pub enum EntityVariant {
+    /// A base table of the extensional database (EDB).
     Table,
+    /// A derived view of the intensional database (IDB).
     View(Materialization),
+    /// Tell `coln-store` to create an index and possibly hint to `coln-query`.
     Index {
         method: IndexMethod,
         columns: Vec<ColName>,
@@ -105,15 +118,25 @@ pub struct ColumnEntry {
     pub col_type: ColType,
 }
 
-// This is really Entity on the Haskell IR side, but I feel schema matches it better
+/// Describes a schema of a relation.
+///
+/// Note: An `Entity` in `coln-compiler`.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Schema {
     pub entity_variant: EntityVariant,
+    /// The columns of the table in their physical order.
     pub columns: Vec<ColumnEntry>,
+    /// A `None` indicates that there is no primary key. `Some(vec![])` means
+    /// that there is at most one row in the table. `Some(vec![ColA, ColB])`
+    /// encodes a compound primary key consisting of the columns `ColA` and
+    ///  `ColB`.
+    ///
+    /// At the moment there is only support for a single (compound) primary key.
     pub primary_key: Option<Vec<ColName>>,
 }
 
+/// A literal expression.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "tag", rename_all = "lowercase")]
 pub enum Lit {
@@ -127,65 +150,106 @@ pub enum Lit {
 #[serde(tag = "tag", rename_all = "lowercase")]
 pub enum Term {
     Lit { lit: Lit },
-    Var { index: FId },
+    Var { index: VarIdx },
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ValueEntry {
-    pub column: i64,
+    pub column: ColumnIdx,
     pub term: Term,
 }
 
+/// An [`Atom`] references an entity (a relation or a table) to bring some of
+/// its fields into the scope of a [`Rule`].
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Atom {
+    /// The "name" of the entity being referenced by this [`Atom`].
     pub entity: Path,
+    /// To bring the `row_id` of the [`Entity`](Self::entity) into scope.
+    ///
+    /// Note: A [`Some(Term::Lit)`](Term::Lit) does not make sense in this
+    /// context, as we do not support a row id literal at the moment, I suppose.
     pub row_id: Option<Term>,
+    /// To bring some columns of the [`Entity`](Self::entity) into scope.
     pub values: Vec<ValueEntry>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(tag = "tag", rename_all = "lowercase")]
 pub enum Prop {
-    Atom { atom: Atom },
-    Eq { left: Term, right: Term },
+    Atom {
+        atom: Atom,
+    },
+    Eq {
+        #[serde(flatten)]
+        equality: Equality,
+    },
 }
 
+/// An equality condition between the left and the right term, that is,
+/// we assert `left == right`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Equality {
+    pub left: Term,
+    pub right: Term,
+}
+
+#[derive(Debug, Copy, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub enum RuleVariant {
+    /// _Chased_ rules are not yet fully alive but become relevant once initial
+    /// models land.
     Chased,
+    /// Violations of _enforced_ rules cause a transaction to abort.
     Enforced,
+    /// Violations of _monitored_ rules are just reported back to the user but
+    /// still allow a transaction to commit.
     Monitored,
 }
 
+/// A `Rule` is an implication and must be true in all valid states of
+/// `coln-store` and `coln-query`.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Rule {
     pub rule_variant: RuleVariant,
+    /// Assigns some names to the variables the rule binds.
+    ///
+    /// Note: Must be of the same arity as [`Self::var_types`].
     pub var_names: Vec<ColName>,
+    /// Tells the types of the variables the rule binds.
+    ///
+    /// Note: Must be of the same arity as [`Self::var_names`].
     pub var_types: Vec<ColType>,
+    /// The left-hand side of the implication.
     pub antecedents: Vec<Prop>,
+    /// The right-hand side of the implication.
     pub consequents: Vec<Prop>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TableEntry {
+    /// The "name" of the table.
     pub path: Path,
     #[serde(rename = "value")]
     pub table: Schema,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct RuleEntry {
+    /// The "name" of the rule.
     pub path: Path,
     #[serde(rename = "value")]
     pub rule: Rule,
 }
 
+/// The top-level type of a flattened realm and the starting point of the FLIR.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct FlatRealm {
+    /// The tables of the flattened realm.
     #[serde(rename = "entities")]
     pub tables: Vec<TableEntry>,
+    /// The rules (laws) of the flattened realm.
     pub rules: Vec<RuleEntry>,
 }

packages/coln-flir-rs/src/ir/path.rs

@@ -19,6 +19,25 @@ impl Deref for Path {
     }
 }
 
+impl Path {
+    pub fn append(mut self, name: &str) -> Self {
+        self.0.push(vec![name.to_string()]);
+        self
+    }
+}
+
+impl From<Path> for String {
+    fn from(value: Path) -> Self {
+        value.to_string()
+    }
+}
+
+impl From<&Path> for String {
+    fn from(value: &Path) -> Self {
+        value.to_string()
+    }
+}
+
 impl Display for Path {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         for (i, qname) in self.0.iter().enumerate() {

packages/coln-flir-rs/src/lib.rs

@@ -3,3 +3,6 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 pub mod ir;
+pub mod schema;
+#[cfg(feature = "test-utils")]
+pub mod test_utils;