Tree-Mendous 1.2.0

Tree-Mendous 1.2.0

A compatible feature release. It adds a faster native RangeSet mutation
surface with a caller-selectable locking level, plus behavior-preserving
snapshot and lease caching. The stable 1.0.0, 1.1.0, and 1.1.1 APIs are
unchanged and existing applications require no migration.

Selectable locking level

RangeSet, create_range_set, and BackendRegistry.create accept a new
synchronized keyword.

• synchronized=True (the default) keeps the reentrant internal lock and full
  thread-safety, including snapshot/mutation consistency.
• synchronized=False performs no internal synchronization: the reentrancy
  guard still functions, but the caller alone owns cross-thread safety and
  snapshot/mutation consistency. Choose it only under a caller-owned locking
  discipline or confirmed single-threaded use. RangeSet.synchronized reports
  the selected level.

Fully-native scalar mutators

RangeSet gains two geometry-only scalar mutators that build no
MutationResult:

• release(span) -> int — free semantics, the scalar counterpart of add.
• reserve(span, *, require_covered=False) -> int — occupy semantics, the
  scalar counterpart of discard; a not-fully-covered strict reserve is a 0
  no-op.

Both return only the changed length and are exactly geometry-consistent with
add/discard. They require an authoritative geometry-only range set without a
payload policy and raise ValueError rather than falling back silently.

Faster add/discard

On the authoritative cpp_boundary path, add/discard now build their
MutationResult through validation-free native constructors for coordinates the
backend has already validated, and call cached bound native mutators directly,
removing the adapter wrapper frame and a per-operation isinstance check. The
returned MutationResult, Span, and IntervalResult values are unchanged.

Scoped hot-path evidence on cpp_boundary (Apple M5 Max, macOS 26.5.1, CPython
3.12.7, timing public mutation calls only): add/discard about 1.5–1.7M
ops/s, the scalar release/reserve about 4.3M ops/s synchronized and about
5.0M ops/s unsynchronized, against a raw-native floor near 7.9M ops/s. See
docs/performance.md; this is scoped evidence for one
interface family and workload, not a universal claim.

Backend, protocol, and native surface

• BackendAdapter exposes supports_scalar_delta, release_delta_length, and
  reserve_delta_length.
• RangeSetProtocol gains release and reserve.
• The C++ IntervalManager exposes release_delta_length and
  reserve_delta_length returning the changed length, and builds its delta
  results without re-validating already-validated int64 geometry. A
  construction-time probe verifies an authoritative backend's delta contract and
  fails closed otherwise.

Behavior-preserving performance

• Geometry-only RangeSet.snapshot() reuses one immutable snapshot while the
  geometry is unchanged and re-materializes after any changed mutation.
  Payload-bearing snapshots keep their clone-and-detach behavior.
• The shared lease pool caches lazy immutable lease/availability projections and
  validates fences through an O(1) token lookup, removing repeated free-state
  rebuilds and public-snapshot scans in the leasing engines.

Compatibility

Every addition is compatible. add, discard, MutationResult, Span, and
IntervalResult retain their exact semantics and types. synchronized=False is
opt-in with a documented single-threaded or externally-synchronized contract.
The treemendous.exact_batch module and the experimental multidimensional
indexes are unchanged.

Tree-Mendous 1.1.1

Tree-Mendous 1.1.1

Tree-Mendous 1.1.1 is a documentation and packaging-metadata patch. It does not
change the stable RangeSet API, the stable treemendous.exact_batch API,
backend selection, application-engine behavior, or experimental
multidimensional runtime behavior.

User documentation

The PyPI landing page now leads with a task-oriented API choice:

• use RangeSet for general queries, allocation, snapshots, and payloads;
• use treemendous.exact_batch for ordered, whole-batch-atomic geometry only;
• use treemendous.applications for one of 50 concrete process-local scenario
  engines;
• use treemendous.multidimensional only as an explicit experiment.

