qtsq 1.0.0__tar.gz

qtsq-1.0.0/LICENSE

@@ -0,0 +1,128 @@
+# Quantum Tensor Sequence Proprietary License (QTSPL) v1.0
+
+**Copyright (c) 2026 Haruhito. All Rights Reserved.**
+
+---
+
+## 1. Definitions
+
+- **"Software"** refers to the Quantum Tensor Sequence (.qtsq) file format specification, all associated source code, libraries, tools, documentation, algorithms, and data structures contained in this repository.
+- **"Author"** refers to Haruhito, the sole copyright holder.
+- **"Format"** refers to the .qtsq (Quantum Tensor Sequence) and .qtsw (Event Wave) binary file formats.
+- **"Marks"** refers to the names "Quantum Tensor Sequence", ".qtsq", ".qtsw", "Spaghettification Engine", "Cosmic Censorship", "Hawking Radiation", "Gravitational Waves", and all associated branding, logos, and terminology.
+
+---
+
+## 2. Grant of Rights
+
+You are granted a limited, non-exclusive, non-transferable, revocable license to use the Software strictly for **free non-commercial personal, educational (school), and academic research purposes**, subject to the conditions set forth in this license.
+
+All other rights, including commercial use, distribution, and modification, are strictly reserved by the Author.
+
+---
+
+## 3. Restrictions
+
+Except for the permitted uses expressly granted in Section 2, you may **NOT**, without prior written authorization from the Author:
+
+### 3.1 Commercial and Unauthorized Use
+- Use the Software, in whole or in part, for any commercial, corporate, or for-profit purpose.
+- Incorporate any portion of the Software into any commercial software, product, or service.
+- Use the Format to read, write, create, or process .qtsq or .qtsw files for any commercial purpose.
+
+### 3.2 Modify
+- Modify, adapt, translate, reverse engineer, decompile, disassemble, or create derivative works based on the Software.
+- Alter the Format specification in any way.
+
+### 3.3 Distribute
+- Copy, distribute, publish, sublicense, sell, lease, rent, or otherwise transfer the Software or any portion thereof.
+- Share, upload, or make the Software available through any medium, including but not limited to code repositories, file sharing services, or electronic communication.
+
+### 3.4 Compete
+- Develop, produce, market, or distribute any software, tool, library, or service that reads, writes, processes, or is compatible with the .qtsq or .qtsw file formats.
+- Create any file format, specification, or standard that is substantially similar to or derived from the Format.
+
+### 3.5 Brand
+- Use any of the Marks in any product name, service name, domain name, social media account, marketing material, or any other context.
+- Register any trademark, domain name, or intellectual property that contains or is confusingly similar to any of the Marks.
+- Imply any endorsement, affiliation, or association with the Author without written consent.
+
+---
+
+## 4. Attribution and Credits
+
+For the permitted free uses defined in Section 2, the following attribution rules apply:
+
+- **Academic & Research Use:** If the Software or Format is used in any published academic, scientific, or institutional research, you **MUST** provide appropriate credit and citation to the Author (Haruhito) and the Quantum Tensor Sequence project.
+- **Personal & Educational (School) Use:** Adding credits is **optional but highly appreciated**. If you use this for a school project or personal hobby, mentioning the Quantum Tensor Sequence project is a great way to show support.
+
+---
+
+## 5. Research Paper
+
+The research paper titled "Quantum Tensor Sequence: A Universal Data Compression Format with Physics-Inspired Architecture, Zero-Knowledge Verification, and Self-Healing Recovery" is published for informational and academic reference purposes only. Publication of the paper does **not** constitute a grant of any license, right, or permission to use, implement, or reproduce the Software, Format, or any techniques described therein.
+
+---
+
+## 6. Licensing Inquiries
+
+To obtain a license for commercial use or any use outside the scope of Section 2, contact the Author directly. Licensing terms, fees, and conditions are determined solely at the Author's discretion.
+
+---
+
+## 7. Intellectual Property
+
+The Software, Format, Marks, and all associated intellectual property are the exclusive property of the Author. This includes but is not limited to:
+
+- The .qtsq and .qtsw binary file format specifications
+- The five-layer gravitational compression architecture
+- The Spaghettification Engine (automatic data type detection and strategy selection)
+- The Cosmic Censorship dual-layer security system (AES-256-GCM + Schnorr ZKP)
+- The Wormhole inter-file linking system
+- The Gravitational Wave differential update system
+- The Redshift/Blueshift multi-resolution quality scaling system
+- The Chandrasekhar Limit adaptive threshold system
+- The Information Paradox error correction and recovery system
+- All source code, documentation, and related materials
+
+---
+
+## 8. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+---
+
+## 9. Limitation of Liability
+
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+## 10. Termination
+
+Any unauthorized use of the Software, Format, or Marks automatically terminates the permissions granted herein and may result in legal action. The Author reserves the right to pursue all available legal remedies for any violation of this license.
+
+---
+
+## 11. Governing Law
+
+This license shall be governed by and construed in accordance with the laws of India. Any disputes arising under this license shall be subject to the exclusive jurisdiction of the courts in India.
+
+---
+
+## 12. Severability
+
+If any provision of this license is held to be unenforceable or invalid, that provision shall be modified to the minimum extent necessary to make it enforceable, and all remaining provisions shall continue in full force and effect.
+
+---
+
+## 13. Entire Agreement
+
+This license constitutes the entire agreement between the parties regarding the Software and supersedes all prior agreements, understandings, and communications, whether written or oral.
+
+---
+
+**Quantum Tensor Sequence Proprietary License (QTSPL) v1.0**
+**Effective Date: March 2026**
+**Copyright (c) 2026 Haruhito. All Rights Reserved.**

