Skip to content

Commit 0831687

Browse files
author
Jonathan D.A. Jewell
committed
Auto-commit: Sync changes [2026-02-22]
1 parent 4481c7e commit 0831687

4 files changed

Lines changed: 124 additions & 326 deletions

File tree

‎README.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,3 +145,8 @@ Contributions welcome. Please ensure:
145145
* Code follows the link:.claude/CLAUDE.md[language policy] (no TypeScript, no Node.js, no Go)
146146
* All commits include SPDX license headers
147147
* Dependencies are SHA-pinned
148+
149+
150+
== Architecture
151+
152+
See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard.

‎TOPOLOGY.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
<!-- SPDX-License-Identifier: PMPL-1.0-or-later -->
2+
<!-- TOPOLOGY.md — Project architecture map and completion dashboard -->
3+
<!-- Last updated: 2026-02-19 -->
4+
5+
# Universal Chat Extractor — Project Topology
6+
7+
## System Architecture
8+
9+
```
10+
┌─────────────────────────────────────────┐
11+
│ OPERATOR / USER │
12+
│ (CLI Interface / Privacy HUD) │
13+
└───────────────────┬─────────────────────┘
14+
│ Command / File
15+
▼
16+
┌─────────────────────────────────────────┐
17+
│ PARSER REGISTRY HUB │
18+
│ ┌───────────┐ ┌───────────────────┐ │
19+
│ │ WhatsApp │ │ Telegram / Signal │ │
20+
│ │ (.txt) │ │ (JSON / Backup) │ │
21+
│ └─────┬─────┘ └────────┬──────────┘ │
22+
│ ┌─────▼─────┐ ┌────────▼──────────┐ │
23+
│ │ Discord / │ │ iMessage / Slack │ │
24+
│ │ Slack │ │ (SQLite / API) │ │
25+
│ └─────┬─────┘ └────────┬──────────┘ │
26+
└────────│─────────────────│──────────────┘
27+
│ │
28+
▼ ▼
29+
┌─────────────────────────────────────────┐
30+
│ UNIFIED MESSAGE SCHEMA │
31+
│ (Normalization, PII Anonymization) │
32+
└───────────────────┬─────────────────────┘
33+
│
34+
▼
35+
┌─────────────────────────────────────────┐
36+
│ EXPORT ENGINE │
37+
│ ┌───────────┐ ┌───────────┐ ┌───────┐│
38+
│ │ JSON/CSV │ │ Markdown │ │ PDF ││
39+
│ └───────────┘ └───────────┘ └───────┘│
40+
└─────────────────────────────────────────┘
41+
42+
┌─────────────────────────────────────────┐
43+
│ REPO INFRASTRUCTURE │
44+
│ Justfile Automation .machine_readable/ │
45+
│ Deno / ReScript 0-AI-MANIFEST.a2ml │
46+
└─────────────────────────────────────────┘
47+
```
48+
49+
## Completion Dashboard
50+
51+
```
52+
COMPONENT STATUS NOTES
53+
───────────────────────────────── ────────────────── ─────────────────────────────────
54+
PARSER REGISTRY
55+
WhatsApp Parser (.txt) █░░░░░░░░░ 10% Architecture stubs
56+
Telegram Parser (JSON) █░░░░░░░░░ 10% Format spec verified
57+
iMessage / Discord ░░░░░░░░░░ 0% Pending specification
58+
59+
CORE LOGIC
60+
Unified Message Schema █░░░░░░░░░ 10% Normalization stubs
61+
PII Anonymization Mode ░░░░░░░░░░ 0% Privacy logic planned
62+
Export Engine █░░░░░░░░░ 10% Output format stubs
63+
64+
REPO INFRASTRUCTURE
65+
Justfile Automation ██████████ 100% Standard tasks active
66+
Multi-Forge Synchronization ██████████ 100% GH/GL/BB/CB sync stable
67+
.machine_readable/ ██████████ 100% STATE tracking active
68+
69+
─────────────────────────────────────────────────────────────────────────────
70+
OVERALL: ██░░░░░░░░ ~20% Specification Phase
71+
```
72+
73+
## Key Dependencies
74+
75+
```
76+
Chat Export ──────► Parser Registry ─────► Unified Schema ────► Export File
77+
│ │ │ │
78+
▼ ▼ ▼ ▼
79+
Privacy Rules ───► Anonymization ──────► Local Processing ────► Report
80+
```
81+
82+
## Update Protocol
83+
84+
This file is maintained by both humans and AI agents. When updating:
85+
86+
1. **After completing a component**: Change its bar and percentage
87+
2. **After adding a component**: Add a new row in the appropriate section
88+
3. **After architectural changes**: Update the ASCII diagram
89+
4. **Date**: Update the `Last updated` comment at the top of this file
90+
91+
Progress bars use: `█` (filled) and `░` (empty), 10 characters wide.
92+
Percentages: 0%, 10%, 20%, ... 100% (in 10% increments).

