integer-atlas-algos 0.1.0__tar.gz

integer_atlas_algos-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/

integer_atlas_algos-0.1.0/COMMANDS.md

@@ -0,0 +1,167 @@
+# Algos — complete command reference
+
+Every command runnable in this repo: the executor CLI (`compute`, `verify`), the
+dev tools, and the test runner.
+
+**Environment**
+- Python 3.10+. The CLI is the `atlas-algos` console command. Get it either way:
+  - **Installed:** `pip install integer-atlas-algos` (or `pip install -e .` from a
+    source checkout) — then `atlas-algos …` works anywhere.
+  - **From source without installing:** run from the `algos/` directory as
+    `python3 -m integer_atlas_algos.executor …` (same subcommands and options).
+  The synopses below use `atlas-algos`; substitute `python3 -m integer_atlas_algos.executor`
+  if you haven't installed it.
+- CSV format needs no dependencies. Parquet needs `pyarrow` (`pip install
+  integer-atlas-algos[parquet]`). A native `blake3` (`[hash]` extra) is an optional
+  fast path; otherwise the bundled pure-Python BLAKE3 is used.
+- First factorization uses `integer_atlas_algos/precomputed/primes_le_31623.txt`
+  (shipped with the package; regenerated by sieve if missing, kept in memory if the
+  dir is read-only).
+
+---
+
+## 1. `compute` — generate a shard
+
+```
+atlas-algos compute --manifest <work-order.json> --out <path> [options]
+```
+
+| Option | Type | Default | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| `--manifest` | path | required | `tests/manifests/base_1_1000.json` | Work order: JSON `{start, end, columns}` (+ optional `id`, `algorithm_release`). |
+| `--out` | path | required | `/tmp/shard` | Destination shard path; extension is normalized to the format. |
+| `--format` | `parquet`\|`csv` | `parquet` | `--format csv` | Shard format. `parquet` needs pyarrow; `csv` is dependency-free. |
+| `--chunk-size` | int | `50000` | `--chunk-size 100000` | Rows per part = checkpoint/resume granularity **and** the memory knob. |
+| `--force` | flag | off | `--force` | Discard any existing output + checkpoint and rebuild from scratch. |
+| `--no-resume` | flag | off (resume on) | `--no-resume` | Ignore an existing checkpoint and recompute (still writes to `--out`). |
+| `--keep-build` | flag | off | `--keep-build` | Keep the `.build/` working dir after success (default: deleted). |
+| `--dry-run` | flag | off | `--dry-run` | Print the work estimate as JSON and exit; compute nothing. |
+| `--log-file` | path | none | `--log-file run.log` | Also write logs here. |
+| `--log-level` | level | `INFO` | `--log-level WARNING` | `DEBUG`/`INFO`/`WARNING`/`ERROR`/`CRITICAL`. |
+
+**Main effect:** computes the requested columns for every integer in `[start, end]`
+and writes one shard file.
+
+**Side effects:**
+- Creates `<out>.<ext>` (the shard) and `<out>.<ext>.manifest.json` (columns, types,
+  row count, SHA256/SHA512/BLAKE3, range, `algorithm_release`, `verification.status:"computed"`).
+- Creates a transient `<out>.<ext>.build/` (part files + `checkpoint.json`) during the
+  run; removed on success unless `--keep-build`.
+- **stdout:** one JSON line — `{"status":"ok"|"noop","shard","manifest","row_count","hashes"}`.
+- **stderr:** an estimate banner, the "safe to Ctrl-C / resume with …" message, and
+  per-chunk progress (`chunk i/N  P%  (rows, eta)`).
+- **Exit codes:** `0` ok/noop · `2` bad input or unknown column · `130` interrupted (Ctrl-C).
+- Re-running a completed work order is a **no-op** (`status:"noop"`). Ctrl-C is safe at
+  any point; rerun the same command to resume.
+
+**When to use:** to produce a shard (contributor), or any time you need property values
+for a range. Use `--dry-run` first to size a job; `--force` to rebuild; `--chunk-size`
+smaller to cap memory, larger to reduce overhead.
+
+---
+
+## 2. `verify` — validate a shard
+
+```
+atlas-algos verify --manifest <entry.json> --shard <shard> [options]
+```
+
+| Option | Type | Default | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| `--manifest` | path | required | `/tmp/shard.csv.manifest.json` | Manifest entry for the shard (`range_start`/`range_end`/`columns`). |
+| `--shard` | path | required | `/tmp/shard.csv` | The shard file to check. |
+| `--degree` | float | `0.1` | `--degree 1.0` | Fraction of rows independently recomputed (0.1 sampled … 1.0 full). |
+| `--seed` | int | `0` | `--seed 42` | Deterministic sample seed. |
+| `--format` | `parquet`\|`csv` | inferred from extension | `--format csv` | Override the shard format. |
+| `--log-file` | path | none | | Also write logs here. |
+| `--log-level` | level | `INFO` | | Log verbosity. |
+
+**Main effect:** recomputes a sample of the requested columns and compares against the
+shard; checks row count, column presence, and `n` contiguity; at `--degree 1.0` also
+re-checks the file's SHA256 if the manifest carries one.
+
+**Side effects:** writes nothing. **stdout:** one JSON line —
+`{"status":"pass"|"fail","degree","checked_rows","sampled","row_count","failures":[…]}`.
+**Exit codes:** `0` pass · `3` verification mismatch · `2` bad input.
+
+**When to use:** contributor self-check before submitting (`--degree 0.1`); maintainer/CI
+validation; `--degree 1.0` for disputed or release-critical shards.
+
+---
+
+## 3. `tools/make_work_order.py` — build a work order
+
+```
+python3 tools/make_work_order.py --start <S> --end <E> [options]
+```
+
+| Option | Type | Default | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| `--start` | int | required | `0` | Range start (inclusive). |
+| `--end` | int | required | `100000` | Range end (inclusive). |
+| `--columns` | csv | all registered | `--columns is_prime,euler_phi` | Explicit column list. |
+| `--exclude` | csv | none | `--exclude partition_count` | Drop columns from the default-all set. |
+| `--id` | str | `all_<start>_<end>` | `--id demo` | Work-order id. |
+| `--algorithm-release` | str | `dev` | `--algorithm-release algos-2026.06` | Pinned release stamped into the order. |
+| `--out` | path | stdout | `--out /tmp/wo.json` | Write here instead of printing. |
+
+**Main effect:** emits a work-order JSON requesting all registered columns (minus
+`--exclude`) or the given `--columns`. **Side effects:** writes `--out` or prints to
+stdout (a one-line note to stderr when `--out` is used). **When to use:** to create the
+input for `compute`/`perfrun`; it emulates what the Shards planner will emit.
+
+---
+
+## 4. `tools/perfrun.py` — benchmark a compute run
+
+```
+python3 tools/perfrun.py --start <S> --end <E> [options]
+```
+
+| Option | Type | Default | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| `--start` / `--end` | int | required | `0` / `100000` | Range to compute. |
+| `--columns` | csv | all registered | | Explicit column list. |
+| `--exclude` | csv | none | `--exclude partition_count` | Drop columns (use this to skip the super-linear ones). |
+| `--format` | `parquet`\|`csv` | `csv` | `--format parquet` | Shard format. |
+| `--chunk-size` | int | `50000` | `--chunk-size 20000` | Part/memory granularity. |
+| `--out` | path | temp file | `--out /tmp/perf` | Output path. |
+
+**Main effect:** runs `compute` in-process (with `--force`) and prints wall time,
+user/sys CPU, CPU utilization, throughput (rows/s, µs/row), peak RSS, and output size.
+**Side effects:** writes a shard (a temp file by default). **When to use:** to measure
+performance and seed the planner cost model. For CPU/memory cross-checks also run the
+plain `compute` under `/usr/bin/time -l` (macOS) or `/usr/bin/time -v` (Linux).
+
+---
+
+## 5. `tools/bench.py` — per-property micro-benchmark
+
+```
+python3 tools/bench.py [n]
+```
+
+| Argument | Type | Default | Example | Meaning |
+| --- | --- | --- | --- | --- |
+| `n` | int (positional) | `1000` | `python3 tools/bench.py 1000000` | The integer each property is timed at. |
+
+**Main effect:** prints a TSV of `column  big_o  usec` (best-of-5 per-call timing).
+**Side effects:** none (no files written). **When to use:** to measure per-property cost
+and refine the cost model; note this is the standalone cost (each factor column re-runs
+factorization here, whereas the executor shares one factorization per n).
+
+---
+
+## 6. Tests
+
+```
+python3 -m unittest discover -s tests -t .                 # all tests
+python3 -m unittest tests.test_properties                  # one module
+python3 -m unittest tests.test_properties.PropertyTest.test_first_100_all_properties
+/path/to/venv/bin/python -m unittest discover -s tests -t .  # include parquet (needs pyarrow)
+```
+
+**Main effect:** runs the unit suite (property test vectors, compute/verify, resume,
+estimate, BLAKE3 vectors, parquet round-trip). **Side effects:** uses temp dirs; the
+first run generates `precomputed/primes_le_31623.txt`. Parquet and native-blake3 tests
+**skip** when those libraries are absent. **When to use:** after any change.

