English | 简体中文 | 日本語 | 한국어

Ultra-High-Performance Native Archiving & Compression Microkernel
Engineered with a Safe Rust Microkernel (ttzip-engine → TTZipVendor.xcframework), SOTA Codecs, Dual-ISA SIMD / PMULL Vector Acceleration, and a Swift 6 SDK Shell & CLI (TTZipCore, ttzip, ttzip-bench).

---

📖 Architecture & Design Documentation

• System Architecture Whitepaper (English): Deep dive into the Dual-Core UniFFI microkernel, memory safety, APFS CoW rollback, and architectural testing invariants.
• 系统架构与工程规范白皮书 (简体中文): 完整的中文系统架构设计白皮书与工程治理规范。
• Android Device Management & VFS Pipeline Guide: Native macOS driver-free MTP 1.1 / ADB SYNC dual-mode communication, Scoped Storage penetration, and Stream-First archive pipeline.

---

🌟 Key Highlights & Architectural Principles

• 🚀 Dual-Core Architecture (Swift 6 + Safe Rust Microkernel): High-throughput, memory-safe Rust native engine (rust/ttzip-engine compiled into TTZipVendor.xcframework), bridged via a standardized zero-overhead C-ABI & UniFFI (CTTZipBridge), orchestrated by Swift 6 complete concurrency (TTZipCore), and presented via POSIX CLI (ttzip), telemetry benchmark suite (ttzip-bench), and native desktop applications (apple/TTZipApp).
• ⚡️ 63+ GB/s Hardware Vector Dual-ISA Acceleration:
  • 63,232 MB/s (63.2 GB/s) CRC32: Hardware polynomial multiplication (vmull_p64 / __crc32d on ARM64, _mm_clmulepi64_si128 on x86_64).
  • 36,017 MB/s (36.0 GB/s) CRC64: Dual-ISA wide-folded polynomial reduction (ECMA-182).
  • AES-256 Vector Pipeline: Hardware crypto instructions for ZIP / 7Z encryption & decryption at memory bus bandwidth.
• 🏎 SOTA Codec Matrix:
  • Deflate (libdeflate): 4,742 MB/s single-core compression (L1) / 34,060 MB/s decompression (L9).
  • Zstandard (Zstd): 7,452 MB/s compression / 29,046 MB/s decompression (L3).
  • Google Snappy: 10,259 MB/s compression / 26,254 MB/s decompression.
  • Fast-LZMA2 (FL2): Multi-threaded extreme LZMA2 compression with radical match finders.
  • Apple LZFSE, Brotli, Bzip2 & Zopfli DAG: Native macOS acceleration, web stream codecs, and shortest-path graph optimization.
• 🔍 Sub-Nanosecond Virtual Filesystem Microkernels:
  • Constant-Time Magic Header Sniffing: 428.33 Million ops/s instant binary signature detection across 100+ formats.
  • Natural Numeric Sorting: 32.18 Million ops/s case-insensitive natural sort (img_2.png < img_10.png).
  • Compact Radix Archive Tree: 5,000-node hierarchy search in 308 microseconds (0.3 ms).
  • Zero-Disk-IO Instant Preview: Memory-mapped direct entry decompression without temporary files.
• 🛡 Cryptographic Memory Scrubbing & Error Correction:
  • DSE-Immune Memory Wipe (4,254 MB/s): Volatile pointer scrubbing to prevent Dead Store Elimination from leaking keys in memory.
  • Reed-Solomon Recovery Records (1,382 MB/s): Galois Field GF(2^8) forward error correction (FEC) for self-healing damaged archives.
  • Panic-Free Resilience: Hardened FFI boundary with catch_unwind isolation protecting all host processes.

---

📦 Supported Archive Formats (16 Full-Matrix Formats)