‎src/abi/Foreign.idr‎

Lines changed: 14 additions & 192 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,38 @@
1-
||| Foreign Function Interface Declarations
1+
||| UNIVERSAL-CHAT-EXTRACTOR — FFI Bridge Declarations
22
|||
3-
||| This module declares all C-compatible functions that will be
4-
||| implemented in the Zig FFI layer.
5-
|||
6-
||| All functions are declared here with type signatures and safety proofs.
7-
||| Implementations live in ffi/zig/
3+
||| This module defines the formal bridge to the native chat-extraction
4+
||| kernel. It provides the low-level signatures required to process
5+
||| heterogeneous chat logs (Slack, Discord, Teams) via a unified API.
86

9-
module {{PROJECT}}.ABI.Foreign
7+
module UNIVERSAL_CHAT_EXTRACTOR.ABI.Foreign
108

11-
import {{PROJECT}}.ABI.Types
12-
import {{PROJECT}}.ABI.Layout
9+
import UNIVERSAL_CHAT_EXTRACTOR.ABI.Types
10+
import UNIVERSAL_CHAT_EXTRACTOR.ABI.Layout
1311

1412
%default total
1513

1614
--------------------------------------------------------------------------------
17-
-- Library Lifecycle
15+
-- Lifecycle
1816
--------------------------------------------------------------------------------
1917

20-
||| Initialize the library
21-
||| Returns a handle to the library instance, or Nothing on failure
18+
||| Initializes the extraction engine.
2219
export
23-
%foreign "C:{{project}}_init, lib{{project}}"
20+
%foreign "C:chat_extractor_init, libextractor"
2421
prim__init : PrimIO Bits64
2522

26-
||| Safe wrapper for library initialization
23+
||| Safe initialization wrapper.
2724
export
2825
init : IO (Maybe Handle)
2926
init = do
3027
ptr <- primIO prim__init
3128
pure (createHandle ptr)
3229

33-
||| Clean up library resources
30+
||| Shuts down the engine and releases native buffers.
3431
export
35-
%foreign "C:{{project}}_free, lib{{project}}"
32+
%foreign "C:chat_extractor_free, libextractor"
3633
prim__free : Bits64 -> PrimIO ()
3734

