Metadata-Version: 2.4
Name: staqtapp-tds
Version: 3.11.0
Summary: Production Temporal Directory System storage engine and operations layer
Author: Staqtapp-TDS contributors
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/staqtapp-tds/
Keywords: storage,virtual-filesystem,telemetry,database,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: fast
Requires-Dist: numba>=0.58; extra == "fast"
Provides-Extra: gui
Requires-Dist: PySide6<7,>=6.8; extra == "gui"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Provides-Extra: native
Dynamic: license-file

# Staqtapp-TDS v3.11.0

> **Staqtapp-TDS 3.11.0 is the final public version of TDS.**
>
> **Platform: Linux.**
>
> This public distribution does not include Eaglegate activation or full Eaglegate integration.
> The Olum multi-agentic registry system and workflow are not included.
>
> Eaglegate target and shadow qualification utilities remain non-authoritative
> and cannot activate production serving.

Staqtapp-TDS is a directory-first storage, persistence, evidence, and operations
engine for Python systems. It stores typed values in an indexed hierarchy,
persists exact bytes to rooted `.tds` files, and returns stable non-halting
results for ordinary operations.

[Programmer Core API Guide (PDF; complete source ZIP)](tds_api_docs/Staqtapp_TDS_Programmer_Core_API_Guide.pdf)

| Package status | Value |
| --- | --- |
| Version | `3.11.0` |
| Python | `3.10+` |
| Platform | Linux |
| Base dependency | NumPy `>=1.23` |
| License | MIT |

## Available features

| Area | Included |
| --- | --- |
| Directory storage | Hierarchical directories; exact indexed lookup; binary, text, JSON, NumPy, and restricted-pickle values; schemas; bounded batch reads and writes; locks; and stalk chains. |
| Result-first API | `TDSResult` responses with stable codes, values, messages, and metadata for storage, variable, persistence, and capability operations. |
| Rooted `.tds` persistence | Atomic snapshots, exact encoded-byte retention, SHA-256 roots, required integrity sidecars for new v2 files, lazy mounts, immutable reader epochs, pin/reload safety, and integrity audits. |
| Versioned storage | Self-contained `.tds` v3 nodes, dirty-node Merkle commits, frozen indexes, `NONE` and `ZLIB` blocks, leased range reads, read-only NumPy access, and cross-process publication locks. |
| Generations and CAS | SHA-256 sharded content-addressed storage, immutable publications, head compare-and-swap, reader pins, recovery, rollback, retirement, and composite CSV objects. |
| CSV evidence | Original-byte preservation, dialect fingerprints, row offsets and anchors, scans, validation, artifact transactions, storage binding, Interpole evidence, and explicit Semantic IR review records. |
| Trace and paths | Deterministic trace ranking, packed waypoint/CSR graphs, provenance records, bounded path planning, and replayable receipts. |
| Driver platform | TDDL validation, deterministic bytecode, bounded Driver VM execution, Runtime Manager evidence, Foundry proposal/review flows, regression harnesses, audit exports, and the optional PySide6 Stargate cockpit. |
| Operations | Cached telemetry, bounded diagnostics, pressure/recovery reporting, local Stargate Browser console, CLI verification, and optional workspace snapshots. |
| Acceleration | Optional Numba paths and opt-in C index/CSV kernels with deterministic Python fallbacks. |

## Measured performance

### PyPI 3.8.3 compared with 3.11.0

| Workload | 3.8.3 median | 3.11.0 median | Improvement |
| --- | ---: | ---: | ---: |
| Exact hit, telemetry OFF | 9.125 µs/read | 1.253 µs/read | **7.28×** |
| Exact hit, telemetry LIGHT | 13.824 µs/read | 3.405 µs/read | **4.06×** |
| Exact miss, telemetry OFF | 2.894 µs/read | 1.347 µs/read | **2.15×** |
| Exact miss, telemetry LIGHT | 7.747 µs/read | 3.662 µs/read | **2.12×** |
| Probability-ranked scan, 2,047 entries | 9.632 µs/read | 1.937 µs/read | **4.97×** |
| Probability-ranked scan, 2,049 entries | 1.934 ms/read | 1.912 µs/read | **1,011.31×** |
| Probability-ranked scan, 4,096 entries | 1.915 ms/read | 2.271 µs/read | **843.34×** |
| Portable slot packing, 8,192 records | 15.038 µs/record | 0.505 µs/record | **29.80×** |