New maintained guides cover choosing an interface,
application patterns, and
performance. The performance guide records scoped local
standard measurements, links the hosted 1.1.0 exact-batch evidence, defines the
timed layers, and gives a gated optimization roadmap without claiming new
runtime work. The 1.1.0 GitHub release now carries durable JSON, Markdown, and
SHA-256 assets for both the standard RangeSet profile and hosted exact-batch
evidence linked by that guide.

Two new executable patterns live outside the 50-engine example directory:

• atomic port-pool reconciliation
  uses exact batch but intentionally supplies no lease identity, TTL, or
  fencing;
• spatiotemporal geofences
  uses experimental, process-local BoxIndex3D.

Exact batch is not integrated into the 50 engines. The radio-spectrum engine
is the existing generic multidimensional integration: it wraps experimental
BoxIndex(2) behind application-specific channel/time reservation semantics.
The Morton geospatial catalog does not use BoxIndex; it uses one-dimensional
Morton candidate bands with exact Cartesian filtering.

Packaging metadata

The project description now reflects the stable Python/C++ range-set backends,
atomic native batch API, experimental multidimensional indexes, and 50
application engines. PyPI metadata adds search keywords and explicit homepage,
documentation, repository, issue, and release links. The version is 1.1.1 and
the lock file is regenerated.

twine>=6.2.0 is part of the build extra. Release source, platform-wheel, and
aggregate artifact jobs run python -m twine check --strict before upload or
publication. The existing pinned Actions, OIDC trusted publication, single
publisher, and job timeouts remain in place.

The source-distribution content policy now requires all new guides and examples.
Documentation contracts execute both patterns from an unrelated working
directory and verify that README repository links are absolute and PyPI-safe.

Compatibility

Version 1.0.0 established RangeSet, BackendRegistry, and
create_range_set as the stable package-root API. Version 1.1.0 added the
contained stable treemendous.exact_batch module without root, backend, or
protocol integration. Those release statements and contracts remain unchanged
in 1.1.1. Existing 1.0.0 and 1.1.0 applications require no migration.

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.

Tree-Mendous 1.0.0

What's Changed

• refactor!: ship the canonical RangeSet API as 1.0 by @josephjohncox in #9
• feat: add concrete application engines and bounded multidimensional indexes by @josephjohncox in #10
• fix: execute the release version check as one Python program by @josephjohncox in #11
• fix: strip native rebuild sources from Windows wheels by @josephjohncox in #12
• fix: pin the PyPI publisher's dereferenced commit by @josephjohncox in #13

Full Changelog: v0.2.5...v1.0.0

Release v0.2.5

Tree-Mendous v0.2.5

• Release v0.2.5
• fix: multiplatform unicode (#8)

Installation

pip install treemendous==0.2.5

What's New

This release includes improvements to interval tree implementations, performance optimizations, and enhanced examples.

Release v0.2.4

Tree-Mendous v0.2.4

• Release v0.2.4
• feat: modernize release system and add cross-platform performance benchmarking (#7)
• build(deps): bump pypa/gh-action-pypi-publish in /.github/workflows (#2)

Installation

pip install treemendous==0.2.4

What's New

This release includes improvements to interval tree implementations, performance optimizations, and enhanced examples.

Release v0.2.3

Tree-Mendous v0.2.3

• Release v0.2.3
• feat: modernize release system and CI/CD with uv (#6)

Installation

pip install treemendous==0.2.3

What's New

This release includes improvements to interval tree implementations, performance optimizations, and enhanced examples.

Release v0.2.1

Tree-Mendous v0.2.1

Initial release of Tree-Mendous interval tree library

Installation

pip install treemendous==0.2.1

What's New

This release includes improvements to interval tree implementations, performance optimizations, and enhanced examples.

v0.1.0

What's Changed

• build: init by @josephjohncox in #1

New Contributors

• @josephjohncox made their first contribution in #1

Full Changelog: https://github.com/josephjohncox/TreeMendous/commits/v0.1.0