From 8c640a262969ef44cd8bc0e0abe95e2a54f4c3f5 Mon Sep 17 00:00:00 2001 From: Marcos Magueta Date: Thu, 5 Mar 2026 23:42:15 -0300 Subject: ocaml re-migration --- docs/reliability_roadmap.org | 223 ------------------------------------------- 1 file changed, 223 deletions(-) delete mode 100644 docs/reliability_roadmap.org (limited to 'docs/reliability_roadmap.org') diff --git a/docs/reliability_roadmap.org b/docs/reliability_roadmap.org deleted file mode 100644 index d47a00e..0000000 --- a/docs/reliability_roadmap.org +++ /dev/null @@ -1,223 +0,0 @@ -#+TITLE: Sakura Reliability Roadmap (Precise) - -* Scope - -Build Sakura into a correct and efficient first-order predicate logic (FOPL) -relational algebra engine where relations are first-class values with: - -- *Extension* :: denotation as a tuple set (finite stored set or generated stream) -- *Intension* :: logical meaning (schema + normalized constraints + derivation) - -* Formal Position on Issue =#48= - -Issue =#48= is *not* semantic redundancy. - -- =constraint:create_1op/3= is an attribute-constraint *definition* constructor. -- =constraint:add_attribute_constraint/3= is a relation-level *binding* operation. - -They are distinct layers. The defect is API ambiguity and weak invariants. - -- [ ] Require key/record coherence: key =:= =#attribute_constraint.attribute=. -- [ ] Provide one canonical "declare and bind" path to prevent invalid states. - -* Relation Contract (Non-Negotiable) - -** C1 Representation Contract - -- [ ] Exactly one extension mode per relation: - - finite stored: =tree =/= undefined= and =generator= is factory for tree iterator - - generated: =tree == undefined= and =generator= is mandatory -- [ ] Intension is always =#relation_constraints{}=, never raw =#{}=. -- [ ] =membership_criteria= is either removed (Issue =#47=) or treated as a derived cache from constraints, never a second source of truth. - -** C2 Identity Contract - -- [ ] Relation hash function is canonical and identical across all mutation paths. -- [ ] Hash input includes the same semantic fields in the same order, with explicit versioned format. -- [ ] Any relation update that changes intension or extension must change hash deterministically. - -** C3 Algebraic Closure Contract - -- [ ] Every algebra operator returns a relation with valid extension + intension. -- [ ] Constraint propagation rules are explicit and tested per operator. -- [ ] Result schema and constraints are compatible and normalized. - -* Current Critical Correctness Gaps - -- [ ] Non-canonical relation hash updates in =src/operations.erl=. -- [ ] Split semantics between =constraints= and =membership_criteria=. -- [ ] Mixed constraints shapes (=#relation_constraints{}= and raw maps). -- [ ] Placeholder substitution search in =constraint:find_satisfying_substitution/4=. -- [ ] Derived infinite/finite relations not consistently honoring constraints (=#13=, =#14=). -- [ ] Dual planner paths with mismatched behavior in =src/query_planner.erl=. -- [ ] Iterator close protocol mismatch (=stop= vs =close= forms). -- [ ] XML schema endpoint assumes map constraints and crashes. - -* Workstreams - -** W0 Safety and Determinism (P0) - -- [ ] Fix =xml_server= SCHEMA serialization for record constraints (=src/xml_server.erl=). -- [ ] Replace ad-hoc prints with =logger= (=#39=), remove debug output in constraint lookup. -- [ ] Make =repl:start/0= non-destructive; add explicit destructive reset command. -- [ ] Standardize iterator termination protocol across all iterator loops. -- [ ] Normalize constraints type in all constructors (planner/operators/operations). - -*Acceptance criteria* - -- [ ] No SCHEMA crash under any built-in relation set. -- [ ] No unsolicited stdout noise during normal queries. -- [ ] No relation loss on default REPL startup. -- [ ] No orphan iterator processes after collect/close paths. - -** W1 FOPL Semantics Core (P1) - -- [ ] Implement full variable binding search and substitution for partial constraints. -- [ ] Define and enforce formula AST for =and/or/not/exists/forall=. -- [ ] Separate logical membership from physical storage existence checks. -- [ ] Decide and document two-valued logic policy (no NULL) or explicit three-valued policy. -- [ ] Complete 1OPiC modeling (=#42=) and baseline 1OP constraints (=#28=). - -*Acceptance criteria* - -- [ ] Quantified constraints produce correct truth values on finite fixtures. -- [ ] Membership equivalence tests pass for stored vs generated extension of same intension. -- [ ] Constraint violation diagnostics identify failing attribute/formula branch. - -** W2 Constraint Model Consistency (P1) - -- [ ] Resolve =#48= with scope-safe API (define vs bind) and strict invariant checks. -- [ ] Implement relation creation with constraints in one call (=#15=). -- [ ] Decide fate of =membership_criteria= (=#47=): remove or strict derivation cache. -- [ ] Add migration helper to convert legacy constraint maps to =#relation_constraints{}=. -- [ ] Establish extension/intension introspection API for debugging and tooling. - -*Acceptance criteria* - -- [ ] No public path can construct mismatched attribute constraint key/record pairs. -- [ ] New relation creation API supports schema + constraints atomically. -- [ ] Intension is serialized/deserialized in one normalized shape everywhere. - -** W3 Planner Unification (P1) - -- [ ] Remove dual compile paths; keep one logical -> rewrite -> physical pipeline. -- [ ] Add semantic validation (schema compatibility, attribute existence, constraint shape). -- [ ] Add rewrite rules: projection pruning, predicate pushdown, limited join reordering. -- [ ] Add typed planner errors for REPL/XML consumers. - -*Acceptance criteria* - -- [ ] Same query plan always yields same output schema and row semantics across interfaces. -- [ ] Planner rejects invalid plans with stable machine-readable reasons. - -** W4 Algebra Completeness and Performance (P2) - -- [ ] Implement union/intersection/difference with strict compatibility checks. -- [ ] Implement semijoin/antijoin/division. -- [ ] Add hash join and merge join; keep nested loop fallback. -- [ ] Enforce bounded execution preconditions for blocking operators over infinite relations. -- [ ] Improve tuple hash retrieval path performance (=#7=). - -*Acceptance criteria* - -- [ ] Algebra law regression tests pass for finite relations (where laws apply). -- [ ] Join strategy selection is observable and benchmarked. -- [ ] Infinite + blocking plans fail fast with actionable diagnostics unless bounded. - -** W5 Versioning and Updatable Views (P2) - -- [ ] Implement branch metadata and lineage (=#43=). -- [ ] Implement fast-forward merge semantics and conflict checks (=#44=). -- [ ] Implement provenance-safe updatable ephemeral views (=#26=). - -*Acceptance criteria* - -- [ ] Branch/merge operations are deterministic and test-covered. -- [ ] Updatable views reject ambiguous write-back paths. - -** W6 Interfaces and Hardening (P2) - -- [ ] Replace XML =erl_eval= execution with safe parsed DSL/AST. -- [ ] Version protocol responses and provide structured errors. -- [ ] Add explain-analyze metrics (rows, time, strategy, spills/materialization). -- [ ] Add visualizer mode for relation semantics (schema, constraints, lineage, extension mode). -- [ ] Integrate or deprecate =relation.erl= helper model. - -*Acceptance criteria* - -- [ ] No arbitrary code execution path through external query interface. -- [ ] Interface responses are stable under malformed input and concurrency. - -* GitHub Issue Mapping - -** Core reliability and semantics - -- [ ] =#39= logging -- [ ] =#15= define constraints at finite relation creation -- [ ] =#14= derived finite from infinite honors/inherits constraints -- [ ] =#13= derived infinite honors constraints -- [ ] =#7= tuple hash retrieval performance - -** Constraint/data model - -- [ ] =#48= clarify define/bind API and enforce invariants -- [ ] =#47= remove/replace membership_criteria split -- [ ] =#42= proper 1OPiC model -- [ ] =#28 #29 #30 #31= 1st/2nd/3rd/4th order property constraints - -** Versioning and updates - -- [ ] =#43= branching -- [ ] =#44= fast-forward merge -- [ ] =#26= updatable views - -** Optional research tracks - -- [ ] =#45= nullary relations vs booleans -- [ ] =#40= state monad -- [ ] =#41= C node for hot loops -- [ ] =#19= chessboard integration - -* Verification Matrix (Must Exist in CI) - -- [ ] Unit tests: constraints AST eval, membership semantics, hash determinism -- [ ] Property tests: algebra laws, hash stability, propagation invariants -- [ ] Integration tests: REPL flows, XML QUERY/NEXT/CLOSE/SCHEMA, malformed inputs -- [ ] Performance tests: join algorithms, bounded infinite queries, Merkle hash retrieval -- [ ] Concurrency tests: iterator lifecycle and server session cleanup - -* Milestones and Exit Criteria - -** M1 (Safety Baseline) - -- Deliver W0 -- Close target issues: =#39 #15 #14 #13 #7= -- Exit: no destructive default startup, no XML schema crash, no protocol-level iterator leaks - -** M2 (Semantic Correctness) - -- Deliver W1 + W2 -- Close target issues: =#48 #47 #42 #28= (with foundations for =#29 #30 #31=) -- Exit: extension/intension invariants hold across create/query/derive flows - -** M3 (Planner and Performance) - -- Deliver W3 + W4 -- Exit: unified planner, bounded infinite behavior, measurable join improvements - -** M4 (Versioned Workflows) - -- Deliver W5 + W6 -- Close target issues: =#43 #44 #26= -- Exit: deterministic branch/merge and safe updatable views with stable interfaces - -* Execution Order - -1. W0 Safety and Determinism -2. W1 FOPL Semantics Core -3. W2 Constraint Model Consistency -4. W3 Planner Unification -5. W4 Algebra Completeness and Performance -6. W5 Versioning and Updatable Views -7. W6 Interfaces and Hardening -8. Optional research tracks (=#45 #40 #41 #19=) -- cgit v1.2.3