Format Category	Formats	Packing (Rust/Swift Engine)	Extraction (Safe Engine)	In-Memory Preview	Multi-Volume Split
Primary Modern	.zip, .7z, .tar, .tar.zst	✅ (Multi-Core)	✅ (Hardware SIMD)	✅ (0-Disk-IO)	✅ (.z01, .001)
High Compression	.tar.xz, .tar.bz2, .tar.gz, .lzip	✅	✅	✅	✅
Real-time / High Speed	.lz4, .brotli, .snappy, .aar	✅	✅	✅	-
System & Disk Images	.dmg, .iso, .wim	✅	✅	✅	-
Multi-Volume Split	.7z.001, .zip.001, .001	✅	✅	✅	✅
Legacy & Proprietary	.rar, .cbr, .zipx, .cab	Read-Only	✅	✅	-

---

📈 Real Physical Hardware Benchmarks (ttzip-bench matrix)

Tested on Apple Silicon M-Series (macOS 14+ / Darwin), compiled via Swift 6.0 & Rust Cargo with -O3 Release flags.

=================================================================
 TTZip High-Performance Native Archive Engine v1.0.0
 Dual-Core Engine: Swift 6 Concurrency + Safe Rust Microkernel
=================================================================

[1/3] Hardware Vector Checksums:
  • CRC32 (PMULL/ACLE/SSE4.2):  63,232.78 MB/s (63.2 GB/s)
  • CRC64 (PMULL/PCLMULQDQ):   36,017.11 MB/s (36.0 GB/s)

[2/3] SOTA Single-Core Compression Throughput:
  • Deflate (libdeflate L1)    -> Comp:  4,742.1 MB/s | Decomp:   7,464.7 MB/s [OK]
  • Deflate (libdeflate L6)    -> Comp:  1,294.2 MB/s | Decomp:  29,967.3 MB/s [OK]
  • Deflate (libdeflate L9)    -> Comp:    416.9 MB/s | Decomp:  34,060.7 MB/s [OK]
  • Zstandard (Zstd L1)        -> Comp:  7,322.2 MB/s | Decomp:  19,115.9 MB/s [OK]
  • Zstandard (Zstd L3)        -> Comp:  7,452.7 MB/s | Decomp:  29,046.9 MB/s [OK]
  • Google Snappy              -> Comp: 10,259.4 MB/s | Decomp:  26,254.6 MB/s [OK]

[3/4] Virtual Filesystem & Frontend Heavy Calculation Microkernels:
  • Magic Header Sniffing:        428.33 Million ops/s (Detected: PNG - image/png)
  • Natural Numeric Sorting:        32.18 Million ops/s (Result: -1)
  • Radix Tree 5000-Node Search:   308.38 µs (Found 1 matches: 'file_0042.dat')
  • DSE-Immune Memory Scrubbing:  4,254.14 MB/s
  • Reed-Solomon Recovery Parity: 1,382.18 MB/s

[4/4] Cross-Platform Rayon / TaskGroup Multi-Core Scaling:
  • Active Worker Threads: 18 P/E Workers

---

⚡️ Quick Installation & Building

1. Install via Homebrew

brew install wittkung/ttzip/ttzip-cli

2. Building ttzip CLI & Microkernel

Build the high-performance pure Rust POSIX CLI tool and microkernel libraries:

git clone https://github.com/wittkung/ttzip-core.git
cd ttzip-core

# Option A: Build ttzip CLI binary via Makefile
make cli

# Option B: Build via Cargo workspace directly
cd rust && cargo build --release --bin ttzip

3. Build via Swift Package Manager (SwiftPM)

# Build all release products (TTZipCore, CTTZipBridge, ttzip-bench)
swift build -c release

4. Build Rust Core Microkernel (ttzip-engine)

# Automatically compile universal static library & deploy to Vendor XCFramework
./scripts/build_rust.sh

# Or build directly via Cargo
cargo build --manifest-path rust/Cargo.toml --release

5. Run 100% Local Automated CI Verification (0 Cloud Quota)