qtsq-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# Include all C source and headers for compilation
+recursive-include src *.c *.h
+recursive-include include *.h
+include qtsq/_native.c
+include qtsq/_metal_stubs.c
+include qtsq/README.md
+include setup.py

qtsq-1.0.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: qtsq
+Version: 1.0.0
+Summary: Read and extract data from .qtsq (Quantum Tensor Sequence) image files
+Author: haruhito
+License: Proprietary
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: ml
+Requires-Dist: torch>=2.0.0; extra == "ml"
+Requires-Dist: torch-geometric>=2.4.0; extra == "ml"
+Provides-Extra: images
+Requires-Dist: Pillow>=9.0.0; extra == "images"
+Dynamic: license-file

qtsq-1.0.0/include/qtsq.h

@@ -0,0 +1,261 @@
+/*
+ * Quantum Tensor Sequence — Universal Public API
+ * File Extension: .qtsq (Quantum Tensor Sequence)
+ * Author: Haruhito
+ */
+
+#ifndef QTSQ_H
+#define QTSQ_H
+
+#include "qtsq_format.h"
+#include "qtsq_types.h"
+#include "qtsq_turbo.h"
+#include "qtsq_triangle_only.h"
+
+int  qtsq_init(qtsq_context_t *ctx);
+void qtsq_free(qtsq_context_t *ctx);
+
+int qtsq_compress(qtsq_context_t *ctx,
+                 const uint8_t *data, size_t size,
+                 qtsq_data_type_t type_hint);
+
+int qtsq_compress_image(qtsq_context_t *ctx,
+                       const uint8_t *pixels,
+                       uint32_t width, uint32_t height,
+                       uint8_t channels);
+
+int qtsq_compress_gravitational(qtsq_context_t *ctx,
+                                const uint8_t *pixels,
+                                uint32_t width, uint32_t height,
+                                uint8_t channels,
+                                size_t source_size);
+
+int qtsq_compress_gravitational_hd(qtsq_context_t *ctx,
+                                    const uint8_t *pixels,
+                                    uint32_t width, uint32_t height,
+                                    uint8_t channels,
+                                    size_t source_size);
+
+/* Mathematical upscaler for lossy inputs (JPEG/WebP).
+ * Uses dense triangle mesh + splats to reconstruct clean edges
+ * from compression artifacts. Output is LARGER but HIGHER QUALITY. */
+int qtsq_compress_gravitational_upscale(qtsq_context_t *ctx,
+                                         const uint8_t *pixels,
+                                         uint32_t width, uint32_t height,
+                                         uint8_t channels,
+                                         size_t source_size);
+
+/* Lossless HD mode — maximum fidelity with 6M vertices.
+ * Output caps: <5MB input → ≤10MB output, ≥5MB input → ≤30MB output. */
+int qtsq_compress_gravitational_lossless(qtsq_context_t *ctx,
+                                          const uint8_t *pixels,
+                                          uint32_t width, uint32_t height,
+                                          uint8_t channels,
+                                          size_t source_size);
+
+/* Pure 2D Gaussian Splat compression (no triangle mesh). */
+int qtsq_compress_splat_compact(qtsq_context_t *ctx,
+                                 const uint8_t *pixels,
+                                 uint32_t width, uint32_t height,
+                                 uint8_t channels, size_t source_size);
+int qtsq_compress_splat_hd(qtsq_context_t *ctx,
+                             const uint8_t *pixels,
+                             uint32_t width, uint32_t height,
+                             uint8_t channels, size_t source_size);
+int qtsq_compress_splat_lossless(qtsq_context_t *ctx,
+                                   const uint8_t *pixels,
+                                   uint32_t width, uint32_t height,
+                                   uint8_t channels, size_t source_size);
+int qtsq_decompress_splat_only(qtsq_context_t *ctx,
+                                 uint8_t **out_data, size_t *out_size);
+
+int qtsq_decompress_gravitational(qtsq_context_t *ctx,
+                                  uint8_t **out_data, size_t *out_size);
+
+int qtsq_optimize_mesh(qtsq_context_t *ctx, const uint8_t *rgb_target, 
+                       uint32_t width, uint32_t height);
+
+/* ══════════════════════════════════════════════════════════════
+ *  Gravitational AI Direct Render API 
+ *  Bypasses redundant Delaunay triangulation during optimizations
+ * ══════════════════════════════════════════════════════════════ */
+typedef struct {
+    float x, y;
+    uint8_t r, g, b;
+} tri_vertex_t;
+
+typedef struct {
+    uint32_t v0, v1, v2;
+} tri_face_t;
+
+int qtsq_render_mesh(const tri_vertex_t *verts, uint32_t nv,
+                     const tri_face_t *faces, uint32_t nf,
+                     uint32_t orig_w, uint32_t orig_h, uint8_t ch,
+                     uint8_t *output);
+
+/* AI Hooks for MeshNet V3 */
+int qtsq_extract_vertices(const qtsq_context_t *ctx, float *flat_verts, uint32_t max_verts);
+int qtsq_apply_vertices(qtsq_context_t *ctx, const float *new_verts, uint32_t num_verts);
+
+/* Mesh Editor: Splat extract/apply — works with splat2d_t arrays directly */
+int qtsq_extract_splats(const qtsq_context_t *ctx, void *out_splats, uint32_t max_splats,
+                         uint32_t *out_width, uint32_t *out_height);
+int qtsq_apply_splats(qtsq_context_t *ctx, const void *splats, uint32_t count,
+                       uint32_t width, uint32_t height);
+
+int qtsq_compress_gravitational_audio(qtsq_context_t *ctx,
+                                       const int16_t *pcm,
+                                       uint32_t total_samples,
+                                       uint8_t channels,
+                                       uint32_t sample_rate);
+
+int qtsq_decompress_gravitational_audio(const qtsq_context_t *ctx,
+                                          uint8_t **out_data, size_t *out_size);
+
+int qtsq_compress_audio(qtsq_context_t *ctx,
+                       const int16_t *samples,
+                       size_t num_samples,
+                       uint32_t sample_rate,
+                       uint8_t channels);
+
+/* Photon Audio — HQ Spatial Gabor atom codec */
+int qtsq_compress_audio_hq(qtsq_context_t *ctx,
+                            const float *samples,     /* 32-bit float */
+                            size_t num_samples,
+                            uint32_t sample_rate,
+                            uint8_t channels);
+
+int qtsq_decompress_audio_hq(const qtsq_context_t *ctx,
+                              float **out_pcm,            /* outputs 32-bit float interleaved */
+                              size_t *out_total_samples,
+                              photon_atom_t **out_atoms,  /* outputs spatial atoms array */
+                              size_t *out_atom_count);
+
+int qtsq_compress_text(qtsq_context_t *ctx,
+                      const char *text, size_t length);
+
+int qtsq_compress_csv(qtsq_context_t *ctx,
+                     const char *csv_data, size_t length);
+
+int qtsq_compress_json(qtsq_context_t *ctx,
+                       const char *json, size_t length);
+
+int qtsq_compress_signal(qtsq_context_t *ctx,
+                        const double *signal, size_t num_samples);
+
+typedef struct qtsq_video_encoder qtsq_video_encoder_t;
+
+/* Initialize a video encoder session */
+qtsq_video_encoder_t* qtsq_video_encoder_create(qtsq_context_t *ctx,
+                                                uint32_t width, uint32_t height,
+                                                uint8_t channels, uint32_t fps,
+                                                int strategy_flags,
+                                                size_t target_payload_per_frame);
+
+/* Append a single uncompressed frame to the video sequence. */
+int qtsq_video_encoder_add_frame(qtsq_video_encoder_t *enc, const uint8_t *pixels);
+
+/* Finish encoding and flush all buffers to context. */
+int qtsq_video_encoder_finish(qtsq_video_encoder_t *enc);
+
+/* Get the underlying context */
+qtsq_context_t* qtsq_video_encoder_get_context(qtsq_video_encoder_t *enc);
+
+/* Cleanup encoder resources */
+void qtsq_video_encoder_free(qtsq_video_encoder_t *enc);
+
+typedef struct qtsq_video_decoder qtsq_video_decoder_t;
+
+/* Open a video for decoding */
+qtsq_video_decoder_t* qtsq_video_decoder_open(const qtsq_context_t *ctx);
+
+/* Decode a specific frame. Returns malloc'd RGB buffer. */
+int qtsq_video_decoder_get_frame(qtsq_video_decoder_t *dec, uint32_t frame_index, uint8_t **out_pixels, uint32_t *width, uint32_t *height);
+
+/* Get total number of frames */
+uint32_t qtsq_video_decoder_get_frame_count(qtsq_video_decoder_t *dec);
+
+/* Get the underlying context */
+const qtsq_context_t* qtsq_video_decoder_get_context(qtsq_video_decoder_t *dec);
+
+/* Cleanup decoder resources */
+void qtsq_video_decoder_free(qtsq_video_decoder_t *dec);
+
+int qtsq_compress_raw(qtsq_context_t *ctx,
+                     const uint8_t *data, size_t size, uint64_t seed);
+
+int qtsq_write(const qtsq_context_t *ctx, const char *filename);
+int qtsq_read(qtsq_context_t *ctx, const char *filename);
+
+int qtsq_decompress(qtsq_context_t *ctx,
+                   uint8_t **out_data, size_t *out_size);
+
+int qtsq_decompress_redshift(const qtsq_context_t *ctx,
+                            double redshift,
+                            uint8_t **out_data, size_t *out_size);
+
+int qtsq_radiate(const qtsq_context_t *ctx,
+                uint64_t offset, uint32_t size,
+                uint8_t **out_data);
+int qtsq_radiate_time(const qtsq_context_t *ctx,
+                     double start_sec, double duration_sec,
+                     int16_t **out_samples, size_t *out_count);
+int qtsq_radiate_region(const qtsq_context_t *ctx,
+                       uint32_t x, uint32_t y, uint32_t w, uint32_t h,
+                       uint8_t **out_pixels);
+int qtsq_radiate_frame(const qtsq_context_t *ctx,
+                      uint32_t frame_index, uint8_t **out_pixels);
+
+int qtsq_add_wormhole(qtsq_context_t *ctx,
+                     const char *target_path,
+                     uint32_t target_offset, uint32_t target_size);
+int qtsq_resolve_wormholes(qtsq_context_t *ctx);
+
+int qtsq_encrypt(qtsq_context_t *ctx, const char *password);
+int qtsq_decrypt(qtsq_context_t *ctx, const char *password);
+int qtsq_is_encrypted(const qtsq_context_t *ctx);
+
+int qtsq_emit_wave(const qtsq_context_t *old_ctx,
+                  const qtsq_context_t *new_ctx,
+                  const char *wave_filename);
+int qtsq_apply_wave(qtsq_context_t *ctx,
+                   const char *wave_filename);
+
+int qtsq_add_recovery(qtsq_context_t *ctx);
+int qtsq_health_check(const qtsq_context_t *ctx);
+int qtsq_recover(qtsq_context_t *ctx);
+
+void            qtsq_print_info(const qtsq_context_t *ctx);
+double          qtsq_compression_ratio(const qtsq_context_t *ctx);
+const char*     qtsq_error_string(int error_code);
+
+/* ══════ Utility ══════ */
+void qtsq_sha256(const uint8_t *data, size_t size, uint8_t *hash);
+double qtsq_entropy(const uint8_t *data, size_t size);
+uint32_t qtsq_crc32(const uint8_t *data, size_t size);
+
+/* ══════ Engine-specific decompression ══════ */
+int qtsq_decompress_singularity(const qtsq_context_t *ctx,
+                                uint8_t **out_data, size_t *out_size);
+int qtsq_decompress_horizon(const qtsq_context_t *ctx,
+                            uint8_t **out_data, size_t *out_size);
+int qtsq_decompress_lensing(const qtsq_context_t *ctx,
+                            uint8_t **out_data, size_t *out_size);
+int qtsq_decompress_accretion(const qtsq_context_t *ctx,
+                              uint8_t **out_data, size_t *out_size);
+
+/* ══════ Container (Multi-Data) ══════ */
+int qtsq_container_create(qtsq_context_t *ctx);
+int qtsq_container_add_file(qtsq_context_t *ctx, const char *path,
+                             const char *stream_name);
+int qtsq_container_add_stream(qtsq_context_t *ctx,
+                               const qtsq_context_t *sub_ctx,
+                               const char *stream_name);
+int qtsq_container_add_folder(qtsq_context_t *ctx, const char *folder_path);
+int qtsq_container_pack(qtsq_context_t *ctx);
+int qtsq_container_get_count(const qtsq_context_t *ctx, uint32_t *out_count);
+int qtsq_container_get_stream(const qtsq_context_t *ctx, uint32_t index,
+                               qtsq_context_t *out_ctx,
+                               char *name_buf, size_t name_buf_size);
+
+#endif /* QTSQ_H */

