slicecompose 0.1.0__tar.gz

slicecompose-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,35 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build
+
+      - name: Build package distribution
+        run: python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

slicecompose-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+src/slicecompose/_version.py

slicecompose-0.1.0/CLAUDE.md

@@ -0,0 +1,69 @@
+# slicecompose — project notes
+
+## What this is
+
+Exact slice-composition library: `compose(s1, s2)` returns a slice equivalent
+to `arr[s1][s2]` for **all** sequence lengths, or `None` exactly when none
+exists. Sound AND complete — both directions are hard guarantees. Never
+weaken either one to make a test pass.
+
+## Environment
+
+- micromamba env: **py10** (pure-stdlib library; only pytest is needed).
+
+## Layout / packaging
+
+- src layout per projtemplate: library in `src/slicecompose/__init__.py`,
+  tests in `tests/`. `verify_examples.py` stays at root (tied to PROBLEM.md).
+- `pyproject.toml` uses setuptools + setuptools_scm (version from git tags;
+  `fallback_version = "0.0.0"` keeps builds working before the first tag).
+  `src/slicecompose/_version.py` is generated — never edit or commit it.
+- pytest works from the repo root without installing (pytest `pythonpath =
+  ["src"]` in pyproject) — no editable install into py10 needed.
+- ruff is configured in pyproject (line-length 99, double quotes).
+
+## Testing
+
+- Quick tier: `micromamba run -n py10 python -m pytest -q` from the repo root (~30 s)
+- Exhaustive tier: prefix `SLICECOMPOSE_FULL=1` (~35 min; measured 36 min)
+- Run heavy tiers with `ulimit -v` and `nice`.
+- Ground truth for any manual check is CPython `range` slicing:
+  `range(n)[s1][s2] == range(n)[s3]` is exact, O(1) even for astronomical
+  `n`, and ranges compare by value. Prefer it over the library's own
+  `_eval1`/`_eval2` when independence matters.
+
+## Architecture invariants
+
+- **Soundness never depends on candidate generation**: every candidate
+  (including ±1 wiggles) must pass `_verify`, which compares only
+  ground-truth point evaluations. Keep it that way — new candidate families
+  are cheap to add and cannot break soundness.
+- **Completeness** lives in the forcing lemmas (EXPLANATION.md §5.2) and the
+  candidate generators. This is the risky part: any change there requires
+  re-running the exhaustive grid audit (FULL tier) — it has caught a real
+  forcing-lemma bug before (the K<0 window stop pin).
+- No code path may branch on field *magnitudes* (only signs, `None`-ness,
+  and exact comparisons); this uniformity is what lets the exhaustive
+  small-field audits stand in for all magnitudes.
+- `SlicePlan` must keep delegating reduction to the `SliceChain` greedy
+  stack: the stack is left-to-right, so a collapsed prefix + new tail
+  reduces identically to the raw history and plan results are independent
+  of when queries happened. An "optimal" interval-DP reduction would break
+  that path-independence unless the raw history were kept alongside.
+
+## Documentation sync
+
+- EXPLANATION.md §8 quotes the FULL-tier grid/table sizes; keep them in sync
+  with the parameters in `test_slicecompose.py` when grids change.
+- The runtime estimates in the test module docstring are measured values;
+  update them if the grids change.
+
+## Known theory facts (verified, documented in EXPLANATION.md §7)
+
+- Adjacent-pair chain reduction is **not confluent**: merge order can change
+  the final chain length, and the greedy stack does not always reach a
+  shortest fixpoint (spec only requires *a* fixpoint, so this is not a bug).
+- Pairwise merging is inherently incomplete for chains ≥ 3: e.g.
+  `[2::-1], [:2], [:-1]` equals the single slice `[2:0:-2]` for every `n`,
+  yet neither adjacent pair merges. A k-ary `compose` would be needed to
+  detect such chains.

slicecompose-0.1.0/EXPLANATION.md