./scripts/run_local_ci_gate.sh

---

🌐 Multi-Language Native SDK Matrix (9 Ecosystems)

ttzip-core provides first-class native bindings and zero-copy FFI wrappers across all major programming environments:

Language / Framework	Integration / Package	Quickstart Snippet
Rust	Cargo.toml: ttzip-engine = "1.0.0"	ttzip_engine::zip::compress(&src, &dst, 6)
Swift 6	Package.swift: .package(url: "...", branch: "main")	let engine = TTZipCoreEngine()
Python 3	pip install ttzip	import ttzip; ttzip.compress(["file.txt"], "out.zip")
Node.js / TS	npm install ttzip	import { createArchive } from "ttzip";
C11 Native	find_package(TTZip REQUIRED)	#include <ttzip.h> → ttzip_create_archive(...)
Modern C++20	find_package(TTZip REQUIRED)	#include <ttzip.hpp> → ttzip::compress_files(...)
Java 21+ (FFM)	com.ttzip:ttzip:1.0.0	TTZip.compress(List.of("src"), "out.zip");
Kotlin	com.ttzip:ttzip:1.0.0	file.ttzipCompress(destinationFile)
C# / .NET 8	TTZip.dll / NuGet	TTZipEngine.CreateArchive(sources, "out.zip");
Dart / Flutter	ttzip: ^1.0.0	await TTZip.compress(sources: ["src"], destination: "out.zip");

See the examples/ directory for complete, executable sample projects for every ecosystem.

---

💻 CLI Usage Guide (ttzip-cli)

ttzip-cli provides dedicated POSIX subcommands with pipeline and streaming support:

Common Commands

# 1. Create archives with SOTA compression
ttzip-cli archive backup.zip file1.txt docs/ photos/
ttzip-cli archive output.tar.zst /path/to/source --level 9

# 2. Parallel multi-core extraction
ttzip-cli extract archive.tar.zst -o ./extracted/
ttzip-cli extract archive.7z

# 3. Test archive CRC integrity
ttzip-cli test archive.zip

# 4. List and inspect archive contents
ttzip-cli list archive.zip
ttzip-cli inspect archive.7z

# 5. Interactive terminal TUI archive explorer
ttzip-cli explore archive.zip

# 6. Salvage and repair damaged archives
ttzip-cli repair damaged.zip -o repaired.zip

Subcommands Reference

Command	Aliases	Usage	Description
archive	create, a, c	ttzip-cli archive <out> <inputs...>	Create archive using SOTA codecs & parallel compression
extract	x, e	ttzip-cli extract <archive> [-o dir]	Multi-core parallel extraction with safe permission mapping
test	t, verify	ttzip-cli test <archive>	Verify archive CRC, headers, and container integrity
list	l, ls	ttzip-cli list <archive>	Print archive entry list, compressed size, and attributes
inspect	i, info	ttzip-cli inspect <archive>	Inspect detailed container metadata, codec, and compression ratio
explore	tui, browse	ttzip-cli explore <archive>	Launch interactive full-screen TUI archive browser
repair	recover	ttzip-cli repair <damaged> -o <fixed>	Reconstruct broken central directories and recover entries
bench	b, benchmark	ttzip-cli bench	Run hardware vector and codec throughput benchmarks
mcp	-	ttzip-cli mcp	Launch Model Context Protocol (MCP) server over standard I/O

---

🤖 Model Context Protocol (MCP) Server for AI Agents

ttzip-cli provides a built-in native Model Context Protocol (MCP) server running over standard input/output (stdio), allowing AI coding agents (Claude Desktop, Cursor, Antigravity, VS Code Copilot) to inspect, stream, extract, and create archives safely without writing ad-hoc shell or Python scripts.

Agent Tool Capabilities (8 Native Tools)

