From baca3a79cded23329ba8555afefb5590b679c955 Mon Sep 17 00:00:00 2001 From: Marcos Magueta Date: Fri, 6 Feb 2026 20:18:17 -0300 Subject: Fix comparison relation order, rebranding & roadmap (#50) --- README.org | 255 ++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 136 insertions(+), 119 deletions(-) (limited to 'README.org') diff --git a/README.org b/README.org index 2cfebe7..cf42f5c 100644 --- a/README.org +++ b/README.org @@ -1,122 +1,139 @@ -#+TITLE: Domino +#+TITLE: Sakura * About -Domino is an *Extended Relational Database Engine* based on E. F. Codd's -RM/T (Relational Model/Tasmania, 1979). It implements relational algebra -in its strict, theoretical form while extending it to capture more of the -meaning of data through semantic modeling concepts. - -** Theoretical Foundation - -The engine builds upon two seminal works by E. F. Codd: - -1. *"A Relational Model of Data for Large Shared Data Banks"* (1970) — - The foundation of relational theory -2. *"Extending the Database Relational Model to Capture More Meaning"* (1979) — - RM/T extensions for semantic modeling - -** Core Principles - -A relation is modeled as a set of tuples, each tuple being a set of -attributes. Each attribute is a pairing of a name with a value drawn -from a domain. All operations are defined on entire relations as sets, -with no recourse to the compromises typical of SQL or other practical -implementations. - -** What Makes Domino Extended? - -*** Content-Addressed Storage -Entities are identified by system-controlled *surrogates* — cryptographic -hashes (SHA-256) that provide permanent, unique identification. This -enables: -- Automatic deduplication -- Immutable versioning -- Merkle tree-based diffing -- Distributed synchronization - -*** Entity Types (RM/T) -Three fundamental entity classifications: -- *Kernel Entities* — Independent entities (e.g., Employee, Supplier) -- *Characteristic Entities* — Multi-valued properties (e.g., Job History) -- *Associative Entities* — Relationships as first-class entities - -*** Four Dimensions of Molecular Semantics -1. *Cartesian Aggregation* — Properties, characteristics, and associations -2. *Generalization* — Subtyping and inheritance hierarchies -3. *Cover Aggregation* — Collections and groupings (e.g., teams, convoys) -4. *Event Precedence* — Temporal ordering of events - -*** Immutable Architecture -All data structures are immutable. Every modification creates a new version -with a new hash, enabling: -- Temporal queries -- Audit trails -- Safe concurrent access -- Version control for data - -** Current Implementation - -*** What's Built -- Content-addressed storage with SHA-256 surrogates -- E-relations for entity type management -- P-relations for immediate properties -- Merkle tree integration for efficient versioning -- Volcano iterator model for lazy evaluation -- Transactional ACID operations via Mnesia -- Comprehensive EUnit test suite - -*** What's Planned -- Full relational algebra operators (σ, π, ⋈, ∪, ∩, −) -- Characteristic entities and CG-relation -- Associative entities and AG-relation -- Generalization hierarchies (UGI/AGI) -- Cover aggregation (KG-relation) -- Event precedence (US/AS/UP/AP) -- Extended operators (OUTER JOIN, MAYBE operators) -- RM/T catalog relations -- Null value handling (three-valued logic) -- Infinite relations (aleph₀) -- High-level query language - -** Design Philosophy - -The engine is intended as a study in correctness and semantic richness: -each operation is executed in a manner consistent with the classical -definition of relational algebra, while the RM/T extensions provide a -framework for capturing more meaning about entities, their properties, -and their relationships. - -It is a platform for exploring the consequences of relational theory in -a low-level programming context, providing both a tool for experimentation -and a concrete realization of Codd's vision for semantic data modeling. - -** Why RM/T? - -Most database systems today are compromises — they sacrifice theoretical -purity for practical performance. Domino takes a different approach: -implement the theory *correctly* first, then optimize. RM/T provides: - -- *Atomic Semantics* — What constitutes a minimal meaningful unit? -- *Molecular Semantics* — What larger clusters constitute meaningful units? -- *Systematic Design* — Principled approach to database schema design -- *Intelligent Behavior* — System understands more about data meaning - -** Documentation - -See =docs/= directory: -- =code.org= — Comprehensive code documentation -- =features.org= — Feature roadmap and RM/T extensions -- =ci.org= — Continuous integration setup - -** References - -- Codd, E. F. (1970). "A Relational Model of Data for Large Shared Data Banks." - /Communications of the ACM/ 13(6): 377-387. -- Codd, E. F. (1979). "Extending the Database Relational Model to Capture More Meaning." - /ACM Transactions on Database Systems/ 4(4): 397-434. -- Date, C. J. & Darwen, H. "Foundation for Future Database Systems: The Third Manifesto." - -** License - -See LICENSE file. +Sakura is a semantic-relational algebra engine inspired by +E. F. Codd's RM/T and D. McGoveran's (as understood by Fabian Pascal) +SRDM. It models relations in both intension and extension, providing +their manipulation as first-class elements of an algebra. + +* Motivation + +We believe the relational model was not ever fully implemented. The +fundamental necessity of expressing intent and binding meaning +enclosed to a conceptual model in data is seldom achieved by any +self-claimed relational database vendor. The emergence of different +physically concerned paradigms in the industry demonstrate not only a +large scale amnesia about fundamentals, but also a lethal +manifestation of problems that should not exist otherwise. The +relational data model as an applied theory is an universally rich and +concrete approach to reality that bases itself greatly in +moderate-realism applied to mathematics, as described in =An +Aristotelian Realist Philosophy of Mathematics: Mathematics as the +Science of Quantity and Structure= by J. Franklin. We believe that +unleashing the full potential of the relational model as refined over +the years despite overwhelming disregard of the industry as a whole, +will promote efficiency to a new scale never seen, that was very much +so cut short by relational pretenders and theoretically unsound +approaches. Our goal is to eliminate the application-database +distinction, while maintaining a clear separation between a first +order predicate logic algebra engine and a higher order predicate +logic decision engine (application) via an embedded data sublanguage +with Sakura as a possible auxiliary runtime. + +* Current State + +** What Works Today + +- Base finite relations: create, insert, retract, clear +- Built-in immutable/generated domains on database creation: + =integer=, =natural=, =rational=, =string=, =atom=, =term= +- Query DSL in =query_planner= and =repl=: + - base relation scan (using relation atom) + - =select=, =project=, =join=, =theta_join=, =sort=, =take=, =rename= + - =materialize= (plan-level, with caveats) +- Volcano-style iterator execution model (process-per-operator) +- Visual output modes in =visualizer= (table/tree/nested views) +- XML TCP server protocol commands: =QUERY=, =NEXT=, =CLOSE= + +** Known Gaps / Reliability Risks + +- Lack of constraints greater than 1OPs; +- =repl:start/0= is destructive: it calls =main:setup/0=, which recreates schema; +- =xml_server= =SCHEMA= path is currently fragile with constraints representation; +- Constraint/intension representation is not yet fully normalized across modules; +- Planner contains dual compilation styles (iterator path + relation path); +- Blocking operators (for example =sort=) over infinite relations can time out unless bounded with =take= first; +- There is currently no substantial automated test suite in-repo despite CI hooks; + +See =docs/reliability_roadmap.org= for the detailed remediation plan. + +* Architecture (High Level) + +- =src/operations.erl= :: core storage/versioning and iterator primitives +- =src/constraint.erl= :: domain constraints, inference, validation +- =src/generators.erl= :: infinite relation generators +- =src/relational_operators.erl= :: pure relation-to-relation algebra operators +- =src/query_planner.erl= :: tuple DSL parsing/validation/execution planning +- =src/repl.erl= :: shell-facing query convenience API +- =src/xml_server.erl= :: TCP/XML query interface +- =src/visualizer.erl= :: renderers for result tuples + +Data model records are defined in =include/operations.hrl=. + +* Query DSL + +Plans are Erlang tuples: + +- base relation: =employees= +- selection: ={select, employees, fun(T) -> maps:get(age, T) > 30 end}= +- projection: ={project, employees, [name, age]}= +- equijoin: ={join, employees, departments, dept_id}= +- theta join: ={theta_join, Left, Right, Pred2}= +- sort: ={sort, Plan, Comparator2}= +- take: ={take, Plan, N}= +- rename: ={rename, old_attr, new_attr, Plan}= + +* Running + +** Compile + +#+begin_src sh +rebar3 compile +#+end_src + +** REPL + +#+begin_src erlang +repl:start(). +DB = repl:example_db(). +repl:q(DB, employees). +repl:q(DB, {take, {sort, employees, + fun(A,B) -> maps:get(age,A) =< maps:get(age,B) end}, 3}). +#+end_src + +** XML Server (manual) + +Start server from Erlang shell, then send line commands over TCP: + +- =QUERY = +- =NEXT = +- =CLOSE = + +* Design Intent + +Sakura aims to treat relations as algebraic manipulation units with both: + +- extension (actual tuples, finite or generated) +- intension (schema + constraints + derivation meaning) + +The current engine already exposes the extension side robustly for +many operations, despite the lack of constraints greater than 1OP. +The main active work is making intension handling fully consistent and +reliable across planners/operators/protocols. + +* Roadmap and Docs + +- =docs/reliability_roadmap.org= :: precise reliability + correctness roadmap +- =docs/code.org= :: code-oriented notes +- =docs/features.org= :: feature notes (may contain older planning context) +- =docs/constraints.org= :: constraint model notes + +* References + +- Codd, E. F. (1970), "A Relational Model of Data for Large Shared Data Banks" +- Codd, E. F. (1979), "Extending the Database Relational Model to Capture More Meaning" + +* License + +See =LICENSE=. -- cgit v1.2.3