38-
||| Safe wrapper for cleanup
35+
||| Safe cleanup wrapper.
3936
export
4037
free : Handle -> IO ()
4138
free h = primIO (prim__free (handlePtr h))
42-
43-
--------------------------------------------------------------------------------
44-
-- Core Operations
45-
--------------------------------------------------------------------------------
46-
47-
||| Example operation: process data
48-
export
49-
%foreign "C:{{project}}_process, lib{{project}}"
50-
prim__process : Bits64 -> Bits32 -> PrimIO Bits32
51-
52-
||| Safe wrapper with error handling
53-
export
54-
process : Handle -> Bits32 -> IO (Either Result Bits32)
55-
process h input = do
56-
result <- primIO (prim__process (handlePtr h) input)
57-
pure $ case result of
58-
0 => Left Error
59-
n => Right n
60-
61-
--------------------------------------------------------------------------------
62-
-- String Operations
63-
--------------------------------------------------------------------------------
64-
65-
||| Convert C string to Idris String
66-
export
67-
%foreign "support:idris2_getString, libidris2_support"
68-
prim__getString : Bits64 -> String
69-
70-
||| Free C string
71-
export
72-
%foreign "C:{{project}}_free_string, lib{{project}}"
73-
prim__freeString : Bits64 -> PrimIO ()
74-
75-
||| Get string result from library
76-
export
77-
%foreign "C:{{project}}_get_string, lib{{project}}"
78-
prim__getResult : Bits64 -> PrimIO Bits64
79-
80-
||| Safe string getter
81-
export
82-
getString : Handle -> IO (Maybe String)
83-
getString h = do
84-
ptr <- primIO (prim__getResult (handlePtr h))
85-
if ptr == 0
86-
then pure Nothing
87-
else do
88-
let str = prim__getString ptr
89-
primIO (prim__freeString ptr)
90-
pure (Just str)
91-
92-
--------------------------------------------------------------------------------
93-
-- Array/Buffer Operations
94-
--------------------------------------------------------------------------------
95-
96-
||| Process array data
97-
export
98-
%foreign "C:{{project}}_process_array, lib{{project}}"
99-
prim__processArray : Bits64 -> Bits64 -> Bits32 -> PrimIO Bits32
100-
101-
||| Safe array processor
102-
export
103-
processArray : Handle -> (buffer : Bits64) -> (len : Bits32) -> IO (Either Result ())
104-
processArray h buf len = do
105-
result <- primIO (prim__processArray (handlePtr h) buf len)
106-
pure $ case resultFromInt result of
107-
Just Ok => Right ()
108-
Just err => Left err
109-
Nothing => Left Error
110-
where
111-
resultFromInt : Bits32 -> Maybe Result
112-
resultFromInt 0 = Just Ok
113-
resultFromInt 1 = Just Error
114-
resultFromInt 2 = Just InvalidParam
115-
resultFromInt 3 = Just OutOfMemory
116-
resultFromInt 4 = Just NullPointer
117-
resultFromInt _ = Nothing
118-
119-
--------------------------------------------------------------------------------
120-
-- Error Handling
121-
--------------------------------------------------------------------------------
122-
123-
||| Get last error message
124-
export
125-
%foreign "C:{{project}}_last_error, lib{{project}}"
126-
prim__lastError : PrimIO Bits64
127-
128-
||| Retrieve last error as string
129-
export
130-
lastError : IO (Maybe String)
131-
lastError = do
132-
ptr <- primIO prim__lastError
133-
if ptr == 0
134-
then pure Nothing
135-
else pure (Just (prim__getString ptr))
136-
137-
||| Get error description for result code
138-
export
139-
errorDescription : Result -> String
140-
errorDescription Ok = "Success"
141-
errorDescription Error = "Generic error"
142-
errorDescription InvalidParam = "Invalid parameter"
143-
errorDescription OutOfMemory = "Out of memory"
144-
errorDescription NullPointer = "Null pointer"
145-
146-
--------------------------------------------------------------------------------
147-
-- Version Information
148-
--------------------------------------------------------------------------------
149-
150-
||| Get library version
151-
export
152-
%foreign "C:{{project}}_version, lib{{project}}"
153-
prim__version : PrimIO Bits64
154-
155-
||| Get version as string
156-
export
157-
version : IO String
158-
version = do
159-
ptr <- primIO prim__version
160-
pure (prim__getString ptr)
161-
162-
||| Get library build info
163-
export
164-
%foreign "C:{{project}}_build_info, lib{{project}}"
165-
prim__buildInfo : PrimIO Bits64
166-
167-
||| Get build information
168-
export
169-
buildInfo : IO String
170-
buildInfo = do
171-
ptr <- primIO prim__buildInfo
172-
pure (prim__getString ptr)
173-
174-
--------------------------------------------------------------------------------
175-
-- Callback Support
176-
--------------------------------------------------------------------------------
177-
178-
||| Callback function type (C ABI)
179-
public export
180-
Callback : Type
181-
Callback = Bits64 -> Bits32 -> Bits32
182-
183-
||| Register a callback
184-
export
185-
%foreign "C:{{project}}_register_callback, lib{{project}}"
186-
prim__registerCallback : Bits64 -> AnyPtr -> PrimIO Bits32
187-
188-
||| Safe callback registration
189-
export
190-
registerCallback : Handle -> Callback -> IO (Either Result ())
191-
registerCallback h cb = do
192-
result <- primIO (prim__registerCallback (handlePtr h) (believe_me cb))
193-
pure $ case resultFromInt result of
194-
Just Ok => Right ()
195-
Just err => Left err
196-
Nothing => Left Error
197-
where
198-
resultFromInt : Bits32 -> Maybe Result
199-
resultFromInt 0 = Just Ok
200-
resultFromInt _ = Just Error
201-
202-
--------------------------------------------------------------------------------
203-
-- Utility Functions
204-
--------------------------------------------------------------------------------
205-
206-
||| Check if library is initialized
207-
export
208-
%foreign "C:{{project}}_is_initialized, lib{{project}}"
209-
prim__isInitialized : Bits64 -> PrimIO Bits32
210-
211-
||| Check initialization status
212-
export
213-
isInitialized : Handle -> IO Bool
214-
isInitialized h = do
215-
result <- primIO (prim__isInitialized (handlePtr h))
216-
pure (result /= 0)

0 commit comments

Comments
 (0)