1. ttzip_list: Paginated metadata table of contents with glob filtering (include/exclude).
2. ttzip_extract: Sandboxed decompression with path traversal / Zip Slip interception and structured error codes.
3. ttzip_create: Multi-format archive creation (ZIP, 7z, TAR, Brotli, Snappy) with Pareto compression levels.
4. ttzip_inspect: Deep header diagnostics, encryption detection, compression ratio, and volume counts.
5. ttzip_cat: Zero-disk direct in-memory extraction of single entries directly into context.
6. ttzip_verify: Header and CRC32 integrity verification without writing to disk.
7. ttzip_convert: In-process transcode between archive containers.
8. ttzip_repair: Non-destructive salvage and central directory reconstruction for damaged archives.

Claude Desktop & Agent Configuration

Add the following to your claude_desktop_config.json or IDE MCP settings:

{
  "mcpServers": {
    "ttzip": {
      "command": "ttzip",
      "args": ["mcp"]
    }
  }
}

Virtual Resources & Interactive Manuals

• ttzip://manuals/overview: Architecture, formats, and tool guidelines.
• ttzip://manuals/format-matrix: Pareto tradeoffs and benchmark throughputs.
• ttzip://manuals/safe-extraction: Anti-Tar-Bomb and defensive extraction policies.
• ttzip://manuals/troubleshooting: Diagnostics for encrypted headers, split spans, and charsets.
• archive://{path}: Virtual file hierarchy table with sizes, CRCs, and encryption indicators.

---

📊 Benchmarking & Telemetry Guide (ttzip-bench)

ttzip-bench is a high-performance in-memory microbenchmarking utility communicating over the Rust Native C-ABI.

# 1. Run full in-memory multi-engine benchmark matrix
swift run ttzip-bench matrix

# 2. Run automated regression gate (CI/CD verification)
swift run ttzip-bench gate

# 3. Export structured telemetry JSON, interactive Pareto SVG, and Zen UI dashboard
swift run ttzip-bench plot --json-out telemetry.json --svg-out pareto.svg --html-out dashboard.html

---

💖 Giving Back to Upstream Open Source

TTZip stands upon the work of foundational open-source compression libraries:

• libarchive (Tim Kientzle, Martin Matuska)
• XZ Utils / liblzma (Lasse Collin, Igor Pavlov)
• libdeflate (Eric Biggers)
• Zstandard (zstd) (Yann Collet & Meta Compression Team)
• LZ4 (Yann Collet)
• 7-Zip / LZMA SDK (Igor Pavlov)

🌟 Upstream Contributions

We actively contribute verified hardware acceleration routines back to foundational upstream projects:

• libarchive/libarchive:
  • ✅ ARMv8 ACLE Hardware-Accelerated CRC32 & Architectural Unification (PR #3391 — Merged into master, Commit 8e439b92).
  • 🔄 7-Zip AES-256-CBC Stream Decryption Pipeline (PR #3388).
  • 💡 POSIX F_PREALLOCATE & fallocate Heuristics (Issue #3392 / PR #3393).
• zlib-ng/zlib-ng:
  • 🔄 ARM64 NEON compare256 Longest Match Vectorization & I-Cache Optimization (PR #2416): Optimized NEON sliding window pattern comparison with compact vmaxvq_u8 instruction sequences (-19% ~ -25% latency reduction on long matches, minimal I-cache footprint).

---

📄 License & Community Model

TTZip Core is dual-licensed under the BSD 3-Clause License and the Apache License (Version 2.0):

• See LICENSE-BSD and LICENSE-APACHE for complete terms.
• 100% Open Source: All source code in ttzip-core is available for commercial, academic, and personal use under OSI-approved licenses.
• Desktop Application Licensing: For the macOS desktop application (ttzip-apple), see apple/LICENSE (GPL-3.0-or-later).
• Commercial Inquiries: witt.w.kung@gmail.com.

---

© 2026 Witt Kung. All rights reserved.