privpy 0.1.0__tar.gz

privpy-0.1.0/DESIGN.md

@@ -0,0 +1,135 @@
+# privpy — final API draft
+
+A region owns private data. Protected functions compute on it. Explicit export authorizes disclosure to ordinary Python or an exact local file.
+
+This is an API and execution design. It does not, by itself, establish hardware memory isolation.
+
+## Public API
+
+```python
+with PrivateRegion() as region:
+    private_result = protected_function(public_input)
+    public_result = region.export(private_result)
+    region.export(private_result, to=Path("/absolute/output.csv"), transform=as_csv)
+```
+
+```python
+@private_function
+def protected_function(...):
+    ...
+
+region.export(value, *, to=None, transform=None)
+```
+
+There is no named policy, general-purpose load method, manual run method, format argument, or destination alias.
+
+## Region
+
+The context manager owns private objects and their lifetime and establishes the active region. The surrounding Python block executes normally. Decorated functions execute in the protected runtime.
+
+Every private reference belongs to exactly one region. References from another region are rejected. Closing the region, including on exception, invalidates all its references. Exported copies and files survive independently.
+
+Ordinary Python arguments can be copied into computations. Their original copies remain public. Private source readers retrieve and parse their inputs inside the runtime; their source must itself be protected if confidentiality before retrieval matters.
+
+## Protected functions
+
+Decorated functions accept supported public arguments and private references. Their implementation is compiled or interpreted by the protected runtime, never executed as an ordinary Python callback with plaintext inputs.
+
+Calls use ordinary syntax and automatically dispatch to the active region. Calls between protected functions remain inside. A call without an active region fails.
+
+All intermediate and returned objects remain private: scalars, strings, collections, arrays and supported dataframes. Comparisons, lengths, schemas and aggregates receive no automatic exemption. Branches and loops can use private conditions inside the runtime. Unsupported operations fail; there is no plaintext fallback to host Python.
+
+Outside the runtime, results are opaque references. They can be passed to protected functions or exported. They cannot expose contents through conversion, iteration, indexing, truth testing, attribute access or serialization. Their representation is a fixed placeholder.
+
+## Export
+
+`export` is the application's deliberate authorization to disclose. It checks mechanics, not whether the data is semantically safe to reveal. The application developer is trusted to choose outputs. Deliberately exporting an original secret is permitted.
+
+Arguments:
+
+| Argument | Meaning |
+| --- | --- |
+| `value` | A private reference owned by the active region |
+| `transform` | Optional protected function accepting one value and returning a private result |
+| `to=None` | Return an independent supported Python value |
+| `to=Path(...)` | Write bytes directly to that absolute local file; return `None` |
+
+The optional transform runs inside the region. Its result remains private until export. With no transform, the value must already be suitable for its destination. File destinations require bytes; there is no inferred serialization, encoding or encryption. Existing files are not overwritten. Aliases, relative paths, URLs, file objects and callbacks are not supported as destinations in the initial API.
+
+```python
+region.export(value, to=path, transform=as_csv)
+```
+
+is equivalent to:
+
+```python
+encoded = as_csv(value)
+region.export(encoded, to=path)
+```
+
+Saved plaintext is disclosed. Confidential persistence uses a protected transform that serializes and encrypts to bytes, plus a protected reader that reverses it later. Key management and a secure encryption integration must exist before that feature can be claimed. File extensions never select these behaviors.
+
+## Target dataframe example
+
+The following illustrates the eventual supported-integration API, not unrestricted pandas or SDK compatibility:
+
+```python
+@private_function
+def read_orders():
+    token = secrets.get("payments-token")
+    records = payments.fetch_orders(token)
+    return DataFrame(records)
+
+@private_function
+def summarize(orders):
+    paid = orders[orders["status"] == "paid"]
+    return paid.groupby("country", as_index=False)["amount"].sum()
+
+@private_function
+def as_csv(frame):
+    return frame.to_csv(index=False).encode("utf-8")
+
+with PrivateRegion() as region:
+    totals = summarize(read_orders())
+    region.export(totals, to=Path("/reports/monthly.csv"), transform=as_csv)
+```
+
+Source retrieval, credential handling and library operations require supported runtime integrations. Neither a decorator nor moving a pointer makes an arbitrary Python SDK safe to execute on private data.
+
+## Execution sketch
+
+```mermaid
+flowchart TD
+    H[Ordinary Python: public inputs and private references]
+    R[Native runtime: region-owned objects and compiled functions]
+    S[Supported source readers]
+    T[Optional protected transform]
+    E[Explicit export: validate ownership and destination]
+    F[Absolute local file: exact bytes]
+    H -->|Protected function call| R
+    S --> R
+    R -->|Opaque reference| H
+    R --> T
+    T --> E
+    R -->|No transform| E
+    E -->|Independent ordinary value| H
+    E -->|Direct native write| F
+```
+
+## Initial implementation boundary
+
+The first module uses a native C++ runtime with a restricted Python-syntax interpreter. Python compiles function source into a data-only representation. Private function evaluation, local variables, source parsing, results and file-output bytes live in native storage. The Python interface receives handles until explicit export.
+
+Initial supported data: bounded integers, finite floats, booleans, null, UTF-8 strings, bytes, lists and string-keyed records. Initial computations include assignments, expressions, comparisons, branches, loops and calls between protected functions. File readers and JSON/CSV byte encoders provide a concrete end-to-end vertical slice.
+
+Full dataframe engines, real secrets-manager SDKs, HTTP clients, encryption, arbitrary Python modules, asynchronous functions and custom Python classes are future integrations, not implicit compatibility promises.
+
+The prototype targets accidental disclosure through supported language operations. It does not protect against hostile code with unrestricted native-memory access, a debugger, a compromised runtime, process dumps, timing/termination/error side channels or an application developer deliberately exporting secrets. Native resource release is not a guarantee of complete zeroization of allocator memory, registers or operating-system copies. Normal Python handles do not hold the plaintext object graph.
+
+A production backend would need security review, memory-management hardening, further resource limits and a defined threat model. A strong enclave or process-isolation backend can use the same public API, but is not implemented by this prototype.
+
+## Background
+
+- [Python context-manager semantics](https://docs.python.org/3/reference/compound_stmts.html#the-with-statement)
+- [Native memory access through Python](https://docs.python.org/3/library/ctypes.html)
+- [Information flow, including exceptional control flow](https://www.cs.cornell.edu/jif/doc/jif-3.3.0/label_checking.html)

privpy-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md DESIGN.md TESTING.md VALIDATION.md RELEASING.md requirements-test.txt
+recursive-include src/privpy/native *.cpp
+recursive-include tests *.py
+recursive-include examples *.py *.json
+recursive-include scripts *.py

privpy-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: privpy
+Version: 0.1.0
+Summary: Experimental native private computation regions for Python
+Home-page: https://github.com/technoyoda/privpy
+Project-URL: Source, https://github.com/technoyoda/privpy
+Project-URL: Issues, https://github.com/technoyoda/privpy/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: C++
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: hypothesis<7,>=6.100; extra == "test"
+Requires-Dist: coverage<8,>=7; extra == "test"
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# privpy
+
+**Private computations, native-owned values, explicit export.**
+
+Experimental same-process Python module. The runtime is C++17; the entire test suite is Python, using `unittest` and Hypothesis.
+
+## Install from PyPI
+
+Install the latest release into your Python environment:
+
+```sh
+python -m pip install privpy
+```
+
+To upgrade an existing installation:
+
+```sh
+python -m pip install --upgrade privpy
+```
+
+Prebuilt wheels include the native runtime for CPython 3.9–3.14 on macOS 14+ and glibc 2.28+ Linux, on Intel and ARM. These wheels do not require a local C++ compiler. If pip selects a source archive instead, the source-build requirements below apply. Windows and PyPy are not supported yet.
+
+## Example
+
+Save protected functions in a Python file so their source can be inspected.
+
+```python
+from pathlib import Path
+from privpy import PrivateRegion, private_function
+from privpy.intrinsics import read_json, json_bytes
+
+@private_function
+def read_records(path):
+    return read_json(path)
+
+@private_function
+def total_paid(records):
+    total = 0
+    for row in records:
+        if row["status"] == "paid":
+            total += row["amount"]
+    return total
+
+@private_function
+def encode_total(total):
+    return json_bytes({"total": total})
+
+with PrivateRegion() as region:
+    records = read_records("/absolute/orders.json")
+    total = total_paid(records)
+    print(total)  # <PrivateRef>
+
+    # Deliberate disclosure: the caller chooses what gets exported.
+    public_total = region.export(total)
+    region.export(total, to=Path("/absolute/new-report.json"), transform=encode_total)
+```
+
+There is no `policy`, `region.run`, universal `load`, `format`, or destination alias. The context manager establishes the active region. Decorated functions execute in a native interpreter; their original Python bodies are never invoked with private inputs.
+
+## Build and run
+
+Requires Python 3.9+ and macOS or Linux. Building from source needs a C++17 compiler with floating-point `std::to_chars` support. Release wheels target macOS 14+ and glibc 2.28+ Linux. The pinned development environment uses Python 3.12.
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements-test.txt
+PYTHONPATH=src python -m privpy.build
+PYTHONPATH=src python examples/orders.py
+PYTHONPATH=src python examples/orders.py --output /absolute/new-report.csv
+```
+
+If a virtual environment already exists, activate and reuse it.
+
+`python -m pip install .` builds the native library during installation. There are no Python runtime dependencies. Source-checkout use only needs `PYTHONPATH=src` and the explicit build command.
+
+## Implemented contract
+
+- A region owns native values. Outside Python receives a `PrivateRef` containing an owner reference and integer handle.
+- Public arguments are copied in; their original Python copies remain public.
+- Native source readers retrieve regular files without routing plaintext through Python. They do not make a public source file secret.
+- Private calls remain native. Outside callbacks, dynamic imports and arbitrary Python libraries are rejected.
+- Every result stays private, including booleans, lengths and aggregates.
+- Export is deliberate disclosure. It checks mechanics, not whether the contents are semantically safe to reveal.
+- `export(value)` returns an independent supported Python value.
+- `export(value, to=Path(...))` requires bytes and writes them directly from native storage.
+- An optional decorated transform runs before export. There is no implicit formatting, encoding or encryption.
+- Destinations must be absolute. Existing files and symlinks are never replaced. Symlink components are rejected; use an already-canonical directory path. Complete output is published atomically from a mode-0600 temporary file in the same directory.
+- Closing a region invalidates all its references. Exported values and files survive.
+
+## Supported subset
+
+Data: null, booleans, signed 64-bit integers, finite binary64 floats, Unicode strings, bytes, lists and string-keyed dictionaries.
+
+Syntax: local assignment, single-level subscript updates, unpacking, arithmetic, comparisons, boolean expressions, indexing, conditional expressions, `if`, `for`, `while`, loop `else`, `break`, `continue`, return, one-generator list comprehensions and calls between private functions.
+
+Builtins: `len`, `bool`, scalar `str`, `abs`, `sum`, `min`, `max`, `range`.
+
+Methods: dictionary `get`, `keys`, `values`, `items`; string UTF-8 `encode`.
+
+Source and encoding operations:
+
+```python
+from privpy.intrinsics import (
+    read_json, read_text, read_bytes, json_bytes, csv_bytes, utf8_bytes,
+)
+```
+
+Prototype semantics:
+
+- CSV uses minimal quoting with comma separators and CRLF record endings. NUL characters are preserved and do not by themselves force quoting.
+- Collection updates use value semantics; updating one binding does not mutate another reference.
+- Dictionaries iterate in sorted key order, and their view methods return lists.
+- Integers are bounded. Overflow raises a sanitized execution error.
+- Floor division and modulo currently accept integers only.
+- Mixed integer/float comparisons reject integers outside binary64's exact integer range.
+- Functions require inspectable source. Closures, defaults, variadic/keyword-only parameters and keyword arguments inside protected calls are unsupported. Named arguments at the public call boundary work.
+- Limits bound input/value sizes, collections, native nesting, recursion and interpreter steps. `PrivateRegion(max_steps=...)` adjusts a per-call resource limit.
+- Unsupported syntax fails explicitly, even in unreachable branches.
+
+Full dataframe engines, secrets-manager SDKs, network clients, encryption, arbitrary third-party libraries, custom classes and asynchronous private functions are not implemented. The example demonstrates record processing without claiming pandas compatibility. [DESIGN.md](DESIGN.md) contains the target API and architecture sketch.
+
+## Security boundary
+
+This prototype prevents accidental disclosure through supported operations. Native values are not a hidden Python object graph. Source parsing and file export do not route contents through Python callbacks.
+
+It is **not a hostile-code sandbox or a production-grade secrets facility**. Native-memory access, debuggers, the operating system, compromised native code and a developer deliberately exporting secrets remain outside the guarantee. Timing, exception occurrence, termination, file sizes and I/O side effects can reveal information. Native release does not guarantee full zeroization.
+
+Source/file operations run with the process's filesystem rights. The application developer is trusted. There is intentionally no independent policy engine.
+
+## Tests
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -t . -v
+PYTHONPATH=src python -m coverage run -m unittest discover -s tests -t . -q
+python -m coverage report
+PRIVPY_HYPOTHESIS_PROFILE=ci PYTHONPATH=src python -m unittest discover -s tests -t . -q
+```
+
+Hypothesis provides generated data, shrinking, a persistent regression database, generated programs and a state machine for lifetime/ownership sequences.
+
+Profiles: `dev` uses up to 200 examples per property, `ci` up to 1,000 with deterministic generation, and `stress` up to 10,000. Finite input spaces may be exhausted earlier. Failures include minimized examples and reproduction instructions. `PRIVPY_TEST_STATE` selects the local database directory.
+
+Run the same **Python** suite against an UndefinedBehaviorSanitizer build:
+
+```sh
+PYTHONPATH=src python -m privpy.build --sanitize --output /absolute/work/runtime-sanitized.dylib
+PRIVPY_NATIVE=/absolute/work/runtime-sanitized.dylib PYTHONPATH=src python -m unittest discover -s tests -t . -q
+```
+
+On Linux use a `.so` output path. Test cases remain Python; the native library is rebuilt with instrumentation.
+
+See [TESTING.md](TESTING.md) for extending the suite.
+
+## Builds and PyPI
+
+GitHub Actions runs tests, native sanitizer checks, source builds, and wheels for CPython 3.9–3.14 on Linux and macOS, each on Intel and ARM. Published GitHub releases trigger verified PyPI uploads through Trusted Publishing.
+
+See [RELEASING.md](RELEASING.md) for the exact PyPI publisher fields and release steps, and [VALIDATION.md](VALIDATION.md) for local verification results.

privpy-0.1.0/README.md

@@ -0,0 +1,159 @@
+# privpy
+
+**Private computations, native-owned values, explicit export.**
+
+Experimental same-process Python module. The runtime is C++17; the entire test suite is Python, using `unittest` and Hypothesis.
+
+## Install from PyPI
+
+Install the latest release into your Python environment:
+
+```sh
+python -m pip install privpy
+```
+
+To upgrade an existing installation:
+
+```sh
+python -m pip install --upgrade privpy
+```
+
+Prebuilt wheels include the native runtime for CPython 3.9–3.14 on macOS 14+ and glibc 2.28+ Linux, on Intel and ARM. These wheels do not require a local C++ compiler. If pip selects a source archive instead, the source-build requirements below apply. Windows and PyPy are not supported yet.
+
+## Example
+
+Save protected functions in a Python file so their source can be inspected.
+
+```python
+from pathlib import Path
+from privpy import PrivateRegion, private_function
+from privpy.intrinsics import read_json, json_bytes
+
+@private_function
+def read_records(path):
+    return read_json(path)
+
+@private_function
+def total_paid(records):
+    total = 0
+    for row in records:
+        if row["status"] == "paid":
+            total += row["amount"]
+    return total
+
+@private_function
+def encode_total(total):
+    return json_bytes({"total": total})
+
+with PrivateRegion() as region:
+    records = read_records("/absolute/orders.json")
+    total = total_paid(records)
+    print(total)  # <PrivateRef>
+
+    # Deliberate disclosure: the caller chooses what gets exported.
+    public_total = region.export(total)
+    region.export(total, to=Path("/absolute/new-report.json"), transform=encode_total)
+```
+
+There is no `policy`, `region.run`, universal `load`, `format`, or destination alias. The context manager establishes the active region. Decorated functions execute in a native interpreter; their original Python bodies are never invoked with private inputs.
+
+## Build and run
+
+Requires Python 3.9+ and macOS or Linux. Building from source needs a C++17 compiler with floating-point `std::to_chars` support. Release wheels target macOS 14+ and glibc 2.28+ Linux. The pinned development environment uses Python 3.12.
+
+```sh
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements-test.txt
+PYTHONPATH=src python -m privpy.build
+PYTHONPATH=src python examples/orders.py
+PYTHONPATH=src python examples/orders.py --output /absolute/new-report.csv
+```
+
+If a virtual environment already exists, activate and reuse it.
+
+`python -m pip install .` builds the native library during installation. There are no Python runtime dependencies. Source-checkout use only needs `PYTHONPATH=src` and the explicit build command.
+
+## Implemented contract
+
+- A region owns native values. Outside Python receives a `PrivateRef` containing an owner reference and integer handle.
+- Public arguments are copied in; their original Python copies remain public.
+- Native source readers retrieve regular files without routing plaintext through Python. They do not make a public source file secret.
+- Private calls remain native. Outside callbacks, dynamic imports and arbitrary Python libraries are rejected.
+- Every result stays private, including booleans, lengths and aggregates.
+- Export is deliberate disclosure. It checks mechanics, not whether the contents are semantically safe to reveal.
+- `export(value)` returns an independent supported Python value.
+- `export(value, to=Path(...))` requires bytes and writes them directly from native storage.
+- An optional decorated transform runs before export. There is no implicit formatting, encoding or encryption.
+- Destinations must be absolute. Existing files and symlinks are never replaced. Symlink components are rejected; use an already-canonical directory path. Complete output is published atomically from a mode-0600 temporary file in the same directory.
+- Closing a region invalidates all its references. Exported values and files survive.
+
+## Supported subset
+
+Data: null, booleans, signed 64-bit integers, finite binary64 floats, Unicode strings, bytes, lists and string-keyed dictionaries.
+
+Syntax: local assignment, single-level subscript updates, unpacking, arithmetic, comparisons, boolean expressions, indexing, conditional expressions, `if`, `for`, `while`, loop `else`, `break`, `continue`, return, one-generator list comprehensions and calls between private functions.
+
+Builtins: `len`, `bool`, scalar `str`, `abs`, `sum`, `min`, `max`, `range`.
+
+Methods: dictionary `get`, `keys`, `values`, `items`; string UTF-8 `encode`.
+
+Source and encoding operations:
+
+```python
+from privpy.intrinsics import (
+    read_json, read_text, read_bytes, json_bytes, csv_bytes, utf8_bytes,
+)
+```
+
+Prototype semantics:
+
+- CSV uses minimal quoting with comma separators and CRLF record endings. NUL characters are preserved and do not by themselves force quoting.
+- Collection updates use value semantics; updating one binding does not mutate another reference.
+- Dictionaries iterate in sorted key order, and their view methods return lists.
+- Integers are bounded. Overflow raises a sanitized execution error.
+- Floor division and modulo currently accept integers only.
+- Mixed integer/float comparisons reject integers outside binary64's exact integer range.
+- Functions require inspectable source. Closures, defaults, variadic/keyword-only parameters and keyword arguments inside protected calls are unsupported. Named arguments at the public call boundary work.
+- Limits bound input/value sizes, collections, native nesting, recursion and interpreter steps. `PrivateRegion(max_steps=...)` adjusts a per-call resource limit.
+- Unsupported syntax fails explicitly, even in unreachable branches.
+
+Full dataframe engines, secrets-manager SDKs, network clients, encryption, arbitrary third-party libraries, custom classes and asynchronous private functions are not implemented. The example demonstrates record processing without claiming pandas compatibility. [DESIGN.md](DESIGN.md) contains the target API and architecture sketch.
+
+## Security boundary
+
+This prototype prevents accidental disclosure through supported operations. Native values are not a hidden Python object graph. Source parsing and file export do not route contents through Python callbacks.
+
+It is **not a hostile-code sandbox or a production-grade secrets facility**. Native-memory access, debuggers, the operating system, compromised native code and a developer deliberately exporting secrets remain outside the guarantee. Timing, exception occurrence, termination, file sizes and I/O side effects can reveal information. Native release does not guarantee full zeroization.
+
+Source/file operations run with the process's filesystem rights. The application developer is trusted. There is intentionally no independent policy engine.
+
+## Tests
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -t . -v
+PYTHONPATH=src python -m coverage run -m unittest discover -s tests -t . -q
+python -m coverage report
+PRIVPY_HYPOTHESIS_PROFILE=ci PYTHONPATH=src python -m unittest discover -s tests -t . -q
+```
+
+Hypothesis provides generated data, shrinking, a persistent regression database, generated programs and a state machine for lifetime/ownership sequences.
+
+Profiles: `dev` uses up to 200 examples per property, `ci` up to 1,000 with deterministic generation, and `stress` up to 10,000. Finite input spaces may be exhausted earlier. Failures include minimized examples and reproduction instructions. `PRIVPY_TEST_STATE` selects the local database directory.
+
+Run the same **Python** suite against an UndefinedBehaviorSanitizer build:
+
+```sh
+PYTHONPATH=src python -m privpy.build --sanitize --output /absolute/work/runtime-sanitized.dylib
+PRIVPY_NATIVE=/absolute/work/runtime-sanitized.dylib PYTHONPATH=src python -m unittest discover -s tests -t . -q
+```
+
+On Linux use a `.so` output path. Test cases remain Python; the native library is rebuilt with instrumentation.
+
+See [TESTING.md](TESTING.md) for extending the suite.
+
+## Builds and PyPI
+
+GitHub Actions runs tests, native sanitizer checks, source builds, and wheels for CPython 3.9–3.14 on Linux and macOS, each on Intel and ARM. Published GitHub releases trigger verified PyPI uploads through Trusted Publishing.
+
+See [RELEASING.md](RELEASING.md) for the exact PyPI publisher fields and release steps, and [VALIDATION.md](VALIDATION.md) for local verification results.

privpy-0.1.0/RELEASING.md

@@ -0,0 +1,58 @@
+# Building and publishing privpy
+
+Repository: https://github.com/technoyoda/privpy.
+Distribution and import name: `privpy`.
+
+## PyPI setup
+
+Configure a GitHub **Trusted Publisher** with these exact fields:
+
+| PyPI field | Value |
+| --- | --- |
+| PyPI project name | `privpy` |
+| Owner | `technoyoda` |
+| Repository | `privpy` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+For a new project, use PyPI's [pending publisher form](https://pypi.org/manage/account/publishing/). For a project you already own, add the publisher in its Publishing settings. PyPI explains both [new-project setup](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/) and [existing-project setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/).
+
+Create the `pypi` environment in GitHub under repository **Settings → Environments**, and configure its release-tag restrictions as appropriate. If you add required reviewers, the publish job will wait for their approval. No PyPI API token or GitHub secret is needed: the publisher uses GitHub OIDC. [PyPI publishing documentation](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+
+## What the workflows do
+
+- **Tests** (`tests.yml`): Linux and macOS on Python 3.12 and 3.14, the full property-based suite with the 1,000-example CI profile, Python coverage, and a second run against UndefinedBehaviorSanitizer.
+- **Build distributions** (`build.yml`): a tested source archive and 24 installed-and-tested wheels for CPython 3.9–3.14, on Linux x86_64/AArch64 and macOS Intel/Apple Silicon. Wheels are built from that source archive. The final bundle must pass metadata, version, native-library, and complete-matrix checks.
+- **Publish to PyPI** (`release.yml`): on a **published GitHub release**, require the tag to match the source version, rerun Tests and Build distributions, then publish their validated artifacts through the `pypi` environment.
+
+Pushes to `main` and pull requests run Tests and Build distributions. Both also support manual runs. Neither of those events publishes to PyPI. The publishing job has OIDC permission; build and test jobs have read-only repository permissions. Publishing runs in a separate job without checking out or executing project source.
+
+Published GitHub prereleases also trigger publishing; use a PEP 440 prerelease version such as `0.2.0rc1` and matching tag `v0.2.0rc1`. A GitHub prerelease checkbox alone does not turn `0.2.0` into a PyPI prerelease.
+
+Wheels target glibc 2.28+ Linux and macOS 14+. Windows, musl Linux, PyPy and free-threaded Python are not part of this matrix. Older Python wheel tests resolve a compatible Hypothesis version; the main CI suite uses `requirements-test.txt` pins.
+
+The publisher emits PyPI attestations. [PyPI attestation documentation](https://docs.pypi.org/attestations/producing-attestations/)
+
+## Make a release
+
+1. Change `src/privpy/_version.py`. It is the single version source.
+2. Commit and push the changes; check the Tests and Build distributions runs.
+3. Create a tag exactly matching that version, for example `v0.1.0`, on the desired commit.
+4. Publish a GitHub release for that tag.
+5. Watch Publish to PyPI. Downloadable build artifacts are retained in its Actions run.
+
+Only the publish step uploads to PyPI. PyPI versions cannot be overwritten. A partial upload fails visibly; investigate which files arrived before deciding how to recover. The workflow does not silently skip existing distributions.
+
+## Local packaging check
+
+Run inside the project with a virtual environment:
+
+```sh
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+python scripts/check_dist.py dist
+RELEASE_TAG=v0.1.0 python scripts/check_release.py
+```
+
+`python -m build` builds the wheel from the newly produced source archive. Building from source needs a C++17 compiler with floating-point `std::to_chars` support. macOS release builds set `MACOSX_DEPLOYMENT_TARGET=14.0`. To reproduce the full matrix, use the Build distributions workflow; local cibuildwheel requires additional platform tooling. [cibuildwheel documentation](https://cibuildwheel.pypa.io/en/stable/setup/)

privpy-0.1.0/TESTING.md

@@ -0,0 +1,60 @@
+# Test contract and growth plan
+
+All test code is Python. The suite uses `unittest` and real Hypothesis property-based tests, rather than replacing properties with fixed random loops.
+
+## Categories
+
+| Suite | Contract |
+| --- | --- |
+| `test_api.py` | Lifetime, ownership, task/thread contexts, opacity, export, destination behavior |
+| `test_compiler.py` | Allowed syntax, rejected escape operations, bindings, control flow, no callbacks |
+| `test_properties.py` | Nested-value round trips, Python differential oracles, generated expressions, transforms, serialization and I/O |
+| `test_stateful.py` | Generated create, compute, copy, export, nest, close and reopen sequences |
+| `test_native.py` | Malformed parser/ABI inputs, Unicode, numeric boundaries, resource limits, concurrent publication |
+| `test_regressions.py` | Minimized float, CSV and scoping failures retained independently of the example database |
+| `test_packaging.py` | Release-tag properties, malformed/incomplete distribution rejection, metadata and native-library requirements |
+
+## Properties
+
+- Export of `identity(x)` preserves supported values.
+- Safe-range arithmetic and comparisons agree with Python; overflow is rejected.
+- Generated expression trees agree with an independent Python oracle.
+- Unicode indexing, length and encoding agree with Python.
+- CSV encoding agrees with `csv.writer` for documented input types.
+- The CSV oracle uses an escape character absent from the generated input to avoid older CPython's incidental NUL quoting. NUL values remain covered, including deterministic regressions.
+- JSON reading and encoding agree with Python for the strict supported subset.
+- Inline transforms equal separate protected transformation followed by export.
+- File export writes exact bytes; paths never infer formats.
+- Existing files remain unchanged under repeated/concurrent exports and symlink attempts.
+- Exported mutable objects are independent copies.
+- Reference representations are independent of contents.
+- Lifetime and ownership hold under generated operation sequences.
+- Unsupported callbacks fail before executing host code on private values.
+- Malformed native requests produce handled failures rather than crashes.
+
+## Profiles and reproducibility
+
+`dev`: up to 200 examples per property, persistent shrinking database.
+
+`ci`: up to 1,000 examples per property, deterministic generation for a fixed Hypothesis version.
+
+`stress`: up to 10,000 examples per property, persistent shrinking database.
+
+Pinned versions are in `requirements-test.txt`. Hypothesis reports minimized failures and reproduction blobs. Preserve important discovered cases as deterministic regressions too; the local database is not the only record of a bug.
+
+## Adding a feature
+
+1. Specify its semantics and unsupported cases.
+2. Add a Python oracle or invariant independent of the native implementation.
+3. Extend strategies with valid and invalid inputs.
+4. Add state-machine transitions when lifetime or ownership changes.
+5. Preserve minimized bug regressions.
+6. Run normal and sanitizer suites.
+
+Coverage helps find missing behavior; it is not proof of security. Python coverage does not measure C++. Native coverage needs separate instrumentation and reporting. Sanitizers do not prove absence of bugs or side channels.
+
+The Python coverage report enforces a 90% floor. CI configuration exercises macOS and Linux; only the local platform results recorded in `VALIDATION.md` have actually been run during initial development.
+
+## Exclusions
+
+Tests do not claim hardware isolation, resistance to hostile native memory access, constant-time execution, full zeroization, unrestricted Python/pandas compatibility, or semantic safety of deliberately exported values.

privpy-0.1.0/VALIDATION.md

@@ -0,0 +1,43 @@
+# Initial validation
+
+Validated on macOS ARM64 with Python 3.12.14 and Apple Clang 21.0.0. All test code is Python. The package version is 0.1.0.
+
+## Results
+
+| Check | Result |
+| --- | --- |
+| Full Python suite | 211 tests passed |
+| Property coverage | 51 Hypothesis properties plus a rule-based state machine |
+| Python runtime coverage | 96% combined statement/branch coverage; 90% enforced floor |
+| CI profile + AddressSanitizer + UndefinedBehaviorSanitizer | 211 tests passed; no sanitizer diagnostics |
+| Native line coverage | 93.80% |
+| Native branch coverage | 79.33% |
+| Native function coverage | 100% of 85 functions |
+| GitHub Actions static validation | actionlint 1.7.12 passed |
+| cibuildwheel configuration | 24 intended Python/platform build identifiers verified |
+| Local wheel and source archive | Built successfully; strict Twine metadata checks passed |
+| Release guards | Tag matching, missing native runtime, wrong versions and incomplete bundles tested |
+
+The native coverage values come from the final CI-profile sanitizer run. AddressSanitizer leak detection was disabled; these results do not establish leak freedom. Python coverage excludes the compiler-invocation build helper and does not measure C++.
+
+The default Hypothesis profile exercises up to 200 examples per property; the CI run uses up to 1,000. Finite strategy domains can be exhausted earlier. The state machine generates region creation, computation, export, nesting, closure and invalid-reference sequences.
+
+## Failures caught during development
+
+- Valid subnormal floating-point input was rejected by the original number parser.
+- Binary wire encoding incorrectly applied a plaintext limit to its expanded representation.
+- Float rendering differed from Python at notation boundaries.
+- CSV needed quotes around a single empty field.
+- Comprehension variable scope incorrectly affected later name resolution.
+- Repeated structural nesting and shared-value expansion needed explicit limits.
+- A generated unknown-method test allowed Python keywords; the strategy now generates legal identifiers.
+
+Runtime regressions are preserved as deterministic cases alongside generated tests. The release suite also rejects incomplete or incorrectly identified package bundles.
+
+## Scope
+
+Local execution verifies macOS ARM64 and Python 3.12. The Linux, Intel macOS, and other Python jobs are configured in GitHub Actions but have not run remotely during this initial local implementation. Publishing requires the repository changes to be pushed and the PyPI Trusted Publisher to be configured. No PyPI upload was performed.
+
+The commit candidates were checked for local home/workspace paths, personal Git identity, email addresses, credential patterns, generated artifacts and logs. Local build outputs, virtual environments, profiling files and test databases are excluded. Repository author configuration uses a neutral identity. The explicitly chosen public GitHub repository is retained in package metadata.
+
+These checks do not establish a production security boundary. The limits described in README.md and DESIGN.md still apply, including hostile native code, side channels and lack of guaranteed zeroization.

privpy-0.1.0/examples/orders.json

@@ -0,0 +1,6 @@
+[
+  {"country": "US", "amount": 1200, "status": "paid"},
+  {"country": "GB", "amount": 700, "status": "paid"},
+  {"country": "US", "amount": 300, "status": "paid"},
+  {"country": "GB", "amount": 900, "status": "pending"}
+]