The 843–1,011× results are the removal of the old post-2,048-entry registry
scaling and correctness cliff, not general TDS throughput multipliers. Version
3.8.3 omitted live keys in those fixtures; 3.11.0 retained exact closure.

### Additional 3.11.0 medians

| Workload | Result |
| --- | ---: |
| Rooted v2 flush, 64 MiB uncompressed | 210.645 ms; **303.8 MiB/s**; 1,070,551 B traced Python peak |
| Telemetry `record_read` | **1,441,534 calls/s** |
| Canonical JSON dump / fast load | 2.744 / 1.956 µs per operation |
| CSV scan plus row anchors, 20,001 rows | **85.620 ms** |
| CSV import, same fixture | 67.265 ms |
| CSV row-offset packing | 3.492 ms; 320,463 B traced Python peak |
| Eight cached root reads, 4,096 payloads | **0.004817 ms** |
| Direct / managed Driver VM, 5,000 records | 93.983 / 204.914 ms |
| Trace graph / packed-byte admission, 1,600 rows | 4.464 / 6.186 ms |

Benchmark scope:

- Linux 6.18.35 x86-64, one AMD EPYC 9V74 core, CPython 3.12.13, NumPy 2.3.5.
- Numba disabled, CPU affinity 4, `PYTHONHASHSEED=0`, two warmups, nine timed repetitions.
- Paired results were accepted only after values, telemetry, packed bytes, round trips, and SHA-256 roots matched.
- Results are workload-specific local measurements. `tracemalloc` is not process RSS.

Benchmark harnesses are included in the complete source ZIP.

## Install

```bash
# Base package
python -m pip install "staqtapp-tds==3.11.0"

# Optional Numba acceleration
python -m pip install "staqtapp-tds[fast]==3.11.0"

# Optional PySide6 cockpit
python -m pip install "staqtapp-tds[gui]==3.11.0"
```

The PyPI wheel uses deterministic Python backends. Optional native builds are
Linux-only and require an explicit source build:

```bash
STAQTAPP_TDS_BUILD_NATIVE=1 \
  python -m pip install --no-binary staqtapp-tds "staqtapp-tds==3.11.0"
```

## Quick start

```python
from pathlib import Path

from staqtapp_tds import TDSFileSystem, TDSPersistence, TDSReader

fs = TDSFileSystem("agent_state")
runtime = fs.makedirs("/models/runtime")

assert runtime.write_text("system_prompt", "Be precise.").ok
assert runtime.write_json("settings", {"temperature": 0.2}).ok
assert runtime.write_result("step_count", 7).ok

result = runtime.read_result("settings")
assert result.ok and result.value["temperature"] == 0.2

store = TDSPersistence(Path("./tds_store"))
store.flush(fs, parallel_nodes=False)

path = Path("./tds_store/agent_state__models__runtime.tds")
assert store.load_node(path).read_value("step_count") == 7

with TDSReader(path) as reader:
    assert reader.audit_integrity()["ok"]
```

## Commands

| Command | Purpose |
| --- | --- |
| `staqtapp-tds` | Start the local telemetry Browser on `127.0.0.1:8765`. |
| `staqtapp-tds-admin status` | Show installed runtime status. |
| `staqtapp-tds-admin verify --sample` | Run packaged health and sample-data checks. |
| `staqtapp-tds-generation-audit` | Audit immutable-generation publication, pins, rollback, and recovery. |
| `staqtapp-tds-driver-foundry` | Open the optional PySide6 cockpit. |

## Format and authority boundaries

| Boundary | Status |
| --- | --- |
| Package and formats | Package `3.11.0`, `.tds` v2, additive `.tds` v3, Generation v1, CSV generation v1, and `tds-csv-composite-v2` are separate identities. |
| Existing data | Version 3.11.0 retains existing `.tds` v2 bytes and layout. |
| Encryption | At-rest encryption is not implemented; `DirFlags.ENCRYPTED` fails closed. `XorCryptoProvider` is not secure encryption. |
| Input trust | Treat `.tds` and pickle-compatible inputs as trusted until application-specific resource and trust controls are applied. |
| Semantic authority | TDS records caller declarations and authorized review transitions; it does not infer or commit semantic truth. |
| Driver authority | Driver Foundry and Studio do not sign or activate drivers. |
| Eaglegate | Activation and full integration are not included. |
| Olum | The multi-agentic registry system and workflow are not included. |

## License

MIT. See `LICENSE`.