integer_atlas_algos-0.1.0/INTERFACE.md

@@ -0,0 +1,114 @@
+# Algos executor — interface
+
+The executor is a **Python CLI**, invoked as a module today and as a console
+script (`atlas-algos`) once installed. The Go CLI will wrap these same two
+commands later (`integer-atlas compute` / `verify` shell out to this). It is
+**stateless**: every run is a pure function of its input manifest.
+
+```
+atlas-algos compute --manifest <work-order.json> --out <shard> [options]
+atlas-algos verify  --manifest <entry.json>      --shard <shard> [options]
+```
+
+## compute — generate a shard
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--manifest PATH` | required | work order: `{start, end, columns}` (+ optional `id`, `algorithm_release`) |
+| `--out PATH` | required | destination shard path (extension normalized to the format) |
+| `--format {parquet,csv}` | `parquet` | shard format. `parquet` needs pyarrow; `csv` is stdlib (dev/tests) |
+| `--chunk-size N` | `50000` | rows per part / checkpoint interval — the resume granularity |
+| `--force` | off | discard any existing output/checkpoint and rebuild |
+| `--no-resume` | off | ignore the checkpoint and recompute from scratch (keeps `--out`) |
+| `--keep-build` | off | keep the `.build` working dir after success (default: removed) |
+| `--dry-run` | off | print the work estimate and exit without computing |
+| `--log-file PATH` | none | also write logs here |
+| `--log-level LEVEL` | `INFO` | `DEBUG`/`INFO`/`WARNING`/… |
+
+## verify — validate a shard
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `--manifest PATH` | required | manifest entry for the shard (`range_start`/`range_end`/`columns`) |
+| `--shard PATH` | required | the shard file to check |
+| `--degree F` | `0.1` | share of rows independently recomputed (0.1 sampled … 1.0 full) |
+| `--seed N` | `0` | sample seed (deterministic) |
+| `--format {parquet,csv}` | inferred from extension | override the shard format |
+| `--log-file`, `--log-level` | | as above |
+
+## Output
+
+- **Shard file** at `--out` (e.g. `shard.parquet`), written atomically.
+- **Manifest sidecar** at `<out>.manifest.json` — columns, types, row count, hashes
+  (sha256, sha512, blake3 if available), range, `algorithm_release`, `verification.status: computed`.
+- **Working dir** `<out>.build/` exists only while running (parts + `checkpoint.json`);
+  removed on success unless `--keep-build`.
+
+## stdout / stderr / logs
+
+- **stdout**: exactly one line of JSON — the result summary — for machine consumption
+  (the Go CLI parses this). Nothing else goes to stdout.
+  - compute: `{"status": "ok|noop", "shard", "manifest", "row_count", "hashes"}`
+  - verify: `{"status": "pass|fail", "degree", "checked_rows", "sampled", "row_count", "failures": [...]}`
+- **stderr**: human-readable logs and per-chunk progress (`chunk 3/4 done (n=501..750, rows 750/1000)`).
+- **log file**: same records as stderr when `--log-file` is given.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | success (compute ok/noop, or verify pass) |
+| `2` | bad input — malformed work order or unknown column |
+| `3` | verification mismatch (verify only) |
+| `130` | interrupted (Ctrl-C) — progress checkpointed |
+| `1` | other error |
+
+## Recovery model
+
+Parquet cannot be appended atomically per row, so resumability is by **chunked
+commit + checkpoint**:
+
+1. `[start, end]` is split into `--chunk-size` chunks (≈ one row group each).
+2. Each chunk is computed in memory and written to its own part file **atomically**
+   (temp → `fsync` → `rename`), then `checkpoint.json` is advanced atomically.
+3. On restart, the executor **checks** the checkpoint, validates existing parts
+   (presence + row counts), discards any partial/trailing temp or part beyond the
+   trustworthy watermark, and **resumes from the next chunk**. At most one chunk is
+   ever recomputed.
+4. Finalize concatenates parts into the single shard (atomic), hashes it, and writes
+   the manifest. The checkpoint phase moves `computing → finalizing → done`.
+
+Re-running a completed work order is a **no-op** (`status: noop`) — detected from the
+existing shard + manifest, so it is safe to retry blindly. Because methods are pure
+and chunk ranges are deterministic, a resumed run produces byte-identical output to a
+clean run (verified by the test suite).
+
+## Work estimate, progress & interrupting
+
+Every `compute` run prints a banner to stderr **before doing any work**:
+
+```
+Estimated work: 1,000,000 rows x 7 column(s), ~5 min (coarse).
+Safe to interrupt (Ctrl-C) at any time — progress is checkpointed.
+Resume with:
+  atlas-algos compute --manifest wo.json --out shard.parquet --chunk-size 300
+```
+
+- **Estimate**: derived from each column's static `complexity` × row count (machine-independent, coarse). Super-linear columns (e.g. `partition_count`) are flagged because a flat per-row cost under-models them. `--dry-run` prints the full estimate as JSON and stops.
+- **Progress**: each chunk logs `chunk i/N  P%  (done/total rows, eta …)` to stderr (and `--log-file`).
+- **Interrupting**: Ctrl-C is safe at any moment — the chunk in flight is simply not committed, and the checkpoint always reflects the last durably-written chunk. On interrupt the executor prints the percentage reached and the exact **resume command** (re-running `compute` resumes by default), and exits with code 130.
+
+## Running
+
+```
+# tests (stdlib unittest, zero dependencies)
+python3 -m unittest discover -s tests -t .
+
+# try it (CSV, no pyarrow needed)
+atlas-algos compute --manifest tests/manifests/base_1_1000.json --out /tmp/shard --format csv
+atlas-algos verify  --manifest /tmp/shard.csv.manifest.json --shard /tmp/shard.csv --degree 1.0
+
+# real format
+pip install pyarrow   # or: uv sync --extra parquet
+atlas-algos compute --manifest <work-order>.json --out shard.parquet
+```

integer_atlas_algos-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: integer-atlas-algos
+Version: 0.1.0
+Summary: Integer Atlas — stateless property methods and shard executor
+Project-URL: Homepage, https://github.com/outcompute/integer-atlas-algos
+Project-URL: Source, https://github.com/outcompute/integer-atlas-algos
+License: Apache-2.0
+Keywords: dataset,integers,number-theory,parquet,shards
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: hash
+Requires-Dist: blake3>=0.4; extra == 'hash'
+Provides-Extra: parquet
+Requires-Dist: pyarrow>=15; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# Integer Atlas — Algos
+
+> Directory name is provisional and will be renamed later.
+
+The property methods and the compute engine (the executor). This repository is **independent and stateless**: nothing here imports the other repos, and it stores no information about any shard, pack, release, or lifecycle. It is used exactly twice per shard — `compute` (by a contributor) and `verify` (by a maintainer). Master design: [`../Integer Atlas Documentation.docx.md`](../Integer%20Atlas%20Documentation.docx.md) (§16, §11, §17, §2.5).
+
+## Purpose
+
+- Define each integer property as a small registered method.
+- Provide the executor that computes shards and verifies them.
+- Cut algorithm releases that downstream shards pin to.
+
+## What lives here
+
+Algorithms are a **single flat directory** — one method per file, the filename matching the column it produces. Pack, shard, and release names never appear in the layout. Shared helpers live in `_lib`. There are no pack, coverage, or planner files here — those belong to the Shards repo.
+
+```
+integer_atlas_algos/        the installable package (atlas-algos)
+  registry.py               @property_method + the flat column registry
+  context.py                per-n memoized context (factorization, divisors)
+  properties/               one method per file; filename = column name (46 columns)
+  _lib/                     shared helpers
+    factorization.py        prime-table factorization
+    multiplicative.py       sigma() shared by divisor functions
+    blake3_py.py            pure-Python BLAKE3 fallback
+  precomputed/              regenerable resource cache (not state)
+    primes_le_31623.txt     base primes up to ceil(sqrt(1e9))
+  executor/                 the stateless engine
+    cli.py                  argparse CLI (compute / verify, estimate, resume)
+    compute.py              chunked, resumable, crash-safe, streaming finalize
+    verify.py               sampled recompute + compare
+    estimate.py             pre-run work estimate from static complexity
+    manifest.py             work-order loading, draft manifest, hashing
+    atomicio.py             atomic write / checkpoint primitives
+    backends/               csv_backend (stdlib) + parquet_backend (pyarrow)
+tools/                      bench.py, perfrun.py, make_work_order.py (dev only)
+tests/                      unittest suite + sample work-order manifests
+pyproject.toml              package metadata, console script, extras
+COMMANDS.md  INTERFACE.md  PUBLISHING.md   reference docs
+```
+
+Run it with `pip install -e .` then `atlas-algos …`, or from a source checkout as
+`python3 -m integer_atlas_algos.executor …` (run from the `algos/` directory).
+
+All 46 agreed properties are implemented. See [INTERFACE.md](INTERFACE.md) for the
+complete command reference, output layout, exit codes, and the resume model.
+
+## Precomputed data
+
+To factor any n up to BOUND² you only need primes up to BOUND; with
+BOUND = 31623 (≥ √1e9) that is ~3401 primes covering the whole 0..1e9 range.
+`precomputed/primes_le_31623.txt` holds them — a deterministic, regenerable cache
+(sieved on first use if missing), not state about any shard or pack. It bounds
+worst-case factorization to ~3401 trial divisions regardless of n's size in range.
+
+## Status and known limitations
+
+Done and tested: 46 properties, the stateless executor (compute/verify/estimate,
+resumable + atomic + streaming finalize), CSV and **validated Parquet** backends,
+SHA256/SHA512/BLAKE3 hashing. Remaining performance work (not correctness):
+per-shard run is single-threaded pure Python (~3700 rows/s/core — scale by running
+many shards in parallel, one executor each); a segmented-sieve batch fast-path and
+gmpy2 would speed factorization further; `n` is int64 (covers 0..2^63, hence the
+0..1e9 target) — int128 only needed beyond that; `partition_count` is small-n only
+(its values explode) even though its per-row recompute is now memoized.
+
+## Method contract
+
+- Signature is `f(n, ctx) -> value`. The method **name becomes the column name**.
+- `ctx` is a memoized context of shared intermediates (factorization, divisor list, binary representation) declared via `requires`, so expensive work is computed once per number, not once per method.
+- Metadata (canonical column id, dtype, nullable, zero/negative behavior, `requires`, test vectors) is registered next to the function, so the schema, column ids, and manifest columns are generated from code. A method declares **only its own column** — it says nothing about packs, shards, releases, or any other entity.
+- A method may provide an optional **vectorized fast-path** for speed; the **scalar form is always the verification ground truth**.
+- **Test vectors live with the method** and are reused by both the property-proposal gate and shard verification.
+
+## Executor verbs
+
+The executor is **stateless** — both verbs are pure functions of an input manifest that names a `start`, an `end`, and the requested columns. It does not interpret packs, the grid, or policy; if the manifest does not follow project conventions that is fine, and it errors only if a requested column name is unknown.
+
+- `compute --manifest <work-order> --out <shard>` — run the requested column functions over `[start, end]` and write the shard, filling the output manifest's column types and hashes from the method metadata.
+- `verify --manifest <entry> --shard <file> --degree <fraction>` — recompute a share of the requested columns (0.1 sampled … 1.0 full) and compare against the shard; report pass/fail.
+
+## Releases
+
+Cut an algorithm release once enough methods have merged. It is stamped with the commit id and PR URLs, and is what a shard's `algorithm_versions` pins to. Only released methods are eligible for official shards; unreleased methods exist only for local side-loading.
+
+## Packaging
+
+Distributed with **uv**: each release pins `uv.lock`, so `integer-atlas algos sync` (from the CLI) materializes the exact released code and dependencies on any platform — fast, reproducible, no system Python required. Optional PyInstaller one-file artifacts and an OCI image are conveniences; uv is canonical. Compute speed comes from native math libraries (e.g. gmpy2, primesieve) and the vectorized fast-paths, not from the packaging format.
+
+## State: none
+
+This repo stores no state about any shard, pack, release, or lifecycle. Planning, pack definitions, the coverage policy, and the manifest sets all live in the Shards repo. Algos sees a given shard exactly twice — `compute` (contributor) and `verify` (maintainer).
+
+## Contributing
+
+PRs add algorithms (the code pipeline). Include the method, its metadata, and its test vectors. See §10.1 and §17 in the master doc.

integer_atlas_algos-0.1.0/PUBLISHING.md

@@ -0,0 +1,85 @@
+# Publishing Algos to PyPI — GitHub-managed
+
+Goal: `pip install integer-atlas-algos`, releases driven entirely from GitHub via
+Actions + **PyPI Trusted Publishing** (OIDC — no API tokens stored anywhere).
+
+Assumes the **Algos repo is its own GitHub repository** (repo root = this `algos/`
+directory). If you instead keep a monorepo with `algos/` as a subdirectory, add
+`defaults.run.working-directory: algos` to the workflow jobs and a `paths:` filter
+to `ci.yml`.
+
+## Status: packaging is done
+
+- Installable package `integer_atlas_algos/` (flat layout), all imports package-qualified.
+- `pyproject.toml` configured: hatchling, dynamic version from
+  `integer_atlas_algos/__init__.py`, `atlas-algos` console script, `parquet`/`hash`/`dev`
+  extras, primes table shipped via `artifacts`.
+- Build + clean-venv install verified locally (`atlas-algos` runs standalone, all three
+  hashes populate, primes data ships).
+- Workflows are committed under `.github/workflows/`: `ci.yml`, `release.yml`, `testpypi.yml`.
+
+## One-time setup
+
+1. **Create the GitHub repo** and push this directory to it (`main` branch).
+2. **Fill metadata** in `pyproject.toml`: `authors`, and `[project.urls]`
+   (Homepage/Source → the new repo). Confirm `license`.
+3. **Create GitHub Environments** (repo → Settings → Environments): `pypi` and
+   (optional) `testpypi`. Add required reviewers on `pypi` if you want a manual approval
+   gate before each publish.
+4. **Configure PyPI Trusted Publishing** (do this *before* the first release, as a
+   "pending publisher"): on https://pypi.org → Account → Publishing → Add a pending
+   publisher:
+   - PyPI Project Name: `integer-atlas-algos`
+   - Owner: your GitHub user/org
+   - Repository name: the Algos repo
+   - Workflow filename: `release.yml`
+   - Environment name: `pypi`
+5. (Optional) Repeat step 4 on https://test.pypi.org with Environment `testpypi` and
+   workflow `testpypi.yml`.
+
+No tokens are created or stored — OIDC handles auth at publish time.
+
+## The workflows
+
+- **`ci.yml`** — on every push to `main` and every PR: installs `.[parquet,hash,dev]`
+  across Python 3.10–3.13 and runs the unittest suite (so parquet + native blake3 paths
+  are covered in CI).
+- **`release.yml`** — on a pushed tag `v*`: builds the wheel + sdist and publishes to
+  PyPI via OIDC (environment `pypi`).
+- **`testpypi.yml`** — manual (`workflow_dispatch`): same build, publishes to TestPyPI
+  (environment `testpypi`) for a dry run.
+
+## Cutting a release
+
+1. Bump `__version__` in `integer_atlas_algos/__init__.py` (SemVer). PyPI rejects
+   re-uploads of an existing version.
+2. Open a PR; merge to `main` once CI is green.
+3. (Optional) Run the **TestPyPI** workflow from the Actions tab and verify
+   `pip install -i https://test.pypi.org/simple/ integer-atlas-algos`.
+4. Tag and push:
+   ```
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+   `release.yml` builds and publishes to PyPI automatically.
+5. (Optional) Create a GitHub Release from the tag for changelog/notes.
+
+## Local manual fallback (if ever needed)
+
+```
+cd algos
+python3 -m pip install --upgrade build twine
+rm -rf dist && python3 -m build
+python3 -m twine check dist/*
+python3 -m twine upload dist/*        # needs TWINE_USERNAME=__token__ / TWINE_PASSWORD=<token>
+```
+
+## Notes
+
+- PyPI **project name** `integer-atlas-algos` must be available; **import name** is
+  `integer_atlas_algos`; **command** is `atlas-algos`.
+- `dist/`, `build/`, `*.egg-info/` are git-ignored (see `.gitignore`).
+- `tools/` and `tests/` ship in the sdist but not the wheel.
+- This flow is for the **Python package only** (Algos). The CLI repo (Go) will use a
+  different release path (e.g. GoReleaser → GitHub Releases); see the project-level
+  integration TODO.

integer_atlas_algos-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Integer Atlas — Algos
+
+> Directory name is provisional and will be renamed later.
+
+The property methods and the compute engine (the executor). This repository is **independent and stateless**: nothing here imports the other repos, and it stores no information about any shard, pack, release, or lifecycle. It is used exactly twice per shard — `compute` (by a contributor) and `verify` (by a maintainer). Master design: [`../Integer Atlas Documentation.docx.md`](../Integer%20Atlas%20Documentation.docx.md) (§16, §11, §17, §2.5).
+
+## Purpose
+
+- Define each integer property as a small registered method.
+- Provide the executor that computes shards and verifies them.
+- Cut algorithm releases that downstream shards pin to.
+
+## What lives here
+
+Algorithms are a **single flat directory** — one method per file, the filename matching the column it produces. Pack, shard, and release names never appear in the layout. Shared helpers live in `_lib`. There are no pack, coverage, or planner files here — those belong to the Shards repo.
+
+```
+integer_atlas_algos/        the installable package (atlas-algos)
+  registry.py               @property_method + the flat column registry
+  context.py                per-n memoized context (factorization, divisors)
+  properties/               one method per file; filename = column name (46 columns)
+  _lib/                     shared helpers
+    factorization.py        prime-table factorization
+    multiplicative.py       sigma() shared by divisor functions
+    blake3_py.py            pure-Python BLAKE3 fallback
+  precomputed/              regenerable resource cache (not state)
+    primes_le_31623.txt     base primes up to ceil(sqrt(1e9))
+  executor/                 the stateless engine
+    cli.py                  argparse CLI (compute / verify, estimate, resume)
+    compute.py              chunked, resumable, crash-safe, streaming finalize
+    verify.py               sampled recompute + compare
+    estimate.py             pre-run work estimate from static complexity
+    manifest.py             work-order loading, draft manifest, hashing
+    atomicio.py             atomic write / checkpoint primitives
+    backends/               csv_backend (stdlib) + parquet_backend (pyarrow)
+tools/                      bench.py, perfrun.py, make_work_order.py (dev only)
+tests/                      unittest suite + sample work-order manifests
+pyproject.toml              package metadata, console script, extras
+COMMANDS.md  INTERFACE.md  PUBLISHING.md   reference docs
+```
+
+Run it with `pip install -e .` then `atlas-algos …`, or from a source checkout as
+`python3 -m integer_atlas_algos.executor …` (run from the `algos/` directory).
+
+All 46 agreed properties are implemented. See [INTERFACE.md](INTERFACE.md) for the
+complete command reference, output layout, exit codes, and the resume model.
+
+## Precomputed data
+
+To factor any n up to BOUND² you only need primes up to BOUND; with
+BOUND = 31623 (≥ √1e9) that is ~3401 primes covering the whole 0..1e9 range.
+`precomputed/primes_le_31623.txt` holds them — a deterministic, regenerable cache
+(sieved on first use if missing), not state about any shard or pack. It bounds
+worst-case factorization to ~3401 trial divisions regardless of n's size in range.
+
+## Status and known limitations
+
+Done and tested: 46 properties, the stateless executor (compute/verify/estimate,
+resumable + atomic + streaming finalize), CSV and **validated Parquet** backends,
+SHA256/SHA512/BLAKE3 hashing. Remaining performance work (not correctness):
+per-shard run is single-threaded pure Python (~3700 rows/s/core — scale by running
+many shards in parallel, one executor each); a segmented-sieve batch fast-path and
+gmpy2 would speed factorization further; `n` is int64 (covers 0..2^63, hence the
+0..1e9 target) — int128 only needed beyond that; `partition_count` is small-n only
+(its values explode) even though its per-row recompute is now memoized.
+
+## Method contract
+
+- Signature is `f(n, ctx) -> value`. The method **name becomes the column name**.
+- `ctx` is a memoized context of shared intermediates (factorization, divisor list, binary representation) declared via `requires`, so expensive work is computed once per number, not once per method.
+- Metadata (canonical column id, dtype, nullable, zero/negative behavior, `requires`, test vectors) is registered next to the function, so the schema, column ids, and manifest columns are generated from code. A method declares **only its own column** — it says nothing about packs, shards, releases, or any other entity.
+- A method may provide an optional **vectorized fast-path** for speed; the **scalar form is always the verification ground truth**.
+- **Test vectors live with the method** and are reused by both the property-proposal gate and shard verification.
+
+## Executor verbs
+
+The executor is **stateless** — both verbs are pure functions of an input manifest that names a `start`, an `end`, and the requested columns. It does not interpret packs, the grid, or policy; if the manifest does not follow project conventions that is fine, and it errors only if a requested column name is unknown.
+
+- `compute --manifest <work-order> --out <shard>` — run the requested column functions over `[start, end]` and write the shard, filling the output manifest's column types and hashes from the method metadata.
+- `verify --manifest <entry> --shard <file> --degree <fraction>` — recompute a share of the requested columns (0.1 sampled … 1.0 full) and compare against the shard; report pass/fail.
+
+## Releases
+
+Cut an algorithm release once enough methods have merged. It is stamped with the commit id and PR URLs, and is what a shard's `algorithm_versions` pins to. Only released methods are eligible for official shards; unreleased methods exist only for local side-loading.
+
+## Packaging
+
+Distributed with **uv**: each release pins `uv.lock`, so `integer-atlas algos sync` (from the CLI) materializes the exact released code and dependencies on any platform — fast, reproducible, no system Python required. Optional PyInstaller one-file artifacts and an OCI image are conveniences; uv is canonical. Compute speed comes from native math libraries (e.g. gmpy2, primesieve) and the vectorized fast-paths, not from the packaging format.
+
+## State: none
+
+This repo stores no state about any shard, pack, release, or lifecycle. Planning, pack definitions, the coverage policy, and the manifest sets all live in the Shards repo. Algos sees a given shard exactly twice — `compute` (contributor) and `verify` (maintainer).
+
+## Contributing
+
+PRs add algorithms (the code pipeline). Include the method, its metadata, and its test vectors. See §10.1 and §17 in the master doc.

integer_atlas_algos-0.1.0/integer_atlas_algos/__init__.py

@@ -0,0 +1,3 @@
+"""Integer Atlas — stateless property methods and shard executor."""
+
+__version__ = "0.1.0"