Tree-Mendous 1.1.0

Tree-Mendous 1.1.0

Tree-Mendous 1.1.0 is a compatible minor release that adds the stable,
specialized treemendous.exact_batch native CPU API. It does not change the
stable package-root RangeSet API or backend selection.

Stable API

The exact-batch public surface is exactly:

• ExactBatchRangeSet
• BatchMutation
• MutationOpcode
• BatchLimits
• PackedMutationResults
• BatchLimitError

ExactBatchRangeSet exposes mutate, mutate_packed, snapshot, and the
read-only domain and limits properties. MutationOpcode has the stable ABI
values ADD = 0, DISCARD = 1, and DISCARD_REQUIRE_COVERED = 2.
mutate_packed accepts only exact immutable bytes; each 24-byte row is three
native-endian signed 64-bit integers (opcode, start, end). Packed results use
the documented read-only CSR buffers. See the
complete contract and example.

The specialized object owns independent sorted-vector geometry. It has no
payloads, allocation operation, or generic query API. No exact-batch names are
exported from treemendous, and no exact-batch capability is added to the
backend registry or RangeSetProtocol.

Semver and migration policy

This is a minor release because the new stable module is additive. Version
1.0.0 applications using RangeSet, BackendRegistry, or
create_range_set require no migration.

Experimental exact-batch work existed only during development and was never in
a published Tree-Mendous release. The experimental namespace is deliberately
absent in 1.1.0. Import treemendous.exact_batch directly; there is no
treemendous.experimental compatibility module, alias, deprecation period, or
migration shim for unpublished APIs.

Future compatible additions follow minor-version semantics. Changes to the
stable names, opcode values, dataclass fields/defaults, packed row/result
layout, or containment policy require the corresponding semantic-versioning
review and immutable contract-test update.

Resource limits and concurrency

Every instance has positive, signed-size-checked BatchLimits with these
defaults:

limit	default
max_operations	1,000,000
max_live_intervals	100,000
max_changed_spans	2,000,000
max_result_bytes	256 MiB
max_work_units	100,000,000

A limit failure raises BatchLimitError and publishes no partial state. All
validation, allocation, Python signal interruption, and strict-discard
failures preserve the exact pre-batch snapshot. Rows execute in input order.

Overlapping mutation on one instance is rejected rather than serialized. A
snapshot during staging observes the complete old or complete new state.
Different instances can mutate concurrently. Instances inherited across a
multithreaded fork are unsupported; construct a new instance in the child.
This release does not claim free-threaded CPython support.

Evidence gates

Release publication is gated by the reusable exact-batch evidence workflow
against immutable pre-promotion commit
fdb4efd5f407717c8e18b94e6f4c21cbfb8e5daa. That commit is the main-branch
state immediately before the production interface work, so the scalar gate
measures this promotion rather than unrelated changes since 1.0.0. The gate
rebuilds native code, runs focused correctness, generates correctness-attested
exact-batch and scaling artifacts, and verifies scoped stable scalar
attribution. Fixed gates
cover batch-4 break-even, batch-16 speedup and throughput, no more than 3%
stable scalar regression at the upper 95% confidence bound, and no more than
10 ms at the upper 95% confidence bound for the qualified 100,000-live-interval
batch-16 workload.

Release audit also requires Ruff formatting and lint, mypy, focused and full
non-hardware tests, documentation and packaging contracts, bytecode
compilation, dependency audit, built-artifact verification, and isolated
arbitrary-working-directory smoke tests for both source and wheel installs.

Supported platforms and Python versions

The release matrix builds and verifies CPython 3.11, 3.12, and 3.13 wheels on
hosted Linux x86-64 (repaired manylinux), macOS, and Windows runners. The source
distribution is supported with a C++20 compiler and pybind11 3 or newer. macOS
wheels may also contain the separate experimental Metal extension; that does
not alter the stable CPU exact-batch contract.

Known constraints

• Coordinates, endpoints, and aggregate measure must fit signed 64-bit values.
• Packed rows are native-endian and are not a portable storage or wire format.
• Geometry is bounded by normalized managed-domain components; a row cannot
  cross a component gap.
• Sorted-vector staging scales linearly with live interval count. The evidence
  qualifies the documented workload through 100,000 live intervals, not
  arbitrary states, batches, concurrent load, or application latency.
• Packed result memoryviews are read-only and remain valid, but materialization
  allocates canonical Python result objects.
• CUDA, Metal, free-threaded Python, and alternative interpreters are not part
  of the stable exact-batch guarantee.

Publication prerequisite

The pypi GitHub environment and the treemendous project on PyPI must be
configured for GitHub Actions trusted publishing before the release is
published. The release workflow uses OIDC and one final uploader; platform jobs
must never upload independently. A green build verifies artifacts but does not
by itself prove that PyPI trusted-publisher configuration exists or that
publication succeeded.