qtsq-1.0.0/include/qtsq_format.h

@@ -0,0 +1,263 @@
+/*
+ * Quantum Tensor Sequence — File Format Structures & Constants
+ * File Extension: .qtsq (Quantum Tensor Sequence)
+ * 
+ * Author: Haruhito
+ * License: MIT
+ */
+
+#ifndef QTSQ_FORMAT_H
+#define QTSQ_FORMAT_H
+
+#include <stdint.h>
+#include <stddef.h>
+/* Magic bytes: "QTS\x01" */
+#define QTSQ_MAGIC_0 'Q'
+#define QTSQ_MAGIC_1 'T'
+#define QTSQ_MAGIC_2 'S'
+#define QTSQ_MAGIC_3 '\x01'
+#define QTSQ_VERSION_1  1
+#define QTSQ_VERSION_2  2
+#define QTSQ_VERSION    2     /* current version */
+
+/* gravitational wave diff (.qtsw): "QTW\x01" */
+#define QTW_MAGIC_0 'Q'
+#define QTW_MAGIC_1 'T'
+#define QTW_MAGIC_2 'W'
+#define QTW_MAGIC_3 '\x01'
+
+/* Chandrasekhara limit*/
+#define QTSQ_CHANDRASEKHAR_LIMIT 4096
+
+/* Compression Strategy*/
+typedef enum {
+    QTSQ_STRATEGY_NONE        = 0x00,
+    QTSQ_STRATEGY_PROCEDURAL  = 0x01,
+    QTSQ_STRATEGY_FRACTAL     = 0x02,
+    QTSQ_STRATEGY_FOURIER     = 0x03,
+    QTSQ_STRATEGY_DELTA_SEED  = 0x04,
+    QTSQ_STRATEGY_DICTIONARY  = 0x05,
+    QTSQ_STRATEGY_TEMPORAL    = 0x06,
+    QTSQ_STRATEGY_TRIANGLE    = 0x07,
+    QTSQ_STRATEGY_PHOTON      = 0x08,  /* HQ Gabor atom audio (Photon Audio) */
+    QTSQ_STRATEGY_SPLAT       = 0x09,  /* Pure 2D Gaussian Splat image (no triangles) */
+    QTSQ_STRATEGY_LAYERED     = 0xFF,
+} qtsq_strategy_t;
+
+/* data type*/
+typedef enum {
+    QTSQ_TYPE_RAW          = 0x00,
+    QTSQ_TYPE_IMAGE_GRAY   = 0x10,
+    QTSQ_TYPE_IMAGE_RGB    = 0x11,
+    QTSQ_TYPE_IMAGE_RGBA   = 0x12,
+    QTSQ_TYPE_AUDIO_MONO   = 0x20,
+    QTSQ_TYPE_AUDIO_STEREO = 0x21,
+    QTSQ_TYPE_AUDIO_MULTI  = 0x22,
+    QTSQ_TYPE_VIDEO_FRAMES = 0x30,
+    QTSQ_TYPE_TEXT_ASCII   = 0x40,
+    QTSQ_TYPE_TEXT_UTF8    = 0x41,
+    QTSQ_TYPE_TABLE_INT    = 0x50,
+    QTSQ_TYPE_TABLE_FLOAT  = 0x51,
+    QTSQ_TYPE_JSON         = 0x52,
+    QTSQ_TYPE_CSV          = 0x53,
+    QTSQ_TYPE_SIGNAL_1D    = 0x60,
+    QTSQ_TYPE_SIGNAL_2D    = 0x61,
+    QTSQ_TYPE_CONTAINER    = 0xF0,
+} qtsq_data_type_t;
+
+/* Flags */
+#define QTSQ_FLAG_LAZY_DECOMP   0x0001
+#define QTSQ_FLAG_LOSSY         0x0002
+#define QTSQ_FLAG_CHECKSUMMED   0x0004
+#define QTSQ_FLAG_SEEKABLE      0x0008
+#define QTSQ_FLAG_ENCRYPTED     0x0010
+#define QTSQ_FLAG_MULTI_STREAM  0x0020
+#define QTSQ_FLAG_AUTO_DETECTED 0x0040
+#define QTSQ_FLAG_HAS_WORMHOLES 0x0080
+#define QTSQ_FLAG_HAS_ECC       0x0100
+#define QTSQ_FLAG_REDSHIFTABLE  0x0200
+#define QTSQ_FLAG_HD            0x0400  /* High-quality triangle mesh (QTSQ HD) */
+#define QTSQ_FLAG_3D            0x0800  /* 3D Depth encoded (Parallax/Volumetric) */
+#define QTSQ_FLAG_UPSCALE       0x1000  /* Upscale mathematical enhancement for lossy frames */
+#define QTSQ_FLAG_SPATIAL       0x2000  /* Spatial audio via atoms or object positioning */
+#define QTSQ_FLAG_ZLIB          0x4000  /* Singularity payload is ZLib-compressed */
+#define QTSQ_FLAG_SPLAT_ONLY    0x8000  /* Pure 2D Gaussian Splat image (no triangles) */
+
+/* error codes */
+#define QTSQ_OK                  0
+#define QTSQ_ERR_NULL           -1
+#define QTSQ_ERR_ALLOC          -2
+#define QTSQ_ERR_IO             -3
+#define QTSQ_ERR_FORMAT         -4
+#define QTSQ_ERR_CHECKSUM       -5
+#define QTSQ_ERR_STRATEGY       -6
+#define QTSQ_ERR_TYPE           -7
+#define QTSQ_ERR_ENCRYPTED      -8
+#define QTSQ_ERR_DECRYPT        -9
+#define QTSQ_ERR_WORMHOLE       -10
+#define QTSQ_ERR_WORMHOLE_HASH  -11
+#define QTSQ_ERR_CORRUPT        -12
+#define QTSQ_ERR_RECOVERY_FAIL  -13
+#define QTSQ_ERR_TOO_SMALL      -14
+
+/* file header v2 — 96 bytes packed
+ * v1 was 80 bytes with uint32_t sizes (4 GB limit)
+ * v2 uses uint64_t sizes (18.4 EB limit) */
+typedef struct {
+    uint8_t      magic[4];
+    uint8_t      version;
+    uint8_t      strategy;
+    uint16_t     flags;
+    uint8_t      data_type;
+    uint8_t      num_channels;
+    uint16_t     sample_depth;
+    uint32_t     reserved;
+    uint64_t     original_size;
+    uint64_t     timestamp;
+    uint8_t      checksum[32];
+    uint64_t     horizon_size;       /* v2: was uint32_t */
+    uint64_t     accretion_size;     /* v2: was uint32_t */
+    uint64_t     singularity_size;   /* v2: was uint32_t */
+    uint64_t     radiation_size;     /* v2: was uint32_t */
+} __attribute__((packed)) qtsq_header_t;
+
+_Static_assert(sizeof(qtsq_header_t) == 96, "header must be 96 bytes");
+
+/* v1 header for backward compatibility (reading old files) */
+typedef struct {
+    uint8_t      magic[4];
+    uint8_t      version;
+    uint8_t      strategy;
+    uint16_t     flags;
+    uint8_t      data_type;
+    uint8_t      num_channels;
+    uint16_t     sample_depth;
+    uint32_t     reserved;
+    uint64_t     original_size;
+    uint64_t     timestamp;
+    uint8_t      checksum[32];
+    uint32_t     horizon_size;
+    uint32_t     accretion_size;
+    uint32_t     singularity_size;
+    uint32_t     radiation_size;
+} __attribute__((packed)) qtsq_header_v1_t;
+
+_Static_assert(sizeof(qtsq_header_v1_t) == 80, "v1 header must be 80 bytes");
+
+/* schema */
+typedef struct {
+    char         name[64];
+    uint8_t      data_type;
+    uint32_t     dimensions[8];
+    uint8_t      num_dims;
+    uint32_t     sample_rate;
+    uint32_t     frame_rate;
+    char         encoding[64];
+} qtsq_schema_t;
+
+/* transform */
+typedef struct {
+    uint8_t      type;
+    uint32_t     param_size;
+    void        *params;
+} qtsq_transform_t;
+
+/* Photon Audio Spatial Atom */
+typedef struct {
+    float freq_hz;
+    float magnitude;
+    float phase;
+    float x;        /* Spatial X (pan): -1 (left) to 1 (right) */
+    float y;        /* Spatial Y (height): -1 (low) to 1 (high) */
+    float z;        /* Spatial Z (depth): 0 (far) to 1 (near) */
+    float spread;   /* Spatial Spread (width): 0 (point) to 1 (diffuse) */
+    uint32_t frame_index;
+} photon_atom_t;
+
+/* transform */
+typedef struct {
+    uint64_t     logical_offset;
+    uint32_t     chunk_size;
+    uint32_t     singularity_offset;
+    uint8_t      priority;
+} __attribute__((packed)) qtsq_index_t;
+
+/* wormhole */
+#define QTSQ_WORMHOLE_LOCAL      0x01
+#define QTSQ_WORMHOLE_LAN        0x02
+#define QTSQ_WORMHOLE_CLOUD      0x03
+#define QTSQ_WORMHOLE_MARKER     0xEE
+
+typedef struct {
+    uint8_t      type;
+    uint8_t      target_hash[32];
+    char         target_path[256];
+    uint32_t     target_offset;
+    uint32_t     target_size;
+} qtsq_wormhole_t;
+
+/* censorship */
+typedef struct {
+    uint8_t       iv[16];
+    uint8_t       salt[16];
+    uint8_t       auth_tag[16];
+    uint32_t      iterations;
+} qtsq_censorship_t;
+
+/* recovery */
+typedef struct {
+    uint32_t       num_chunks;
+    uint32_t       *chunk_checksums;
+    uint8_t        *reed_solomon_parity;
+    uint32_t       parity_size;
+} qtsq_recovery_t;
+
+/* wave header (.qtsw) */
+typedef struct {
+    uint8_t        magic[4];
+    uint8_t        source_hash[32];
+    uint8_t        result_hash[32];
+    uint64_t       timestamp;
+    uint32_t       num_patches;
+} __attribute__((packed)) qtsq_wave_header_t;
+
+typedef struct {
+    uint32_t       offset;
+    uint32_t       old_size;
+    uint32_t       new_size;
+    uint8_t       *new_data;
+} qtsq_patch_t;
+
+/* main context */
+typedef struct {
+    qtsq_header_t       header;
+    qtsq_schema_t       schema;
+    qtsq_transform_t   *transforms;
+    uint32_t           num_transforms;
+    uint8_t           *singularity;
+    uint64_t           singularity_size;
+    qtsq_index_t       *radiation_index;
+    uint32_t           num_radiation;
+    qtsq_wormhole_t    *wormholes;
+    uint32_t           num_wormholes;
+    qtsq_censorship_t   censorship;
+    int                is_encrypted;
+    qtsq_recovery_t     recovery;
+    int                has_recovery;
+} qtsq_context_t;
+
+/* ── Container (Multi-Stream) ── */
+#define QTSQ_MAX_STREAMS 256
+
+typedef struct {
+    uint8_t   data_type;       /* QTSQ_TYPE_* for this stream */
+    uint8_t   strategy;        /* QTSQ_STRATEGY_* used to compress */
+    uint16_t  flags;           /* per-stream flags (ZLIB, LOSSY, etc.) */
+    uint32_t  data_offset;     /* offset from start of stream data block */
+    uint32_t  data_size;       /* compressed size in bytes */
+    uint32_t  original_size;   /* original uncompressed size */
+} __attribute__((packed)) qtsq_stream_entry_t;
+
+_Static_assert(sizeof(qtsq_stream_entry_t) == 16, "stream entry must be 16 bytes");
+
+#endif