@@ -0,0 +1,405 @@
+# Why `compose` is sound and complete for every length
+
+`compose(s1, s2)` must return a slice equivalent to `arr[s1][s2]` for **all**
+lengths `n >= 0`, or `None` exactly when no such slice exists.  Testing any
+finite set of lengths cannot establish this by itself; the argument below
+shows how the implementation reduces the infinite quantification over `n` to
+finitely many exact checks, without ever enumerating ranges (fields may be
+astronomically large integers).
+
+Throughout, `s1 = (a1, b1, k1)`, `s2 = (a2, b2, k2)` are the input slices and
+`q = k1` after the mirror reduction of §2 (so `q >= 1`), `K = k1*k2`,
+`D = q*|k2|`.  `ceil(x/y)` denotes ceiling division.
+
+## 1. The action of a slice, and the equality criterion
+
+For a slice `s` and length `n`, Python's semantics (`slice.indices`) yield
+normalized `(alpha(n), beta(n), k)` and select the index progression
+
+    I_j(n) = A(n) + k*j,      0 <= j < L(n),
+
+where `A = alpha` and `L(n) = max(0, ceil((beta - alpha)/k))`.  The clamped
+anchor forms are (with `[x]+ = max(0, x)`):
+
+| step  | field        | normalized form                                      |
+|-------|--------------|------------------------------------------------------|
+| k > 0 | start `None` | `alpha = 0`                                          |
+| k > 0 | start `s>=0` | `alpha = min(s, n)`                                  |
+| k > 0 | start `s<0`  | `alpha = [n+s]+`                                     |
+| k > 0 | stop  `None` | `beta = n`                                           |
+| k > 0 | stop  `e>=0` | `beta = min(e, n)`                                   |
+| k > 0 | stop  `e<0`  | `beta = [n+e]+`                                      |
+| k < 0 | start `None` | `alpha = n-1`                                        |
+| k < 0 | start `s>=0` | `alpha = min(s, n-1)`                                |
+| k < 0 | start `s<0`  | `alpha = max(-1, n+s)`                               |
+| k < 0 | stop  `None` | `beta = -1`                                          |
+| k < 0 | stop  `e>=0` | `beta = min(e, n-1)`                                 |
+| k < 0 | stop  `e<0`  | `beta = max(-1, n+e)`                                |
+
+`_indices`/`_eval1` implement exactly these formulas (unit-tested against
+CPython's own slicing for thousands of random slices and lengths).
+
+Every anchor is either **front-anchored** (`alpha`/`beta` eventually a
+constant) or **back-anchored** (eventually `n + const`).  Two virtual
+positions exist only via `None`: "the whole back" (`beta = n`, k > 0) and
+"before the beginning" (`beta = -1`, k < 0).
+
+**Equality criterion.**  Two actions `(A, k, L)` and `(A', k', L')` at length
+`n` select the same subsequence iff
+
+    L = L'  and  (L = 0 or A = A')  and  (L <= 1 or k = k').
+
+Since `range(n)` has pairwise-distinct elements, per-`n` equality of index
+selections is exactly the problem's equivalence.  `_pt_eq` implements this.
+
+The composition of `s1` then `s2` acts as
+
+    m(n) = L1(n),
+    A(n) = alpha1(n) + k1 * A2(m(n)),   K = k1*k2,   L(n) = L2(m(n)),
+
+because selecting `j`-th of `s2` inside the `s1`-selection composes the two
+affine index maps (`_eval2`).  So `compose` must decide: *is there a slice
+whose `(A, L)` functions agree with the composed ones in the sense above for
+every `n`, with step `K` wherever some `L >= 2`?*
+
+## 2. Mirror reduction: assume `k1 >= 1`
+
+Define `~x = -x-1` and `mirror(s) = slice(~start, ~stop, -step)` with `None`
+kept.  **Lemma (mirror).**  For every slice `u` and every `n`:
+
+    arr[::-1][u] == arr[mirror(u)].
+
+*Proof.*  Reversal maps position `p` to `n-1-p`.  The `j`-th selected index of
+`u` on the reversed sequence is `A_u(n) + k_u j` in reversed coordinates,
+i.e. `n-1-A_u(n) - k_u j` in original coordinates: an action with step
+`-k_u`.  Applying `p -> n-1-p` to the table above maps each anchor form to the
+corresponding form with the field negated bitwise (`min(s,n)`-type maps to
+`max(-1, n+~s)`-type and vice versa, front and back swap), and the two virtual
+`None` positions map to each other.  Hence the transformed action is exactly
+the action of `mirror(u)`.  ∎
+
+Since `rev . rev = id`, also `u = rev . mirror(u)`.  Consequently
+
+    s1 . s2  =  rev . (mirror(s1) . s2),
+
+and applying the lemma once more: `s1 . s2` is expressible as a single slice
+iff `mirror(s1) . s2` is, and the results correspond via `mirror`.  If
+`k1 < 0`, `mirror(s1)` has positive step, so `compose` recurses once with
+`q = |k1|` and mirrors the result back.  From here on `q >= 1`.
+
+## 3. Structure of the composed action
+
+### 3.1 Breakpoints (regime boundaries)
+
+Every `min`, `max`, `[.]+` branch switch and every sign change of
+`beta - alpha` in §1 is a comparison between two terms of the form `c` or
+`n + c` with `c ∈ {0, ±start, ±stop}`.  Hence:
+
+**Lemma B1.**  All regime boundaries of a slice's action, as functions of the
+length, lie in `{x + y + d : x, y ∈ {0, ±fields}, |d| <= 2}`.
+
+`_combo_vals` takes exactly this generous superset.  For the composed action,
+`s2`'s regimes live in `m`-space; they are pulled back to `n`-space:
+
+**Lemma B2.**  `m(n) = L1(n)` changes by at most 1 when `n` grows by 1 (one
+added element extends any slice result by at most one element; immediate from
+the formulas), and is monotone between consecutive breakpoints of `s1` (there
+`beta1 - alpha1` is affine).  Hence `m` crosses each critical value `V` of
+`s2` at most once per piece, cannot skip it, and the crossing is found
+exactly by binary search (`_pullback_breaks`).  On the unbounded final piece,
+a crossing of `V`, if any, occurs within `q*(V+4) + 4*Mag + 64` of the piece
+start (`m` moves with slope `1/q` and offsets bounded by the field
+magnitudes `Mag`), so the bounded search window loses nothing.
+
+The union of `s1`-breakpoints, pulled-back `s2`-breakpoints, the candidate's
+own breakpoints (Lemma B1 applied to it), and `{0..3}`, each with ±2 guards,
+cuts `n >= 0` into **stretches** (`_stretches`); by construction every
+involved function is regime-constant on every stretch.  The count is O(1)
+(a few hundred at most), independent of field magnitudes.
+
+### 3.2 Per-stretch normal forms
+
+**Lemma S1 (lengths).**  On a stretch, `m` is constant or
+`ceil((±n + c)/q)`; `L2` as a function of `m` is constant or
+`ceil((±m + c')/k2')` with `k2' = |k2|` (possibly clamped at 0, which only
+truncates the staircase).  Composing and using the exact identities
+
+    ceil((ceil(x/p) + c)/r) = ceil((x + p*c)/(p*r)),
+    ceil((c - ceil(x/p))/r) = ceil((p*(c-1) + 1 - x)/(p*r)),
+
+the composed `L(n)` on a stretch is **constant, or
+`max(0, ceil((±n + c'')/D))` with `D = q*|k2|`**: a monotone staircase with
+unit jumps spaced exactly `D`.  The same holds for a candidate slice with
+divisor `|k3|`.
+
+**Lemma S2 (first index).**  On a stretch, `A(n) = alpha1(n) + q*A2(m(n))`
+where `alpha1` is affine (slope 0 or 1) and `A2` is affine in `m` with slope
+`tau ∈ {0, 1}` (slope 1 iff `s2`'s start is back-anchored in the active
+regime).  Since `q*ceil((±n+c)/q) = ±n + c + ((∓n - c) mod q)`,
+
+    A(n) = affine(n) + tau * sawtooth_q(n),
+
+where the sawtooth has period `q` and amplitude `q - 1`.  It is present
+(non-degenerate) iff `tau = 1`, `m` non-constant on the stretch, and `q > 1`.
+A candidate slice's `A` is affine on every stretch (its regime switches are
+breakpoints).
+
+**Lemma S3 (monotonicity).**  On a stretch, `m` is monotone and `L2` is
+monotone in `m` over the traversed range (no regime change inside), so the
+composed `L` is monotone on every stretch; likewise the candidate's `L`.
+Consequently `{n in stretch : L(n) >= t}` is a contiguous prefix or suffix.
+
+**Lemma S4 (final stretch).**  Beyond the last breakpoint no clamp changes
+state anymore, so `L` is constant or a growing staircase.  A strictly
+decreasing regime always terminates at its zero-crossing, which is a
+pulled-back death threshold (a 2-field combination, Lemma B1) and hence a
+breakpoint; the code still guards the impossible case (`tail_mode ==
+'shrink'`) conservatively.
+
+## 4. The verifier is exact (soundness)
+
+`_verify` compares the composed action `f` with a candidate's action `g` on
+every stretch.  All probes evaluate **ground truth** (`_eval2`, `_eval1`
+implement §1 directly), so no derived formula can silently disagree with
+Python's semantics; the lemmas are only needed to show the probes *suffice*.
+
+On a **finite stretch** `[u, v]` (`_check_stretch_finite`):
+
+1. *Support and step-relevance regions.*  For `t ∈ {1, 2}` the regions
+   `{L_f >= t}` and `{L_g >= t}` are contiguous (S3) and are computed exactly
+   by monotone binary search; they must coincide.  This pins where results
+   are empty, where they have one element, and where steps matter.
+2. *Lengths on the `L>=2` region `[w1, w2]`.*  Point comparisons at `w1`
+   (which has `L >= 2`) force `k3 = K`, hence both staircases have the same
+   divisor `D` (S1).  Two monotone unit-jump staircases that are exactly
+   `D`-periodic, agree at `w1`, and have the same first jump position (found
+   by binary search, compared, and value-checked at `jump-1, jump, jump+1`)
+   are identical on the region: level and phase determine an exact staircase.
+   The `L ∈ {0, 1}` parts are already fixed by step 1.
+3. *First indices on the `L>=1` region.*  `g`'s `A` is affine (S2).  If the
+   composed sawtooth is active (measured via `tau` and `m` at the region's
+   endpoints — exact because regimes are constant) and the region spans at
+   least `q` points, `f`'s `A` contains a full sawtooth period, is not
+   affine, and cannot equal any slice's `A`: reject.  Otherwise the region
+   contains at most one sawtooth wrap.  The checked points include `w1`,
+   `w1+1`, midpoint, `w2-1`, `w2`: if there is no wrap both sides are affine
+   and agreement at two adjacent points implies agreement everywhere; if
+   there is one wrap, the composed values after the wrap deviate from the
+   affine function through `(w1, w1+1)` by exactly `±q ≠ 0`, which the
+   endpoint checks expose.
+4. All curated points are additionally compared with the full criterion of
+   §1 (length, first index, step where relevant).
+
+On the **final stretch** `[u, ∞)` (`_check_stretch_inf`): by S4 both sides
+are constant or growing exact staircases with divisor at most
+`dmax = max(D, |k3|)`, so every threshold and the first jump lie within
+`u + 2*dmax + 5`; the same finite reasoning applies there, far probes at
+`u + 3*dmax + 7` (and `+ dmax` beyond) pin constant levels and growth, and
+exact `D`-periodicity (S1) extends the jump alignment to all `n`.  An active
+sawtooth necessarily wraps on an infinite support region and is rejected
+outright — no slice can match it (this is what kills, e.g., `[::2][::-1]`).
+
+**Soundness theorem.**  If `_verify(t1, t2, cand)` returns `True`, then the
+candidate is equivalent to the composition for every `n >= 0`: the stretches
+cover all `n`, and on each stretch steps 1–4 establish pointwise equality of
+the selections in the sense of §1.  Since `compose` only ever returns a
+verified candidate, every returned slice is correct — independently of any
+property of the candidate generator.
+
+## 5. Candidate generation is exhaustive (completeness)
+
+Suppose *some* equivalent slice `w = (s, e, k3)` exists.  We show the
+generator (`_candidates`) emits a candidate that is pointwise-equal to `w`
+for all `n`; the verifier then accepts it, so `compose` cannot return `None`.
+
+### 5.1 Every slice belongs to one of finitely many families
+
+From the table in §1, classify `w` by its support `{n : L_w(n) >= 1}` and
+tail behavior:
+
+- **always empty**;
+- **bounded support**: only back-start/front-stop with `k3 > 0`, or
+  front-start/back-stop with `k3 < 0` (every other anchor combination has
+  `beta - alpha` eventually constant or growing, giving tail support or
+  emptiness);
+- **tail support, `L` eventually constant** ("windows"): front/front or
+  back/back anchors, either step sign;
+- **tail support, `L` growing**: front-start/back-stop with `k3 > 0`, or
+  back-start/front-stop with `k3 < 0` (the growth forces the stop to recede
+  with `n` while the start stays anchored).
+
+The profile (§3 machinery without a candidate) measures the composition's
+support bounds `N0`, `N1`, its tail mode (empty / constant `P` / growing),
+`max_len`, and tail probes `A(n̂)`, `sigma = A(n̂+1) - A(n̂)`.  These
+measurements are exact: on the final stretch the forms of S1/S2 hold, so
+constancy vs. growth is decided by probes `2D+5` apart, and monotone binary
+searches locate the support boundaries.  Equivalence forces `w` to reproduce
+exactly these measured quantities, which places `w` in exactly one family
+and, as shown next, forces its parameters.
+
+### 5.2 Parameter forcing per family
+
+*Step.*  If `max_len >= 2`, some `n` has two selected elements whose distance
+is `q*k2`, so `k3 = K` (generated as such).  If `max_len <= 1`, the step
+never influences the selection beyond enforcing `L <= 1`: for the emitted
+shapes, `L >= 1` is step-independent (`beta - alpha >= 1`) and the single
+selected element is `alpha(n)`; any `kappa >= max(beta - alpha)` works and
+all such slices are pointwise identical, so emitting the safe bound
+`max(1, ...)` loses nothing.
+
+*Start.*  On the tail, `sigma ∈ {0, 1}` for any slice (S2 without sawtooth).
+`sigma = 0` forces a front anchor with `s = A(n̂)` (on its support a
+front-anchored start equals its field); `sigma = 1` forces a back anchor with
+`s = A(n̂) - n̂`.  If the measured `sigma` is anything else, the composed `A`
+is not affine on the tail (it carries a sawtooth) and **no** slice matches —
+correctly yielding `None`.  For bounded support the same reading is done at
+the support ends `N0`, `N1`.
+
+*Stop.*
+- *Growing `L`, `K > 0`* (front/back): the tail lengths are
+  `ceil((n + e - s)/K)`; the position `n_j` of the first length jump past
+  `n̂` (binary search) and the value `L(n_j)` pin `e` exactly:
+  `e = s + K*(L(n_j)-1) + 1 - n_j`, with `e = 0` meaning `stop=None`.
+  Distinct `e` give distinct tail length functions, so `e` is unique.
+- *Growing `L`, `K < 0`* (back/front): symmetrically
+  `e = n_j + s + K*(L(n_j)-1) - 1`, with `e = -1` meaning `stop=None`.
+- *Window, `K > 0`, front/front*: `e` may vary within one step bucket
+  `(s + K(P-1), s + K*P]`.  **Bucket invariance:** for any `n`, replacing `e`
+  by another bucket member changes `beta = min(e, n)` only when `beta = n`
+  for both or when `n` lies between them, in which case `ceil((n - s)/K)`
+  equals `P` as well — the selection is unchanged *for every* `n`.  Both
+  bucket ends are emitted.
+- *Window, `K > 0`, back/back*: the support start of
+  `[s:e:K]` (`s < e <= 0`) is `max(1, 1 - e)` (while the start clamps at 0,
+  `L >= 1` iff `n + e >= 1`), so `e = 1 - N0`, unique.
+- *Window, `K < 0`, front/front*: the support start of `[s:e:K]` is `e + 2`
+  (`beta = min(e, n-1) < alpha` first happens there), or `1` for
+  `stop=None`; so `e = N0 - 2`, unique.  (The tail bucket does *not* pin `e`
+  here: bucket members differ at small `n` while the start is clamped —
+  found and fixed by the exhaustive grid audit.)
+- *Window, `K < 0`, back/back*: bucket freedom again; the clamp
+  `beta = max(-1, n+e)` hands over seamlessly (`L = min(ceil((n+s+1)/|K|), P)`
+  independent of the bucket member), so both bucket ends are emitted.
+- *Bounded support:* emptiness first fails at `N1 + 1`, giving
+  `e = N1 + s + 1` (`K > 0`) resp. `e = s - N1 - 1` (`K < 0`); the start is
+  read at the support ends as above.
+
+*`max_len <= 1` shapes.*  The selected-element function `E(n) = A(n)` of any
+`L <= 1` slice is, on its support: constant `c` (front start; support is then
+forced to be exactly `{n > c}` for every such slice, so one representative
+`slice(c, c+1)` suffices); `[n+s]+` (back start, tail support; support start
+`N0` pins the stop via `e = 1 - N0` as above, `kappa = max(1, e - s)`);
+`min(s, n-1)` (negative-step front start; `e = N0 - 2`,
+`kappa = max(1, s - e)`); or the bounded-support versions handled with the
+bounded pins.  Anything else (e.g. the parity-dependent `E` of `[::2][-1:]`)
+matches no slice and correctly yields `None`.
+
+±1 wiggles around every derived stop (and the alternative start readings for
+bounded support) are also emitted purely as armor against off-by-one
+conventions; the exact verifier filters them, so they cannot affect
+soundness.
+
+**Completeness theorem.**  If an equivalent slice `w` exists, the profile
+places it in one family; the forcing lemmas show the generator emits a
+candidate pointwise-equal to `w` (either `w`'s exact parameters or an
+equivalent bucket/`kappa` representative).  The verifier, being exact (§4),
+accepts it.  Hence `compose` returns `None` only when no equivalent slice
+exists.
+
+## 6. Always-empty compositions and edge cases
+
+- If `max_len = 0` (e.g. `[5:3][::-1]`), `slice(0, 0, 1)` is emitted and
+  trivially verified — any always-empty slice is acceptable.
+- `n = 0` imposes no constraint (every slice selects nothing), and all
+  formulas above are exact from `n = 0` on.
+- Emitted slices are cosmetically normalized (`start 0 -> None` for positive
+  step, `start -1 -> None` for negative step, `step 1 -> None`); each rewrite
+  is a strict semantic identity from the table in §1, and it is the
+  normalized triple that gets verified.
+
+## 7. `SliceChain`
+
+`SliceChain(*slices)` reduces with a stack: each incoming slice is repeatedly
+merged with the top of the stack while `compose` succeeds.  A successful
+merge replaces the top, so the new top is retried against its own left
+neighbor — this finds cascading reductions such as
+
+    [::2], [::-1], [::-1]  ->  [::2], [:]  ->  [::2]
+
+(the problem's chain example: the *last two* merge first, then again).
+Invariant: adjacent stack entries never merge; therefore one pass reaches a
+state where **no adjacent pair merges**, which is the required fixpoint.
+The invariant is maintained because mergeability of a pair depends only on
+the pair's composed function, and a merge leaves the composed function of
+every disjoint pair unchanged — so the already-checked pairs to the left
+stay unmergeable.
+
+The fixpoint is not canonical, though: adjacent-pair reduction is **not
+confluent**, and merge order can even affect the length of the result.  A
+merge consumes its two blocks, which can destroy a pairing the optimum
+needed.  Example (all claims machine-verified):
+
+    [-2:2], [0:2], [:0:-1], [1:0:-1]
+
+The stack eagerly merges the first pair and then gets stuck at three slices,
+while merging the middle pair first (`[0:2][:0:-1] == [1:2]`) collapses the
+whole chain to a single always-empty slice.  So the stack reaches *a*
+fixpoint (as the problem statement requires) but not always a shortest one;
+finding a shortest reachable fixpoint would take an interval DP over
+mergeable blocks, matrix-chain style.  Pairwise merging is moreover
+inherently incomplete for chains of three or more:
+
+    [2::-1], [:2], [:-1]   ==   [2:0:-2]   for every n,
+
+yet neither adjacent pair is expressible on its own, so no merge order can
+reduce this chain at all; deciding such cases would require a k-ary
+`compose`.
+
+`apply` simply applies the reduced slices in order, which is correct whether
+or not any merging happened (each merge preserved the function).  The
+reduced tuple is exposed as `.slices`.
+
+`SlicePlan` is a lazy wrapper over the same reduction: it gathers slices
+unreduced (each bracket application returns a new plan) and on first query
+replaces its stored chain by the `SliceChain` fixpoint, flagging itself
+reduced.  Because the stack processes slices left to right, its state after
+the prefix *is* the collapsed prefix, so reducing a collapsed prefix plus
+new tail equals reducing the raw history — query timing never affects a
+plan's result, and everything above applies to `SlicePlan` unchanged.
+
+## 8. Validation performed
+
+The proofs above are the argument for all `n`; the test suite additionally
+hammers every code path empirically:
+
+- the problem statement's 17 merge examples, 6 non-merge examples, and the
+  chain examples;
+- an **exhaustive** grid of 147,456 pairs (fields in `{None, 0, ±1, ±2, ±3}`,
+  steps up to `±3`) and 1,000,000 pairs with steps up to `±6` and fields up
+  to `±7`: every merge is checked against brute force for `n <= 500` plus
+  large spot lengths, and every `None` is audited for completeness against
+  brute-force candidate tables of 18,000 resp. ~221,000 slices (both
+  audits found zero defects; an earlier run of the audit is what caught
+  the `K < 0` window stop-pin bug described in §5.2);
+- randomized soundness checks with fields up to `10^30` and steps up to
+  `10^12`, compared at random lengths up to `10^60`;
+- a structural completeness probe at huge magnitudes: for random triples,
+  `(s1∘s2)∘s3` and `s1∘(s2∘s3)` decide expressibility of the same function,
+  so their `None`-ness must agree whenever both pair-merges exist;
+- the mirror lemma tested pointwise for thousands of random slices,
+  including huge fields;
+- `_indices`/`_eval1` tested against CPython's own slicing.
+
+Because no branch of the implementation depends on the *magnitude* of any
+field (only on signs, `None`-ness, and exact comparisons), the exhaustive
+small-field audits exercise every regime combination that large-field inputs
+can produce; large-field correctness then follows from the magnitude-uniform
+lemmas, and is additionally spot-checked directly.
+
+## 9. Complexity
+
+`compose` performs O(1) profile/verification stretches, each with O(1)
+probes plus binary searches over value ranges bounded by the field
+magnitudes — O(polylog(magnitude)) big-integer operations total
+(~0.1 ms for small fields, ~1 ms for 100-digit fields).  No operation ever
+materializes a range, so memory is O(1).

slicecompose-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 István Sárándi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.