oxedyne/fe2o3 — fe2o3

28.1 KiB, 3 runs

created by r1870400018:11644, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	# Hematite (fe2o3) Library Overview
2
3	Version: 0.5.0 (pre-1.0.0, ~50% complete)
4	Licence: BSD-2-Clause
5	Repository: https://github.com/Oxedize/fe2o3
6	Author: h00gs <hello@oxedize.com>
7
8	## Project Summary
9
10	Hematite is a collection of Rust crates that grew from an exploration into database design and key data structures. The project is built from first principles with a focus on readability, correctness and maintainability over cleverness and premature optimisation. It avoids `unsafe` code and `unwrap()` throughout, using custom error handling macros (`res!`, `ok!`, `err!`, `catch!`) via the `Outcome<T>` result type.
11
12	The library currently comprises 24 crates (including 2 procedural macro crates), organised by their level of cross-dependency into foundational, fundamental, functional and application-level tiers.
13
14	---
15
16	## Architecture and Dependency Graph
17
18	The crates form a layered dependency graph. `fe2o3_core` sits at the base and is used by every other crate. `fe2o3_jdat` (the serialisation format) is the next most widely depended upon, followed by `fe2o3_namex` (the naming registry).
19
20	```
21	Application Layer
22	┌──────────┬──────────┬──────────┐
23	│ fe2o3_ │ fe2o3_ │ fe2o3_ │
24	│ o3db │ shield │ steel │
25	└────┬─────┴────┬─────┴────┬─────┘
26	│ │ │
27	Functional Layer
28	┌────────┬──────────┬──────────┬──────────┐
29	│ fe2o3_ │ fe2o3_ │ fe2o3_ │ fe2o3_ │
30	│ net │ tui │ crypto │ hash │
31	└───┬────┴────┬─────┴────┬─────┴────┬─────┘
32	│ │ │ │
33	Fundamental Layer
34	┌────────┬──────────┬──────────┬──────────┐
35	│ fe2o3_ │ fe2o3_ │ fe2o3_ │ fe2o3_ │
36	│ jdat │ syntax │ namex │ bot │
37	├────────┼──────────┼──────────┼──────────┤
38	│ fe2o3_ │ fe2o3_ │ fe2o3_ │ fe2o3_ │
39	│ data │ file │ text │ units │
40	└───┬────┴────┬─────┴────┬─────┴────┬─────┘
41	│ │ │ │
42	Foundational Layer
43	┌────────┬──────────┬──────────┬──────────┐
44	│ fe2o3_ │ fe2o3_ │ fe2o3_ │ fe2o3_ │
45	│ core │ stds │ geom │ test │
46	└────────┴──────────┴──────────┴──────────┘
47
48	Interoperability Protocol (IOP) Layer
49	┌────────────┬──────────────┬──────────────┐
50	│ fe2o3_ │ fe2o3_ │ fe2o3_ │
51	│ iop_crypto │ iop_hash │ iop_db │
52	└────────────┴──────────────┴──────────────┘
53	```
54
55	---
56
57	## Crate-by-Crate Overview
58
59	### Foundational Crates
60
61	These have no internal cross-dependencies (or only depend on `fe2o3_stds`).
62
63	#### fe2o3_stds -- Standard Data Enumerations
64
65	Purpose: Provides standard data enumerations used across the library.
66
67	Current capabilities:
68	- `chars` -- character enumerations and classification.
69	- `regions` -- geographic and regional enumerations.
70
71	What is next:
72	- No known outstanding items.
73
74	Tests: None.
75
76	---
77
78	#### fe2o3_core -- Core Traits and Utilities
79
80	Purpose: The foundational crate upon which all others depend. Provides the custom error handling system, logging, macros and core utilities.
81
82	Dependencies: `fe2o3_stds`, `new` (proc-macro), `base64`, `flume`, `rand`, `flate2`, `humantime`, `once_cell`.
83
84	Current capabilities:
85	- `error` -- the `Outcome<V>` result type and `GenTag` error tag trait.
86	- `log` -- logging framework.
87	- `macros/` -- a comprehensive collection of macros:
88	- `error` -- `res!`, `ok!`, `err!`, `catch!` for error handling.
89	- `lock` -- `lock_read!`, `lock_write!`, `lock_mutex!`, `lock_mutex_thread!` for safe lock acquisition.
90	- `collection`, `conversion`, `enum_iter`, `integer`, `newtype`, `range`, `string`, `test`.
91	- `alt` -- alternative/option utilities.
92	- `bool`, `bot`, `byte` -- primitive type extensions.
93	- `channels` -- channel-based communication helpers.
94	- `conv` -- type conversion utilities.
95	- `count` -- counting utilities.
96	- `file` -- basic file operations.
97	- `id` -- identification utilities.
98	- `int` -- integer utilities.
99	- `map` -- map/collection helpers.
100	- `mem` -- memory utilities.
101	- `ord` -- ordering utilities.
102	- `path` -- path manipulation.
103	- `rand` -- random number generation.
104	- `string` -- string utilities.
105	- `test` -- test helpers.
106	- `thread` -- threading utilities.
107	- `time` -- time utilities.
108
109	What is next:
110	- No critical outstanding items identified.
111
112	Tests: 3 test files (`main.rs`, `path.rs`, `string.rs`).
113
114	---
115
116	#### fe2o3_geom -- Geometry Library
117
118	Purpose: Basic geometry primitives.
119
120	Dependencies: `fe2o3_core`.
121
122	Current capabilities:
123	- `dim` -- dimensional types.
124	- `rect` -- rectangle types and operations.
125
126	What is next:
127	- No known outstanding items.
128
129	Tests: 1 test file (`macro.rs`).
130
131	---
132
133	#### fe2o3_test -- Testing Utilities
134
135	Purpose: Testing and performance measurement utilities used across the library.
136
137	Dependencies: `fe2o3_core`, `rand`.
138
139	Current capabilities:
140	- `data` -- test data generation.
141	- `error` -- test error utilities.
142
143	What is next:
144	- No known outstanding items.
145
146	Tests: None (utility crate).
147
148	---
149
150	#### fe2o3_infer -- Convolutional Inference
151
152	Purpose: CPU inference for small convolutional networks, and the face detection and face embedding built on it.
153
154	Dependencies: `fe2o3_core`.
155
156	Current capabilities:
157	- `kern` -- safe `f32` kernels (blocked matrix product, matrix--vector, patch gather, depthwise convolution, per-channel scale, parametric rectifier, rectifier, sigmoid, maximum pool, nearest-neighbour doubling, element-wise sum) behind one runtime dispatch, with a fused-multiply-add path and a baseline path.
158	- `onnx` -- a reader for the subset of the ONNX wire format these networks use.
159	- `graph` -- weight preparation (layout permutation, batch-norm folding) and a runner over the prepared operators.
160	- `face` -- letterbox, detection with anchor-free decode and non-maximum suppression, five-point similarity alignment, and a 128-dimensional embedding with cosine comparison.
161
162	What is next:
163	- Clustering over a corpus of embeddings; an `aarch64` dispatch arm; the `f16` weight form.
164
165	Tests: 2 test files (`guard.rs`, `models.rs`) plus in-module tests. Weights are not in the repository; `models.rs` skips without `FE2O3_INFER_MODELS`.
166
167	---
168
169	### Fundamental Crates
170
171	These have 1-3 internal cross-dependencies.
172
173	#### fe2o3_num -- Numerical Type Utilities
174
175	Purpose: Extended numerical types and utilities beyond the standard library.
176
177	Dependencies: `fe2o3_core`, `bigdecimal` 0.2.0, `num-bigint` 0.3.
178
179	Current capabilities:
180	- `float` -- floating point utilities.
181	- `int` -- integer utilities and extensions.
182	- `string` -- number-to-string formatting.
183	- `macros` -- numerical macros.
184	- Re-exports `BigInt` and `BigDecimal`.
185
186	What is next:
187	- No known outstanding items.
188
189	Tests: 1 test file (`macro.rs`).
190
191	---
192
193	#### fe2o3_text -- String Manipulation and Formatting
194
195	Purpose: Rich text processing, encoding and pattern matching.
196
197	Dependencies: `fe2o3_core`, `fe2o3_geom`, `fe2o3_stds`, `base64`.
198
199	Current capabilities:
200	- `Text` struct -- core text type.
201	- `access` -- text access and extraction.
202	- `base2x` -- base-2x encoding/decoding.
203	- `core` -- core text operations.
204	- `highlight` -- syntax/text highlighting.
205	- `lines` -- line-by-line processing.
206	- `pattern` -- pattern matching.
207	- `split` -- text splitting.
208	- `string` -- string extensions.
209	- `phrase` -- phrase-level operations.
210
211	What is next:
212	- No known outstanding items.
213
214	Tests: 5 test files (`base2x.rs`, `highlight.rs`, `main.rs`, `pattern.rs`, `string.rs`).
215
216	---
217
218	#### fe2o3_units -- Scientific Units Library
219
220	Purpose: SI and other unit system representations with scaling.
221
222	Dependencies: `fe2o3_core`, `fe2o3_num`.
223
224	Current capabilities:
225	- `si` -- SI (International System) unit definitions.
226	- `system` -- unit system framework.
227	- `scale` -- unit scaling and conversion (partially implemented).
228
229	What is next:
230	- Scale lookup functions in `scale.rs` contain `unimplemented!()` calls (lines 249, 261) that need completing.
231
232	Tests: None.
233
234	---
235
236	#### fe2o3_bot -- Thread Worker Library
237
238	Purpose: Thread worker and task pool management using OS threads.
239
240	Dependencies: `fe2o3_core`, `fe2o3_jdat`.
241
242	Current capabilities:
243	- `Bot` -- the core worker type.
244	- `handles` -- thread handle management.
245	- `msg` -- inter-bot messaging.
246
247	What is next:
248	- No known outstanding items.
249
250	Tests: None.
251
252	---
253
254	#### fe2o3_data -- Specialised Data Structures
255
256	Purpose: Data structures beyond the standard library.
257
258	Dependencies: `fe2o3_core`, `fe2o3_jdat`.
259
260	Current capabilities:
261	- `ring` -- ring buffer.
262	- `stack` -- stack data structure.
263	- `time` -- time-related data structures.
264	- `tree` -- tree data structures.
265
266	What is next:
267	- No known outstanding items.
268
269	Tests: 3 test files (`base2x.rs`, `main.rs`, `path.rs`).
270
271	---
272
273	#### fe2o3_file -- File System Utilities
274
275	Purpose: File system operations and directory tree management.
276
277	Dependencies: `fe2o3_core`, `fe2o3_data`.
278
279	Current capabilities:
280	- `tree` -- directory tree traversal and operations.
281
282	What is next:
283	- No known outstanding items.
284
285	Tests: 2 test files (`main.rs`, `tree.rs`).
286
287	---
288
289	### Interoperability Protocol (IOP) Crates
290
291	These define abstract interfaces (traits) that separate specification from implementation, allowing different concrete implementations to be swapped in.
292
293	#### fe2o3_iop_crypto -- Cryptography Interoperability
294
295	Purpose: Defines abstract interfaces for cryptographic operations.
296
297	Dependencies: `fe2o3_core`, `fe2o3_namex`.
298
299	Current capabilities:
300	- `enc` -- encryption interface.
301	- `kem` -- key encapsulation mechanism interface.
302	- `keys` -- key management interface.
303	- `sign` -- digital signature interface.
304
305	What is next:
306	- No known outstanding items.
307
308	Tests: None (interface-only crate).
309
310	---
311
312	#### fe2o3_iop_hash -- Hashing Interoperability
313
314	Purpose: Defines abstract interfaces for hashing operations.
315
316	Dependencies: `fe2o3_core`, `fe2o3_namex`.
317
318	Current capabilities:
319	- `api` -- core hashing API traits.
320	- `csum` -- checksum interface.
321	- `kdf` -- key derivation function interface.
322
323	What is next:
324	- No known outstanding items.
325
326	Tests: None (interface-only crate).
327
328	---
329
330	#### fe2o3_iop_db -- Database Interoperability
331
332	Purpose: Defines abstract interfaces for database operations.
333
334	Dependencies: `fe2o3_core`, `fe2o3_crypto`, `fe2o3_data`, `fe2o3_hash`, `fe2o3_iop_crypto`, `fe2o3_iop_hash`, `fe2o3_jdat`, `fe2o3_namex`.
335
336	Current capabilities:
337	- `api` -- common database interface traits.
338
339	What is next:
340	- No known outstanding items.
341
342	Tests: None (interface-only crate).
343
344	---
345
346	### Functional Crates
347
348	These have 4 or more cross-dependencies and provide significant standalone functionality.
349
350	#### fe2o3_jdat -- JDAT Format (Jason's Data And Type)
351
352	Purpose: A superset of JSON that adds type annotations, binary serialisation and structured key support. This is one of the most central crates in the library, used by ~15 other crates.
353
354	Dependencies: `fe2o3_core`, `fe2o3_num`, `fe2o3_text`, `dat_map` (proc-macro), `bigdecimal`, `num-bigint`.
355
356	Current capabilities:
357	- `Dat` enum -- the core data type with rich variant set.
358	- `Kind` -- type descriptor system.
359	- `Daticle` trait -- core serialisation/deserialisation trait.
360	- `binary/` -- binary encoding and decoding:
361	- `enc.rs` -- binary encoder.
362	- `dec.rs` -- binary decoder.
363	- `core.rs` -- shared binary logic.
364	- `load.rs` -- binary loading.
365	- `count.rs` -- byte counting.
366	- `string/` -- human-readable string encoding and decoding:
367	- `enc.rs` -- string encoder.
368	- `dec.rs` -- string decoder.
369	- `core.rs` -- shared string logic.
370	- `map` -- map operations with arbitrary key types.
371	- `conv` -- type conversion utilities.
372	- `file` -- JDAT file I/O.
373	- `id` -- identification types.
374	- `int` -- integer handling.
375	- `note` -- annotations and comments.
376	- `usr` -- user-defined type support.
377	- `version` -- versioning support.
378	- `constant` -- format constants.
379	- `cfg` -- configuration support.
380	- `chunk` -- chunked data handling.
381	- Key traits: `BestFrom` (conversion), `FromDatMap`, `ToDatMap`.
382
383	Key features over JSON:
384	- Type annotations (e.g., `(u64) 42`).
385	- Multiple number formats (integers, floats, big numbers).
386	- Binary representation for compact storage.
387	- Comment support.
388	- Any type as map keys (not just strings).
389
390	What is next:
391	- B256 type consideration (noted in `conv.rs` line 458).
392
393	Benchmarks: 2 benchmark files.
394	Tests: 5 test files (`byte.rs`, `daticle.rs`, `main.rs`, `map.rs`, `string.rs`).
395
396	---
397
398	#### fe2o3_namex -- Universal Name Codex
399
400	Purpose: A distributed naming system for schemes, specifications and identifiers. Used by ~8 other crates.
401
402	Dependencies: `fe2o3_core`, `fe2o3_jdat`, `fe2o3_text`, `base64`, `strum`, `strum_macros`, `num-derive`, `num-traits`.
403
404	Current capabilities:
405	- `InNamex` trait -- interface for named/registered items.
406	- `db` -- database/registry functions.
407	- `id` -- identification and naming.
408
409	What is next:
410	- Date validation needs completing (`db.rs` lines 295, 301).
411
412	Tests: 3 test files (`file.rs`, `genids.rs`, `main.rs`).
413
414	---
415
416	#### fe2o3_hash -- Generic Hashing Utilities
417
418	Purpose: Wrappers for various hash schemes, conforming to the `fe2o3_iop_hash` interfaces.
419
420	Dependencies: `fe2o3_core`, `fe2o3_iop_hash`, `fe2o3_jdat`, `fe2o3_namex`, `crc32fast`, `seahash`, `tiny-keccak`, `rust-argon2`, `num_cpus`, `base64`.
421
422	Current capabilities:
423	- `csum` -- checksum implementations (CRC32).
424	- `hash` -- core hashing (SeaHash, Keccak/SHA-3).
425	- `kdf` -- key derivation functions (Argon2).
426	- `map` -- hash map utilities.
427	- `pow` -- proof-of-work computation.
428
429	What is next:
430	- Async thread optimisation for proof-of-work (`pow.rs` line 375).
431
432	Tests: 3 test files (`hash.rs`, `main.rs`, `map.rs`).
433
434	---
435
436	#### fe2o3_crypto -- Post-Quantum Cryptography
437
438	Purpose: Implements post-quantum cryptographic algorithms from the NIST PQC standardisation process, conforming to `fe2o3_iop_crypto` interfaces.
439
440	Dependencies: `fe2o3_core`, `fe2o3_data`, `fe2o3_iop_crypto`, `fe2o3_jdat`, `fe2o3_namex`, `aes-gcm`, `ed25519-dalek`, `pqcrypto-dilithium`, `secrecy`, `zeroize`, `wasm-bindgen`.
441
442	Library type: `cdylib` + `lib` (supports WebAssembly).
443
444	Feature flags: `mode0`, `mode1`, `mode2` (default), `mode3`.
445
446	Current capabilities:
447	- `pqc/dilithium` -- CRYSTALS-Dilithium digital signatures.
448	- `pqc/saber` -- SABER key encapsulation mechanism.
449	- `enc` -- AES-GCM symmetric encryption.
450	- `kem` -- key encapsulation mechanism framework.
451	- `keys` -- key management.
452	- `scheme` -- cryptographic scheme definitions.
453	- `sign` -- ED25519 elliptic curve signatures.
454	- `wasm/` -- WebAssembly bindings for browser use.
455
456	Build: Uses `bindgen` for C FFI (SABER reference implementation).
457
458	What is next:
459	- Dilithium comparison optimisation (`dilithium.rs` line 1586).
460	- Subtle timing-safe comparison needed (`dilithium.rs` line 1281).
461	- SABER variant implementations incomplete (`saber.rs` line 2322).
462
463	Tests: 1 test file.
464
465	---
466
467	#### fe2o3_syntax -- Command and Message Syntax
468
469	Purpose: A unified syntax definition and parsing system that bridges CLI/TUI commands and over-the-wire message protocols (OSI Presentation Layer).
470
471	Dependencies: `fe2o3_core`, `fe2o3_jdat`, `fe2o3_stds`, `fe2o3_text`, `fe2o3_units`, `levenshtein`.
472
473	Current capabilities:
474	- `Syntax`, `SyntaxRef` -- core syntax definition types.
475	- `cmd` -- command definitions.
476	- `arg` -- argument parsing.
477	- `opt` -- option handling.
478	- `msg` -- message serialisation/deserialisation.
479	- `key` -- keyword handling.
480	- `help` -- help text generation.
481	- `core` -- core parsing logic.
482	- `apps` -- application-level syntax.
483	- Builder pattern for defining command structures.
484	- Levenshtein distance for "did you mean?" suggestions.
485
486	What is next:
487	- Help system completion (`help.rs` lines 57, 269).
488	- Message serialisation optimisations (`msg.rs` line 147).
489
490	Tests: 3 test files (`core.rs`, `main.rs`, `msg.rs`).
491
492	---
493
494	#### fe2o3_tui -- Text User Interface Library
495
496	Purpose: A terminal-based user interface library with REPL support.
497
498	Dependencies: `fe2o3_core`, `fe2o3_file`, `fe2o3_geom`, `fe2o3_hash`, `fe2o3_iop_hash`, `fe2o3_jdat`, `fe2o3_stds`, `fe2o3_syntax`, `fe2o3_text`, `fe2o3_units`, `crossterm`, `secrecy`.
499
500	Current capabilities:
501	- `repl` -- read-eval-print loop framework.
502	- `window` -- terminal window management.
503	- `draw` -- drawing primitives.
504	- `render` -- rendering pipeline.
505	- `event` -- terminal event handling.
506	- `input` -- user input processing.
507	- `action` -- action/command dispatch.
508	- `cmds` -- built-in commands.
509	- `cfg` -- TUI configuration.
510	- `style` -- terminal styling (colours, formatting).
511	- `text` -- text rendering.
512
513	Examples: `repl.rs` example.
514
515	What is next:
516	- Command handling has unimplemented paths (`cmds.rs` line 102).
517
518	Tests: 2 test files (`draw.rs`, `main.rs`).
519
520	---
521
522	### Application-Level Crates
523
524	These are the highest-level crates, combining many lower-level crates into complete applications or protocols.
525
526	#### fe2o3_net -- Networking Utilities
527
528	Purpose: Networking primitives and protocol implementations.
529
530	Dependencies: `fe2o3_bot`, `fe2o3_core`, `fe2o3_crypto`, `fe2o3_data`, `fe2o3_jdat`, `fe2o3_hash`, `fe2o3_iop_crypto`, `fe2o3_iop_db`, `fe2o3_iop_hash`, `fe2o3_stds`, `fe2o3_syntax`, `fe2o3_text`, plus `tokio`, `tokio-rustls`, `lettre`, `chrono`, `sha1`, `secrecy`, `strum`.
531
532	Current capabilities:
533	- `addr` -- network address handling.
534	- `dns` -- DNS resolution.
535	- `http` -- HTTP request/response handling.
536	- `ws` -- WebSocket implementation.
537	- `smtp` -- SMTP client.
538	- `email` -- email construction and sending.
539	- `charset` -- character set handling.
540	- `media` -- MIME/media type definitions.
541	- `conc` -- concurrency utilities for networking.
542	- `file` -- network file operations.
543	- `id` -- network identification.
544	- `time` -- network time utilities.
545	- `constant` -- networking constants.
546
547	What is next:
548	- Media type definitions incomplete (`media.rs` lines 18, 125).
549	- Header field encapsulation needed (`http.rs` line 1054).
550	- WebSocket continuation frames not supported (`ws.rs` line 431).
551
552	Tests: 4 test files (`email.rs`, `http.rs`, `main.rs`, `smtp.rs`).
553	README: Includes port forwarding notes for privileged ports.
554
555	---
556
557	#### fe2o3_o3db -- Ozone O3DB Database
558
559	Purpose: A log-structured key-value database inspired by BitCask, using OS threads (bots) for concurrent operations.
560
561	Dependencies: 15+ internal crates plus `crossbeam-utils`, `hostname`, `humantime`, `lazy_static`, `num_cpus`, `rand`, `regex`, `secrecy`, `seahash`.
562
563	Current capabilities:
564	- `O3db<>` -- generic database struct.
565	- `api` -- public database API (get, put, delete).
566	- `base` -- base types and configuration.
567	- `db` -- main database implementation.
568	- `bots/` -- worker thread system:
569	- `bot_config` -- configuration bot.
570	- `bot_server` -- server bot.
571	- `bot_zone` -- zone management bot.
572	- `bot_super` -- supervisor bot.
573	- `worker/` -- worker bots for read/write operations.
574	- `comm` -- inter-bot communication.
575	- `dal/` -- data abstraction layer.
576	- `data/` -- core data structures.
577	- `file/` -- file management:
578	- `fcache` -- file caching.
579	- `live` -- live file handling.
580	- `floc` -- file location tracking.
581	- `zdir` -- zone directories.
582	- `state` -- file state management.
583	- `stored` -- stored file handling.
584	- `test` -- testing utilities.
585
586	Key features:
587	- Log-structured append-only storage.
588	- Memory-optimised design with configurable cache.
589	- Automatic garbage collection of stale data.
590	- Simple key-value interface.
591	- Multi-zone support for data partitioning.
592	- Configurable reader/writer thread counts.
593	- Robust cache initialisation and server lifecycle.
594	- Timestamped entries.
595
596	What is next (from internal roadmap):
597	- Recaching system not yet implemented.
598	- Rezoning (dynamic zone rebalancing) not yet implemented.
599	- User access control not yet implemented.
600	- Documentation needs expanding.
601	- Extensive testing still required.
602	- Performance optimisation deferred.
603	- Value writing optimisation (`bot_writer.rs` line 398).
604	- GC file status reporting (`bot_file.rs` line 269).
605	- Delete message handling (`bot_server.rs` line 98).
606	- Several unfinished items in `server.rs` (lines 419, 452, 469, 478, 517).
607	- Archive GC unimplemented (`archive/gc.rs` line 160).
608
609	Benchmarks: 1 benchmark file.
610	Tests: 4 test files (`basic.rs`, `dal.rs`, `main.rs`, `perf.rs`).
611
612	---
613
614	#### fe2o3_shield -- SHIELD Protocol
615
616	Full name: Secure Hash In Every Little Datagram.
617
618	Purpose: A secure peer-to-peer protocol built on UDP, with integrated post-quantum cryptography and proof-of-work based DOS protection.
619
620	Dependencies: 10+ internal crates plus `lettre`, `local-ip-address`, `num_cpus`, `rand`, `secrecy`, `tokio`.
621
622	Current capabilities:
623	- `Shield<>`, `Protocol<>`, `ShieldParams<>` -- core protocol types.
624	- `server` -- UDP server implementation.
625	- `packet` -- packet definitions and handling.
626	- `msg/` -- message handling with syntax definitions.
627	- `guard` -- access control and user management.
628	- `pow` -- proof-of-work challenge/response for DOS mitigation.
629	- `schemes` -- cryptographic scheme negotiation.
630	- `cfg` -- protocol configuration.
631	- `constant` -- protocol constants.
632	- `core` -- core protocol logic.
633
634	Key features:
635	- UDP-based secure messaging.
636	- Post-quantum cryptographic key exchange and signing.
637	- Proof-of-work challenges to prevent spam/DOS.
638	- Per-user access control.
639	- Configurable cryptographic scheme negotiation.
640
641	What is next:
642	- Invalid signature handling incomplete (`server.rs` lines 419, 452).
643	- Periodic garbage collection of inactive users (`server.rs` line 469).
644	- Several message completion items pending (`server.rs` lines 478, 517).
645	- Proof-of-work bypass needs review (`constant.rs` line 46).
646	- Additional validation checks needed (`pow.rs` line 187).
647	- User log examination needed (`guard/user.rs` line 84).
648
649	Examples: UDP echo server example.
650	Tests: 2 test files (`main.rs`, `msg.rs`).
651
652	---
653
654	#### fe2o3_steel -- Secure TCP Server
655
656	Purpose: A secure TCP server supporting HTTPS, WebSocket and SMTPS (secure SMTP). Designed with no non-secure communication paths.
657
658	Type: Library + binary (`steel`).
659
660	Dependencies: 20+ crates including `tokio`, `rustls`, `rcgen`, `crossterm`, `rpassword`, `zeroize`, `swc`, `grass`, plus 13+ internal fe2o3 crates.
661
662	Current capabilities:
663	- `srv` -- server implementation:
664	- TLS/mTLS support via `rustls`.
665	- Self-signed certificate generation via `rcgen`.
666	- HTTPS request routing.
667	- WebSocket upgrade and handling.
668	- SMTPS server.
669	- `app` -- application layer:
670	- `repl.rs` -- interactive REPL for server management.
671	- `https.rs` -- HTTPS application logic.
672	- Asset pipeline:
673	- JavaScript bundling via SWC.
674	- SASS/CSS compilation via grass.
675
676	What is next:
677	- Help object caching (`app/repl.rs` line 178).
678	- Dynamic route registration (`app/https.rs` line 119).
679	- Windows certificate testing (`srv/cert.rs` line 328).
680
681	README: Includes port forwarding notes for privileged ports.
682	Tests: 3 test files (`client.rs`, `main.rs`, `server.rs`).
683
684	---
685
686	### Procedural Macro Crates
687
688	#### new -- Constructor Derivation
689
690	Path: `fe2o3_core/new`
691
692	Purpose: Provides `#[derive(New)]` for automatic constructor generation.
693
694	Dependencies: `syn`, `quote`, `proc-macro2`.
695
696	---
697
698	#### dat_map -- Map Derivation
699
700	Path: `fe2o3_jdat/dat_map`
701
702	Purpose: Provides `#[derive(FromDatMap, ToDatMap)]` for automatic JDAT map serialisation.
703
704	Dependencies: `fe2o3_core`, `syn`, `quote`, `proc-macro2`.
705
706	---
707
708	## Cross-Cutting Concerns
709
710	### Error Handling
711
712	All crates use the `Outcome<V>` type from `fe2o3_core` (a `Result` alias) with custom macros:
713	- `res!(expr)` -- replaces `?` operator, propagates errors with context.
714	- `ok!(option, msg)` -- replaces `.unwrap()`, returns error on `None`.
715	- `err!(msg; Tag1, Tag2)` -- creates tagged errors.
716	- `catch!(expr, handler)` -- error handling blocks.
717
718	### Lock Handling
719
720	Safe lock acquisition macros that handle poisoned locks gracefully:
721	- `lock_read!(rwlock)`, `lock_write!(rwlock)` -- RwLock.
722	- `lock_mutex!(mutex)`, `lock_mutex_thread!(mutex, context)` -- Mutex.
723
724	### Naming and Registration
725
726	The `fe2o3_namex` crate provides a universal naming system. Crates that define schemes or algorithms register them via the `InNamex` trait, enabling distributed identification without central coordination.
727
728	### Serialisation
729
730	JDAT (`fe2o3_jdat`) serves as the primary serialisation format throughout the library, used for configuration, wire protocols, database storage and inter-component communication.
731
732	---
733
734	## Testing Summary
735
736	\| Crate \| Test Files \| Benchmarks \|
737	\|---\|---\|---\|
738	\| fe2o3_core \| 3 \| -- \|
739	\| fe2o3_stds \| -- \| -- \|
740	\| fe2o3_geom \| 1 \| -- \|
741	\| fe2o3_test \| -- \| -- \|
742	\| fe2o3_num \| 1 \| -- \|
743	\| fe2o3_text \| 5 \| -- \|
744	\| fe2o3_units \| -- \| -- \|
745	\| fe2o3_bot \| -- \| -- \|
746	\| fe2o3_data \| 3 \| -- \|
747	\| fe2o3_file \| 2 \| -- \|
748	\| fe2o3_jdat \| 5 \| 2 \|
749	\| fe2o3_namex \| 3 \| -- \|
750	\| fe2o3_hash \| 3 \| -- \|
751	\| fe2o3_crypto \| 1 \| -- \|
752	\| fe2o3_syntax \| 3 \| -- \|
753	\| fe2o3_tui \| 2 \| -- \|
754	\| fe2o3_iop_crypto \| -- \| -- \|
755	\| fe2o3_iop_hash \| -- \| -- \|
756	\| fe2o3_iop_db \| -- \| -- \|
757	\| fe2o3_net \| 4 \| -- \|
758	\| fe2o3_o3db \| 4 \| 1 \|
759	\| fe2o3_shield \| 2 \| -- \|
760	\| fe2o3_steel \| 3 \| -- \|
761	\| Total \| 45 \| 3 \|
762
763	---
764
765	## External Dependencies
766
767	### Heavy/Notable Dependencies
768
769	\| Dependency \| Used By \| Purpose \|
770	\|---\|---\|---\|
771	\| tokio \| steel, shield, net \| Async runtime \|
772	\| rustls, tokio-rustls \| steel, net \| TLS implementation \|
773	\| pqcrypto-dilithium \| crypto \| Post-quantum signatures \|
774	\| aes-gcm \| crypto \| Symmetric encryption \|
775	\| ed25519-dalek \| crypto \| Elliptic curve signatures \|
776	\| swc \| steel \| JavaScript bundling \|
777	\| grass \| steel \| SASS/CSS compilation \|
778	\| crossterm \| tui \| Terminal abstraction \|
779	\| lettre \| net, shield \| Email sending \|
780	\| seahash \| hash, o3db \| Fast hashing \|
781	\| tiny-keccak \| hash \| SHA-3/Keccak \|
782	\| rust-argon2 \| hash \| Password hashing/KDF \|
783	\| bigdecimal, num-bigint \| num, jdat \| Arbitrary precision numbers \|
784	\| wasm-bindgen \| crypto \| WebAssembly support \|
785
786	---
787
788	## Overall Project Status and Roadmap
789
790	### Completed
791
792	- Core error handling and macro system.
793	- JDAT format with string and binary encoding/decoding.
794	- Post-quantum cryptography (Dilithium, SABER, AES-GCM, ED25519).
795	- Basic O3DB database with log-structured storage and GC.
796	- SHIELD protocol with UDP messaging and PoW.
797	- Steel secure server with HTTPS, WebSocket and SMTPS.
798	- TUI framework with REPL.
799	- Syntax system bridging CLI and wire protocols.
800	- IOP abstraction layers for crypto, hashing and databases.
801
802	### In Progress / Next Steps
803
804	1. O3DB: Recaching, rezoning, user access control, expanded testing and documentation.
805	2. SHIELD: Protocol completion -- signature handling, user GC, message handling.
806	3. Steel: Dynamic routing, help caching, Windows support.
807	4. Crypto: Timing-safe comparisons, SABER variant completion, Dilithium optimisation.
808	5. Net: WebSocket continuation frames, media type completion, header encapsulation.
809	6. Units: Scale lookup implementation.
810	7. Namex: Date validation.
811	8. General: API stabilisation, expanded documentation, community contribution readiness, crates.io publication.
812
813	### Design Philosophy Reminders
814
815	- Readable and obvious over clever.
816	- Correctness and reliability before optimisation.
817	- No `unsafe`, no `unwrap()`.
818	- Minimal third-party dependencies where practical.
819	- Self-contained implementations built from first principles.