update js client

2026-09-16 10:41:17 +07:00
parent edc528913e
commit dfd81a9dbe
14 changed files with 1090 additions and 2896 deletions
@@ -0,0 +1,514 @@
+# Requirements Document: msghandler
+
+**Version**: 1.4.1  
+**Date**: 2026-09-16  
+**Status**: Active  
+**Ground Truth**: [`src/msghandler.jl`](../src/msghandler.jl)
+
+**ASG Framework Alignment**: Structured per [`ASG_Framework/ASG_Framework.md`](../../ASG_Framework/ASG_Framework.md) (Eight Pillars) — user stories (`US-XXX`), functional/non-functional requirements with traceable IDs, success metrics & KPIs, boundary definitions, security, observability, and acceptance conditions.
+
+**Implementation Status**:
+- **Julia** ([`src/msghandler.jl`](../src/msghandler.jl)): ground truth, active.
+- **Python, JavaScript (CSR), Rust, MicroPython**: implementations present in [`src/`](../src) but not yet tested.
+
+---
+
+## 1. Business Context & Success Metrics
+
+### 1.1 Business Goal
+
+msghandler is a cross-platform, bi-directional data bridge that enables seamless communication between **Julia**, **JavaScript**, **Python**, **Rust**, and **MicroPython** applications using a message broker as the transport layer. The system implements the **Claim-Check pattern** for efficient handling of large payloads (>10KB) by uploading them to an HTTP file server instead of sending raw binary data over the transport layer.
+
+### 1.2 User Stories (with acceptance criteria)
+
+| ID | User Story | Acceptance Criteria |
+|----|------------|---------------------|
+| **US-001** | As a **Julia developer**, I want to send text messages to JavaScript/Python applications on a server or browser **so that** end users get text help across platforms | Text messages are serialized, encoded, and received correctly across platforms |
+| **US-002** | As a **Python developer**, I want to send tabular data to Julia applications **so that** DataFrame exchange works across platforms | DataFrame exchange works with both Arrow IPC and JSON formats |
+| **US-003** | As a **JavaScript developer** (server or browser), I want to send large files (>10KB) to other applications **so that** large payloads are transferred efficiently | Large files are automatically uploaded to file server and URLs are sent via the transport layer |
+| **US-004** | As a **MicroPython developer**, I want to send sensor data with minimal memory usage **so that** constrained devices can exchange data | Direct transport works for payloads <100KB on memory-constrained devices |
+| **US-005** | As a **Rust developer**, I want to send and receive messages with type-safe APIs **so that** type safety and async connectivity are guaranteed | Rust implementation uses serde for serialization, tokio for async, and transport-agnostic client for connectivity |
+| **US-006** | As a **developer**, I want to send mixed-content messages (text + image + file) **so that** rich messages are handled appropriately | msghandler accepts list of (dataname, data, type) tuples and handles each payload appropriately |
+| **US-007** | As a **developer**, I want to receive multi-payload messages **so that** all payloads are returned with correct types preserved | msghandler returns payloads as list of tuples with correct types preserved |
+| **US-008** | As a **developer**, I want to use Plik as the file server **so that** large uploads use one-shot mode with ID/token handling | Plik one-shot upload mode is supported with upload ID and token handling |
+| **US-009** | As a **developer**, I want to use custom HTTP file servers **so that** the file backend is pluggable (AWS S3, custom) | Handler function abstraction allows plugging in AWS S3 or custom implementations |
+| **US-010** | As a **developer**, I want automatic retry on file server download failures **so that** transient failures recover automatically | Exponential backoff with configurable retries (default: 5, base_delay: 100ms, max_delay: 5000ms) |
+| **US-011** | As a **developer**, I want message tracing across distributed systems **so that** message flow is observable end-to-end | Correlation ID is propagated through all message processing steps |
+
+### 1.3 Success Metrics & KPIs
+
+**Functional Requirements KPIs:**
+- **FR-001** (Cross-platform text messaging): 95% of text messages delivered correctly across all platform pairs (<200ms latency) - Measured via synthetic cross-platform tests
+- **FR-002** (Cross-platform tabular data): 100% Arrow IPC round-trip integrity (Desktop), 100% JSON table round-trip integrity (Browser) - Measured via data validation tests
+- **FR-003** (Large file handling): 99% successful file uploads to server for payloads ≥10KB - Measured via integration tests
+- **FR-004** (Direct transport for small payloads): 100% of payloads <10KB use direct transport - Measured via transport selection tests
+- **FR-005** (MicroPython support): 100% of payloads <100KB delivered on MicroPython devices - Measured via MicroPython integration tests
+- **FR-006** (Multi-payload messages): 100% correct parsing of multi-payload message lists - Measured via multi-payload tests
+- **FR-007** (Payload type preservation): 100% type integrity preserved across all platforms - Measured via type validation tests
+- **FR-008** (Plik file server integration): 100% successful Plik upload/token handling - Measured via Plik integration tests
+- **FR-009** (Custom file server support): 100% handler abstraction works with custom implementations - Measured via custom server integration tests
+- **FR-010** (Exponential backoff retry): 95% successful downloads within retry limit - Measured via failure injection tests
+- **FR-011** (Correlation ID propagation): 100% correlation IDs propagated through all steps - Measured via tracing tests
+- **FR-012** (Message serialization): <50ms serialization overhead for 10KB payload - Measured via benchmark tests
+- **FR-013** (Transport publishing): 100% JSON envelope generated correctly - Measured via serialization tests
+- **FR-014** (Transport subscription): 100% JSON messages processed correctly - Measured via deserialization tests
+
+**Non-Functional Requirements KPIs:**
+- **NFR-101** (Message serialization overhead): <50ms for 10KB payload - Measured via benchmark tests
+- **NFR-102** (Message deserialization overhead): <50ms for 10KB payload - Measured via benchmark tests
+- **NFR-103** (Transport connection establishment): <100ms average - Measured via connection pool benchmarks
+- **NFR-104** (File upload latency): <1s for 10KB file - Measured via integration tests
+- **NFR-105** (File download latency): <1s for 10KB file - Measured via integration tests
+- **NFR-106** (Concurrent connections): 100+ simultaneous transport connections - Measured via scale testing
+- **NFR-107** (Message throughput): 1000+ messages/second per instance - Measured via load testing
+- **NFR-108** (File server scalability): Horizontal scaling verified via architecture review
+- **NFR-201** (Message delivery): At-least-once delivery via transport - Measured via message acknowledgment tests
+- **NFR-202** (File server availability): <5% failure rate when file server unavailable - Measured via failure injection tests
+- **NFR-203** (Connection recovery): Auto-reconnect within 30s - Measured via connection failure tests
+- **NFR-301** (Payload integrity): 100% SHA-256 checksum validation - Measured via integrity tests
+- **NFR-302** (Transport security): 100% TLS connections in production - Measured via connection audits
+- **NFR-303** (File server security): 100% authenticated file uploads - Measured via security tests
+- **NFR-401** (Required logs): 100% messages logged with required fields - Measured via log validation
+- **NFR-402** (Critical metrics): 100% metrics collected with 1-minute granularity - Measured via metrics pipeline tests
+- **NFR-403** (Tracing): 100% correlation ID propagation for tracing - Measured via tracing validation
+- **NFR-404** (Alerting): <5min alert latency for `download_retry_exceeded` - Measured via alert pipeline tests
+- **NFR-405** (Retention): Logs: 30 days, Metrics: 1 year - Measured via storage audits
+
+---
+
+## 2. Technical Boundaries
+
+### 2.1 In Scope
+
+| Feature | Description |
+|---------|-------------|
+| Cross-platform interoperability | Seamless data exchange between Julia, JavaScript, Python, Rust, and MicroPython |
+| Intelligent transport selection | Direct transport (<10KB) vs Link transport (≥10KB) based on payload size |
+| Unified API | Consistent `smartpack()` and `smartunpack()` functions across all platforms |
+| Multi-payload support | List of (dataname, data, type) tuples with appropriate handling |
+| File server integration | Plik one-shot upload and custom HTTP server support |
+| Reliability features | Exponential backoff retry and correlation ID propagation |
+| Message serialization | Converts data types to binary format (Base64, JSON, Arrow IPC) |
+| Transport communication | Publishing and subscription via message broker (NATS, MQTT, WebSocket, etc.) |
+
+### 2.2 Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Advanced transport features | Basic transport sufficient for current use cases |
+| Message compression | Compression adds complexity without clear benefit |
+| Message encryption | Payload encryption is application-layer concern |
+| Persistent message queues | Transport request-reply pattern sufficient |
+| Advanced routing rules | Simple topic matching sufficient |
+
+### 2.3 Dependencies
+
+| Platform | Package | Version |
+|----------|---------|---------|
+| Julia | JSON.jl | Latest stable |
+| Julia | Arrow.jl | Latest stable |
+| Julia | HTTP.jl | Latest stable |
+| Julia | UUIDs.jl | Latest stable |
+| Python | aiohttp | Latest stable |
+| Python | pyarrow | Latest stable |
+| Browser | - | Transport-agnostic (caller provides) |
+| Rust | serde | Latest stable |
+| Rust | serde_json | Latest stable |
+| Rust | tokio | Latest stable |
+| Rust | uuid | Latest stable |
+
+### 2.4 Platform Compatibility
+
+| Platform | Minimum Version | Notes |
+|----------|-----------------|-------|
+| Julia | 1.7+ | Arrow.jl required for arrowtable support |
+| Python | 3.8+ | pyarrow required for arrowtable support |
+| Browser | Latest | No Arrow IPC (uses jsontable only) |
+| Rust | 1.70+ | Full support with async/await, Arrow IPC on desktop |
+| MicroPython | 1.19+ | Limited to direct transport |
+
+---
+
+## 3. Functional Requirements (FR)
+
+| ID | Requirement | Description | Traceability |
+|----|-------------|-------------|--------------|
+| **FR-001** | Cross-platform text messaging | System shall allow users to send text messages between Julia, JavaScript, Python, and MicroPython applications | US-001 |
+| **FR-002** | Cross-platform tabular data | System shall support DataFrame exchange between Julia and Python applications using Arrow IPC format | US-002 |
+| **FR-003** | Large file handling | System shall automatically detect payloads ≥10KB and upload them to HTTP file server instead of sending via transport | US-003 |
+| **FR-004** | Direct transport for small payloads | System shall send payloads <10KB directly via transport without file server upload | US-001, US-003, US-004 |
+| **FR-005** | MicroPython support | System shall support payloads <100KB on MicroPython devices using direct transport | US-004 |
+| **FR-006** | Multi-payload messages | System shall accept and process lists of (dataname, data, type) tuples | US-006, US-007 |
+| **FR-007** | Payload type preservation | System shall preserve payload types when returning multi-payload messages | US-006, US-007 |
+| **FR-008** | Plik file server integration | System shall support Plik one-shot upload mode with upload ID and token handling | US-008 |
+| **FR-009** | Custom file server support | System shall provide handler function abstraction for custom HTTP file server implementations | US-009 |
+| **FR-010** | Exponential backoff retry | System shall implement exponential backoff with configurable retries (default: 5, base_delay: 100ms, max_delay: 5000ms) for file server download failures | US-010 |
+| **FR-011** | Correlation ID propagation | System shall propagate correlation IDs through all message processing steps | US-011 |
+| **FR-012** | Message serialization | System shall serialize data types using Base64, JSON, or Arrow IPC encoding | US-001, US-002, US-006 |
+| **FR-013** | Transport publishing | System shall return JSON string representation for caller to publish via transport layer (caller is responsible for actual transport publish) | US-006 |
+| **FR-014** | Transport subscription | System shall receive and process messages by accepting JSON string from transport payload | US-007 |
+
+---
+
+## 4. Non-Functional Requirements (NFRs)
+
+**Requirement vs KPI Clarification:**
+- **FR and NFR** is a *requirement* — it defines what quality or constraint the system must have (e.g., "System shall support 10K TPS", "99.9% monthly uptime", "TLS 1.3+ encryption")
+- **KPI** is a *measurement* — it's the actual data collected to verify if the requirement was met (e.g., "Peak traffic was 8.5K TPS", "MTTR was 8 minutes", "100% of connections use TLS 1.3")
+- Requirements tell you **what to build**; KPIs tell you **how well you built it**
+
+### 4.1 Performance & Scalability
+
+| ID | Requirement | Specification | KPI | Test Method |
+|----|-------------|---------------|-----|-------------|
+| **NFR-101** | Message serialization overhead | <50ms for 10KB payload | <50ms for 10KB payload | Benchmark tests |
+| **NFR-102** | Message deserialization overhead | <50ms for 10KB payload | <50ms for 10KB payload | Benchmark tests |
+| **NFR-103** | Transport connection establishment | <100ms | <100ms average | Connection pool benchmarks |
+| **NFR-104** | File upload latency | <1s for 10KB file | <1s for 10KB file | Integration tests |
+| **NFR-105** | File download latency | <1s for 10KB file | <1s for 10KB file | Integration tests |
+| **NFR-106** | Concurrent connections | Support 100+ simultaneous transport connections | 100+ simultaneous connections | Scale testing |
+| **NFR-107** | Message throughput | Handle 1000+ messages/second per instance | 1000+ messages/second | Load testing |
+| **NFR-108** | File server scalability | Support horizontal scaling of file server backend | Horizontal scaling verified | Architecture review |
+
+### 4.2 Availability & Reliability
+
+| ID | Requirement | Specification | KPI | Test Method |
+|----|-------------|---------------|-----|-------------|
+| **NFR-201** | Message delivery | At-least-once delivery semantics via transport | At-least-once delivery via transport | Message acknowledgment tests |
+| **NFR-202** | File server availability | Graceful degradation when file server is unavailable | <5% failure rate when file server unavailable | Failure injection tests |
+| **NFR-203** | Connection recovery | Auto-reconnect on transport connection failure | Auto-reconnect within 30s | Connection failure tests |
+
+### 4.3 Privacy & Security
+
+- **Data Classification**: Payloads carry binary artifacts (image/audio/video) and tabular/text/dictionary data; classified as internal/commercial. msghandler itself stores or transmits no PHI/PII.
+- **Encryption**: TLS 1.3+ for transport connections (NFR-302) and file server HTTPS (NFR-303). Payload-body encryption is an application-layer concern and out of scope.
+- **Authentication**: File server uploads are authenticated via the Plik `X-UploadToken` (NFR-303); transport/broker authentication is provided by the caller's implementation.
+- **Compliance**: No built-in compliance controls; msghandler relies on the transport layer and application layer for GDPR/SOC2/HIPAA as required by the caller.
+
+| ID | Requirement | Specification | KPI | Test Method |
+|----|-------------|---------------|-----|-------------|
+| **NFR-301** | Payload integrity | SHA-256 checksum support via metadata | 100% SHA-256 checksum validation | Integrity tests |
+| **NFR-302** | Transport security | TLS support for transport connections | 100% TLS connections in production | Connection audits |
+| **NFR-303** | File server security | Authentication token for file uploads | 100% authenticated file uploads | Security tests |
+
+### 4.4 Observability & Telemetry
+
+| ID | Requirement | Specification | KPI | Test Method |
+|----|-------------|---------------|-----|-------------|
+| **NFR-401** | Required logs | `correlation_id`, `msg_id`, `timestamp`, `sender_name`, `receiver_name`, `payload_type`, `transport` | 100% messages logged with required fields | Log validation |
+| **NFR-402** | Critical metrics | `messages_sent_total`, `messages_received_total`, `file_upload_duration_seconds`, `file_download_duration_seconds`, `retry_attempts_total` | 100% metrics collected with 1-minute granularity | Metrics pipeline tests |
+| **NFR-403** | Tracing | Correlation ID propagation for request tracing | 100% correlation ID propagation for tracing | Tracing validation |
+| **NFR-404** | Alerting | `download_retry_exceeded` triggers alert when max retries exceeded | <5min alert latency for `download_retry_exceeded` | Alert pipeline tests |
+| **NFR-405** | Retention | Logs: 30 days, Metrics: 1 year | Logs: 30 days, Metrics: 1 year | Storage audits |
+
+---
+
+## 5. Acceptance Conditions
+
+| Condition | Description |
+|-----------|-------------|
+| **AC-001** | All functional requirements FR-001 through FR-014 are implemented and tested |
+| **AC-002** | All non-functional requirements NFR-101 through NFR-405 meet specified KPI targets |
+| **AC-003** | Cross-platform text message test passes (Julia ↔ JavaScript ↔ Python) |
+| **AC-004** | Cross-platform tabular data test passes with Arrow IPC round-trip (Desktop) |
+| **AC-005** | Cross-platform tabular data test passes with JSON table round-trip (Browser) |
+| **AC-006** | Large file transfer test passes with file server upload/download |
+| **AC-007** | Multi-payload mixed content test passes with all payload types in one message |
+| **AC-008** | CI validation gates block PRs on specification violations |
+| **AC-009** | Unit test coverage exceeds 80% |
+| **AC-010** | Documentation is complete and includes walkthroughs, architecture, and runbook |
+
+---
+
+## 6. Payload Type Requirements
+
+### 6.1 Supported Payload Types
+
+| Type | Julia | JavaScript | Python | MicroPython | Description |
+|------|-------|------------|--------|-------------|-------------|
+| `text` | `String` | `string` | `str` | `String` | Plain text strings |
+| `dictionary` | `Dict`, `NamedTuple` | `Object`, `Array` | `dict`, `list` | `dict` | JSON-serializable data |
+| `arrowtable` | `DataFrame`, `Arrow.Table` | ❌ (Browser) | `pandas.DataFrame` | ❌ | Tabular data (Arrow IPC) |
+| `jsontable` | `Vector{NamedTuple}` | `Array<Object>` | `list[dict]` | ❌ | Tabular data (JSON) - **Only table type in Browser** |
+| `image` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytes` | Image binary data |
+| `audio` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytes` | Audio binary data |
+| `video` | `Vector{UInt8}` | `Uint8Array`, `Buffer` | `bytes` | `bytes` | Video binary data |
+| `binary` | `Vector{UInt8}`, `IOBuffer` | `Uint8Array`, `Buffer` | `bytes`, `bytearray` | `bytes`, `bytearray` | Generic binary data |
+
+### 6.2 Encoding Requirements
+
+| Payload Type | Encoding Method | Notes |
+|--------------|-----------------|-------|
+| `text` | UTF-8 → Base64 | Text must be String type |
+| `dictionary` | JSON → Base64 | JSON.jl for Julia |
+| `arrowtable` | Arrow IPC → Base64 | Requires Arrow.jl/pyarrow (Desktop only) |
+| `jsontable` | JSON → Base64 | Human-readable format - **Browser uses this only** |
+| `image`/`audio`/`video`/`binary` | Direct → Base64 | Binary data preserved |
+
+---
+
+## 7. Size Threshold Requirements
+
+### 7.1 Direct Transport Threshold
+
+| Platform | Threshold | Notes |
+|----------|-----------|-------|
+| Desktop (Julia/JS/Python) | 10KB | Default size threshold |
+| Rust | 10KB | Default size threshold |
+| MicroPython | 100KB | Lower threshold for memory constraints |
+
+### 7.2 Maximum Payload Size
+
+| Platform | Maximum | Notes |
+|----------|---------|-------|
+| Desktop | Unlimited | Limited by transport server configuration |
+| Rust | Unlimited | Limited by transport server configuration |
+| MicroPython | 50KB | Hard limit due to 256KB-1MB memory |
+
+---
+
+## 8. Message Envelope Requirements
+
+### 8.1 Required Fields
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `correlation_id` | String (UUID) | Track message flow across systems |
+| `msg_id` | String (UUID) | Unique message identifier |
+| `timestamp` | String (ISO 8601) | Message publication timestamp |
+| `send_to` | String | Topic/subject to publish to |
+| `msg_purpose` | String | ACK, NACK, updateStatus, shutdown, chat |
+| `sender_name` | String | Sender application name |
+| `sender_id` | String (UUID) | Sender unique identifier |
+| `receiver_name` | String | Receiver application name (empty = broadcast) |
+| `receiver_id` | String (UUID) | Receiver unique identifier (empty = broadcast) |
+| `reply_to` | String | Topic for reply messages |
+| `reply_to_msg_id` | String | Message ID being replied to |
+| `broker_url` | String | Broker URL for the transport layer |
+| `metadata` | Dict | Message-level metadata |
+| `payloads` | Array | List of payload objects |
+
+### 8.2 Payload Fields
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `id` | String (UUID) | Unique payload identifier |
+| `dataname` | String | Name of the payload |
+| `payload_type` | String | Type: text, dictionary, arrowtable, etc. |
+| `transport` | String | direct or link |
+| `encoding` | String | none, json, base64, arrow-ipc |
+| `size` | Integer | Payload size in bytes |
+| `data` | Any | Base64 string or URL |
+| `metadata` | Dict | Payload-level metadata |
+
+---
+
+## 9. Error Handling Requirements
+
+### 9.1 Error Codes
+
+| Error | Condition | Response |
+|-------|-----------|----------|
+| `Unknown payload_type` | Unsupported type | Throw error |
+| `Failed to upload` | File server error | Throw error |
+| `Failed to fetch` | File server unavailable | Retry with exponential backoff |
+| `Unknown transport` | Invalid transport type | Throw error |
+| `Transport connection failed` | Transport/broker unavailable | Throw error |
+
+### 9.2 Exception Handling
+
+| Scenario | Handler |
+|----------|---------|
+| File server unavailable | Retry up to 5 times with exponential backoff |
+| Transport publish failure | Handled by caller |
+| Deserialization error | Log correlation ID and throw error |
+| Memory overflow (MicroPython) | Reject payloads >50KB |
+
+---
+
+## 10. Testing Requirements
+
+### 10.1 Unit Tests
+
+| Test Category | Coverage | Files |
+|---------------|----------|-------|
+| Serialization | All payload types | `test/test_*_sender.*` |
+| Deserialization | All payload types | `test/test_*_receiver.*` |
+| Transport selection | Direct vs link | `test/test_*_mix_payloads.*` |
+| File server upload | Plik integration | Platform-specific |
+| File server download | Exponential backoff | Platform-specific |
+
+### 10.2 Integration Tests
+
+| Test Scenario | Success Criteria |
+|-------------|-----------------|
+| Cross-platform text message | Julia ↔ JavaScript ↔ Python |
+| Cross-platform tabular data (Desktop) | Arrow IPC round-trip |
+| Cross-platform tabular data (Browser) | JSON table round-trip |
+| Large file transfer | File server upload/download |
+| Multi-payload mixed content | All payload types in one message |
+
+---
+
+## 11. API Contract
+
+### 11.1 smartpack Signature
+
+```julia
+function smartpack(
+    subject::String,
+    data::AbstractArray{Tuple{String, T1, String}, 1};
+    broker_url::String = DEFAULT_BROKER_URL,
+    fileserver_url::String = DEFAULT_FILESERVER_URL,
+    fileserver_upload_handler::Function = plik_oneshot_upload,
+    size_threshold::Int = DEFAULT_SIZE_THRESHOLD,
+    correlation_id::String = string(uuid4()),
+    msg_purpose::String = "chat",
+    sender_name::String = "msghandler",
+    receiver_name::String = "",
+    receiver_id::String = "",
+    reply_to::String = "",
+    reply_to_msg_id::String = "",
+    msg_id::String = string(uuid4()),
+    sender_id::String = string(uuid4())
+)::Tuple{msg_envelope_v1, String} where {T1<:Any}
+```
+
+**Note**: Publishing via the transport layer is the caller's responsibility. `smartpack` returns `(env::msg_envelope_v1, env_json_str::String)`.
+
+### 11.2 smartunpack Signature
+
+```julia
+function smartunpack(
+    msg_json_str::String;
+    fileserver_download_handler::Function = _fetch_with_backoff,
+    max_retries::Int = 5,
+    base_delay::Int = 100,
+    max_delay::Int = 5000
+)::JSON.Object{String, Any}
+```
+
+**Note**: Pass the payload string from the transport subscription to `smartunpack`. The input is the JSON string payload from the transport message, not the transport message object directly.
+
+**Note**: Pass the payload from the transport subscription to `smartunpack`.
+
+---
+
+## 12. Deployment Requirements
+
+### 12.1 Minimum Infrastructure
+
+| Component | Minimum | Notes |
+|-----------|---------|-------|
+| Message Broker | 1 instance | Single node for development |
+| File Server | 1 instance | HTTP server for large payloads |
+| Client Memory | 50MB | Desktop platforms (Julia/JS/Python) |
+| Client Memory | 256KB | MicroPython devices |
+
+### 12.2 Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BROKER_URL` | `ws://localhost:4222` | Message broker URL |
+| `FILESERVER_URL` | `http://localhost:8080` | HTTP file server URL |
+| `SIZE_THRESHOLD` | `10000` | Size threshold in bytes (10KB) |
+
+---
+
+## 13. Versioning
+
+### 13.1 Current Version
+
+- **Major**: 1 (Breaking changes require major version bump)
+- **Minor**: 0 (Feature additions)
+- **Patch**: 0 (Bug fixes)
+
+### 13.2 Version Compatibility
+
+| Version | Supported Platforms |
+|---------|---------------------|
+| v1.0.x | Julia 1.7+, Python 3.8+, Rust 1.70+, Browser (latest), MicroPython 1.19+ |
+
+---
+
+## 14. Change Log
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-09-16 | 1.4.0 | Structured per ASG Framework Eight Pillars |
+| - | - | Added `US-XXX` user story IDs and FR→US traceability in sections 1.2 and 3 |
+| - | - | Added Data Classification / Encryption / Authentication / Compliance bullets under NFR-301–303 |
+| - | - | Added ASG-alignment and implementation-status notes (Julia ground truth) |
+| 2026-05-22 | 1.3.0 | Updated to ASG Framework v8 pillars - added KPIs to all FR and NFR requirements |
+| - | - | Added Success Metrics & KPIs section with measurable targets for each requirement |
+| - | - | Added NFR vs KPI clarification section |
+| - | - | Updated NFR tables to include KPI column and Test Method column |
+| 2026-05-15 | 1.3.0 | Made transport layer agnostic |
+| - | - | Removed all NATS-specific dependencies and references |
+| - | - | Updated all NATS references to generic "transport layer"/"message broker" |
+| - | - | Removed NATS client packages from dependencies tables |
+| 2026-05-13 | 1.2.0 | Aligned with ground truth implementation (src/msghandler.jl) |
+| - | - | Fixed smartpack signature: removed is_publish, NATS_connection; added sender_name |
+| - | - | Fixed smartunpack signature: takes msg_json_str::String instead of msg::NATS.Msg |
+| - | - | Fixed size_threshold default from 1,000,000 to 500,000 |
+| - | - | Updated FR-013/FR-014 to reflect caller responsibility for NATS publishing |
+| - | - | Updated FR-008/FR-009 to include file path upload overload |
+| - | - | Updated SIZE_THRESHOLD env var default to 10000 |
+| 2026-03-23 | 1.0.0 | Updated to ASG Framework requirements structure |
+
+---
+
+## 15. Requirements Traceability Matrix
+
+| Requirement ID | Description | Implementation File | Test File |
+|----------------|-------------|---------------------|-----------|
+| FR-001 | Cross-platform text messaging | `src/msghandler.jl` | `test/test_*_sender.*` |
+| FR-002 | Cross-platform tabular data | `src/msghandler.jl` | `test/test_*_sender.*` |
+| FR-003 | Large file handling | `src/msghandler.jl` | `test/test_*_fileserver.*` |
+| FR-004 | Direct transport for small payloads | `src/msghandler.jl` | `test/test_*_transport.*` |
+| FR-005 | MicroPython support | `src/msghandler_mpy.py` | `test/test_mpy.*` |
+| FR-006 | Multi-payload messages | `src/msghandler.jl` | `test/test_*_mix_payloads.*` |
+| FR-007 | Payload type preservation | `src/msghandler.jl` | `test/test_*_types.*` |
+| FR-008 | Plik file server integration | `src/msghandler.jl` | `test/test_plik.*` |
+| FR-009 | Custom file server support | `src/msghandler.jl` | `test/test_custom_server.*` |
+| FR-010 | Exponential backoff retry | `src/msghandler.jl` | `test/test_retry.*` |
+| FR-011 | Correlation ID propagation | `src/msghandler.jl` | `test/test_tracing.*` |
+| FR-012 | Message serialization | `src/msghandler.jl` | `test/test_*_serialization.*` |
+| FR-013 | Transport publishing | `src/msghandler.jl` | `test/test_*_transport.*` |
+| FR-014 | Transport subscription | `src/msghandler.jl` | `test/test_*_receiver.*` |
+| NFR-101 | Message serialization overhead | `src/msghandler.jl` | `test/test_benchmarks.*` |
+| NFR-102 | Message deserialization overhead | `src/msghandler.jl` | `test/test_benchmarks.*` |
+| NFR-103 | Transport connection establishment | `src/msghandler.jl` | `test/test_connection.*` |
+| NFR-104 | File upload latency | `src/msghandler.jl` | `test/test_fileserver.*` |
+| NFR-105 | File download latency | `src/msghandler.jl` | `test/test_fileserver.*` |
+| NFR-106 | Concurrent connections | `src/msghandler.jl` | `test/test_scale.*` |
+| NFR-107 | Message throughput | `src/msghandler.jl` | `test/test_load.*` |
+| NFR-108 | File server scalability | `docs/architecture.md` | `docs/validation.md` |
+| NFR-201 | Message delivery | `src/msghandler.jl` | `test/test_delivery.*` |
+| NFR-202 | File server availability | `src/msghandler.jl` | `test/test_failure_injection.*` |
+| NFR-203 | Connection recovery | `src/msghandler.jl` | `test/test_reconnect.*` |
+| NFR-301 | Payload integrity | `src/msghandler.jl` | `test/test_integrity.*` |
+| NFR-302 | Transport security | `src/msghandler.jl` | `test/test_security.*` |
+| NFR-303 | File server security | `src/msghandler.jl` | `test/test_security.*` |
+| NFR-401 | Required logs | `src/msghandler.jl` | `test/test_logging.*` |
+| NFR-402 | Critical metrics | `src/msghandler.jl` | `test/test_metrics.*` |
+| NFR-403 | Tracing | `src/msghandler.jl` | `test/test_tracing.*` |
+| NFR-404 | Alerting | `src/msghandler.jl` | `test/test_alerting.*` |
+| NFR-405 | Retention | `docs/runbook.md` | `docs/validation.md` |
+
+---
+
+## 16. References
+
+- [`src/msghandler.jl`](../src/msghandler.jl) - Ground truth implementation (Julia)
+- [`src/msghandler_csr.js`](../src/msghandler_csr.js) - Client-side JavaScript implementation
+- [`src/msghandler.py`](../src/msghandler.py) - Python implementation
+- [`src/msghandler_mpy.py`](../src/msghandler_mpy.py) - MicroPython implementation
+- [`src/msghandler.rs`](../src/msghandler.rs) - Rust implementation
+- [`README.md`](../README.md) - Project overview
+- [`docs/specification.md`](./specification.md) - Technical specification
+- [`docs/ui-specification.md`](./ui-specification.md) - UI specification
+- [`docs/walkthrough.md`](./walkthrough.md) - End-to-end walkthrough
+- [`docs/architecture.md`](./architecture.md) - Architecture documentation
+- [`docs/validation.md`](./validation.md) - Validation and CI/CD
+- [`docs/runbook.md`](./runbook.md) - Operational runbook