this repo has no description
more
+134
-13
+134
-13
jmap/CLAUDE.md
+134
-13
jmap/CLAUDE.md
···
134
134
let query = Jmap_email_query.query () |> with_account id |> ...
135
135
```
136
136
137
-
## 3. **Function Usage Hierarchy** ⬆️
137
+
## 3. **Layer Responsibilities and Dependencies** ⬆️
138
+
139
+
Each layer has distinct responsibilities and MUST NOT depend on layers above it:
138
140
139
-
Each layer MUST use functions from the layer immediately below:
141
+
### **jmap-sigs** (Pure Interface Layer)
142
+
- **Purpose**: Type signatures and interface definitions only
143
+
- **Dependencies**: None
144
+
- **Exports**: Pure type signatures, no implementations
145
+
146
+
### **jmap** (Core Protocol Layer)
147
+
- **Purpose**: Stateless JMAP protocol processing (JSON, wire format, core types)
148
+
- **Dependencies**: jmap-sigs only
149
+
- **Exports**: Core protocol builders, parsers, types (Id, Date, Methods, etc.)
150
+
- **NO I/O**: Pure protocol processing, no network or file operations
151
+
152
+
### **jmap-email** (Email Extension Layer)
153
+
- **Purpose**: Email-specific JSON builders and parsers (RFC 8621)
154
+
- **Dependencies**: jmap only (NEVER jmap-unix)
155
+
- **Exports**: Email-specific JSON builders, property utilities, email parsers
156
+
- **NO I/O**: Pure JSON processing, no transport or execution
157
+
- **Key Functions**:
158
+
- `Jmap_email_query.to_json : query_builder -> Yojson.Safe.t`
159
+
- `Jmap_email_query.property_preset_to_strings : preset -> string list`
160
+
- `Jmap_email.of_json : Yojson.Safe.t -> (t, error) result`
161
+
162
+
### **jmap-unix** (Network Transport Layer)
163
+
- **Purpose**: Network I/O, connection management, request execution
164
+
- **Dependencies**: jmap-email only (NEVER direct jmap or jmap-sigs)
165
+
- **Exports**: High-level email operations with network execution
166
+
- **Has Context**: Manages connection state, sessions, authentication
167
+
- **Key Functions**:
168
+
- `query_emails : context -> Jmap_email_query.query_builder -> (email list, error) result`
169
+
- `get_emails : context -> Jmap_email_query.get_args -> (email list, error) result`
140
170
141
-
- **jmap-unix functions**:
142
-
- `Jmap_email_query.execute_query`
143
-
- `Jmap_email_batch.execute`
144
-
- `Jmap_email_methods.query_and_fetch`
171
+
### **CRITICAL ARCHITECTURAL INSIGHT**:
172
+
**jmap-email produces JSON, jmap-unix consumes it for transport**
145
173
146
-
- **jmap-email functions**:
147
-
- `Jmap.Method.create`
148
-
- `Jmap.Request.build`
149
-
- `Jmap.Response.parse`
174
+
```ocaml
175
+
(* jmap-email: JSON builders (NO transport) *)
176
+
val build_email_query : query_builder -> Yojson.Safe.t
150
177
151
-
- **jmap functions**:
152
-
- `Jmap_sigs.JSONABLE.to_json`
153
-
- `Jmap_sigs.METHOD_ARGS.validate`
178
+
(* jmap-unix: uses jmap-email builders + adds transport *)
179
+
let query_emails env ctx query_builder =
180
+
let query_json = Jmap_email_query.build_email_query query_builder in
181
+
(* ... execute via network transport ... *)
182
+
```
154
183
155
184
## 4. **Import Discipline** 📦
156
185
···
617
646
618
647
The foundation is **production-ready** and the development methodology is **proven** - full production implementation can proceed with confidence.
619
648
649
+
# Architectural Clarifications: January 2025
650
+
651
+
## 🎯 **Critical Architecture Correction**
652
+
653
+
During analysis of the fastmail_connect binary, we discovered and corrected a fundamental misunderstanding of layer separation:
654
+
655
+
### **❌ Previous Misunderstanding**
656
+
- jmap-email functions should take `jmap_unix.context` parameters
657
+
- jmap-email should have execution functions like `execute_query`
658
+
- jmap-email should depend on jmap-unix for I/O operations
659
+
660
+
### **✅ Corrected Architecture**
661
+
**jmap-email MUST NOT depend on jmap-unix**
662
+
663
+
Each layer has completely separate responsibilities:
664
+
665
+
- **jmap-email**: Pure JSON builders and parsers (NO I/O, NO transport, NO context)
666
+
- **jmap-unix**: Network transport that uses jmap-email builders
667
+
668
+
### **Implementation Pattern**
669
+
670
+
**jmap-email (Stateless JSON Processing)**:
671
+
```ocaml
672
+
(* Build JSON for Email/query method *)
673
+
val build_email_query : query_builder -> Yojson.Safe.t
674
+
675
+
(* Parse Email objects from JSON responses *)
676
+
val parse_email_list : Yojson.Safe.t -> (t list, error) result
677
+
678
+
(* Convert property presets to string lists *)
679
+
val property_preset_to_strings : [`ListV | `Preview | `Full] -> string list
680
+
```
681
+
682
+
**jmap-unix (Uses jmap-email + Adds Transport)**:
683
+
```ocaml
684
+
(* High-level email query that uses jmap-email internally *)
685
+
val query_emails :
686
+
env:< net : 'a Eio.Net.t ; .. > ->
687
+
context ->
688
+
Jmap_email_query.query_builder ->
689
+
(Jmap_email.t list, error) result
690
+
691
+
(* Implementation example *)
692
+
let query_emails env ctx query_builder =
693
+
(* Use jmap-email to build JSON *)
694
+
let query_json = Jmap_email_query.build_email_query query_builder in
695
+
let builder = build ctx |> add_method_call "Email/query" query_json "q1" in
696
+
(* Execute via network transport *)
697
+
execute env builder >>= fun response ->
698
+
(* Use jmap-email to parse response *)
699
+
Jmap_email.parse_email_list response
700
+
```
701
+
702
+
## 🔧 **Current fastmail_connect Issues**
703
+
704
+
The binary currently violates architectural principles:
705
+
706
+
**Line 23-29**: Manual `Jmap.Methods.Query_args` construction
707
+
```ocaml
708
+
(* WRONG: Manual core protocol construction *)
709
+
let query_args = Jmap.Methods.Query_args.v ~account_id ~sort:[comparator] ~limit:5 ()
710
+
```
711
+
712
+
**Line 42-52**: Manual `Jmap.Methods.Get_args` with result references
713
+
```ocaml
714
+
(* WRONG: Manual result reference handling *)
715
+
let (get_args_with_ref, result_ref_json) = Jmap.Methods.Get_args.with_result_reference
716
+
```
717
+
718
+
**Line 66-71**: Manual email parsing
719
+
```ocaml
720
+
(* WRONG: Direct JSON parsing bypassing jmap-email *)
721
+
let email_from_json json = match Jmap_email.of_json json with ...
722
+
```
723
+
724
+
### **Needed Implementation (Priority Order)**
725
+
726
+
1. **jmap-email JSON builders** (eliminates lines 23-52):
727
+
- `Jmap_email_query.build_query : query_builder -> Yojson.Safe.t`
728
+
- `Jmap_email_query.build_get_args : property list -> Yojson.Safe.t`
729
+
- Property preset utilities
730
+
731
+
2. **jmap-unix high-level operations** (eliminates manual execution):
732
+
- `query_emails : context -> query_builder -> (email list, error) result`
733
+
- `fetch_emails : context -> query_builder -> (email list, error) result`
734
+
735
+
3. **Response integration** (eliminates lines 59-71):
736
+
- Automatic response parsing using jmap-email parsers
737
+
- Clean error handling with proper error types
738
+
739
+
The goal: **Reduce fastmail_connect from ~300 lines to ~50 lines** by using proper layer abstractions.
740
+