cutctx 0.1.0__tar.gz

cutctx-0.1.0/.editorconfig

@@ -0,0 +1,23 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+[*.{toml,yml,yaml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+[Makefile]
+indent_style = tab

cutctx-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff format --check .
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install ruff
+      - run: ruff check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: mypy src tests
+
+  boundaries:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: lint-imports
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python-version }}" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=xml
+
+  tests-314-early-warning:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.14" }
+      # Deliberately unpinned: ci.lock is resolved on 3.13, and pinning a version that has no
+      # 3.14 wheels would defeat the purpose of an early warning.
+      - run: pip install -e ".[dev]"
+      - run: pytest -m "not live and not performance"
+
+  coverage:
+    needs: [tests]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m "not live and not performance" --cov --cov-report=term-missing --cov-fail-under=95
+
+  contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/ci.lock
+      - run: pip install . --no-deps
+      - run: pytest -m contract
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # gitleaks scans *history*, and `actions/checkout` fetches a single commit by default.
+        # For a push it is handed `<first-pushed>^..<last-pushed>`, so the parent of the first
+        # pushed commit has to be in the object store; in a depth-1 clone it is not, and git
+        # answers "unknown revision", which the action reports as exit code 1. It fails the same
+        # way whether or not a secret exists, so a green run would not have meant anything either.
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install pip-audit
+      # Audit the locked sets, not the job's own environment: a bare `pip-audit` here would
+      # inspect an environment containing only pip-audit itself (Security Standards §11).
+      - run: pip-audit --require-hashes -r requirements/ci.lock
+      - run: pip-audit --require-hashes -r requirements/release.lock
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  install-check:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - run: pip install dist/*.whl
+      - run: python -c "import cutctx"

cutctx-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  workflow_dispatch:   # manual TestPyPI dry run; see publish-testpypi below
+
+permissions:
+  id-token: write   # required for PyPI Trusted Publishing
+  contents: write   # required to create the GitHub release
+
+jobs:
+  release:
+    # Tag pushes only. Without this, clicking "Run workflow" for the TestPyPI dry run below would
+    # also fire this job and publish to real PyPI — the exact opposite of a dry run.
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the Environment name set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      # Byte-for-byte the dry run's build chain below. A real release that resolved `build` and
+      # `hatchling` fresh from PyPI would not be the artifact the dry run proved.
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish-testpypi:
+    # Manual only, via Actions -> Release -> Run workflow. Packaging and Release Standards §6
+    # requires a successful TestPyPI publish ahead of a package's first real release; 0.1.0 is
+    # this package's first published version, so run this once before tagging v0.1.0. Later
+    # releases may skip it, or use it again as a dry run.
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install --require-hashes -r requirements/release.lock
+      - run: python -m build --no-isolation
+      - run: twine check dist/*
+      - run: pip install "dist/$(ls dist | grep .whl)[dev]"
+      - run: pytest -m "not live and not performance"
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

cutctx-0.1.0/.gitignore

@@ -0,0 +1,104 @@
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# ---- Packaging / build backends ----
+pip-wheel-metadata/
+share/python-wheels/
+
+# ---- Testing / coverage ----
+.pytest_cache/
+.cache
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+*.py,cover
+htmlcov/
+nosetests.xml
+.hypothesis/
+
+# ---- Type checking / linting ----
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+.pytype/
+
+# ---- Virtual environments ----
+.venv/
+venv/
+ENV/
+env/
+env.bak/
+venv.bak/
+.python-version
+
+# ---- Distribution / dependency locking ----
+# requirements/*.lock is deliberately NOT ignored. The lock files are committed
+# inputs: CI and release jobs install from them with --require-hashes (Packaging
+# and Release Standards §4, Security Standards §11), so an ignored lock file
+# means a checkout that cannot build.
+
+# ---- Editors / OS ----
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# ---- Suite runtime state (this component's local data) ----
+# The application writes to XDG paths at runtime (~/.config, ~/.local/share,
+# ~/.local/state per Master Architecture §1.2), never inside the repository.
+# These entries only guard against a developer pointing XDG_* at the repo
+# during local testing.
+.local/
+.config/
+*.sqlite3
+*.sqlite3-journal
+*.sqlite3-wal
+*.sqlite3-shm
+/data/
+/logs/
+/backups/
+/artifacts/
+/exports/
+
+# ---- Secrets ----
+# Per Security Standards §8: secrets are never committed. Config files may
+# only name where a secret comes from (*_env / *_file), never the value.
+.env
+.env.*
+*.key
+*.pem
+secrets.toml
+
+# ---- Node-free JS assets (MirrorWall consumers may still use a local tool) ----
+node_modules/
+
+# ---- Build artifacts from docs generation ----
+docs/api/openapi-v1.json.tmp
+
+# ---- import-linter cache ----
+# `lint-imports` writes this on every gate run; it is a cache, never an input.
+.import_linter_cache/

cutctx-0.1.0/.importlinter

@@ -0,0 +1,89 @@
+[importlinter]
+root_package = cutctx
+include_external_packages = True
+
+[importlinter:contract:no-application-imports]
+name = CutCtx must not import applications
+type = forbidden
+source_modules = cutctx
+forbidden_modules =
+    freeweight
+    loadcoach
+    ideapress
+    promptcadence
+
+[importlinter:contract:no-sibling-packages]
+name = CutCtx must not import sibling capability packages
+type = forbidden
+source_modules = cutctx
+forbidden_modules =
+    setspec
+    modelrack
+    sweatmeter
+    weightsdb
+    mirrorwall
+    toolyard
+    loadledger
+    commissioner
+    spotcheck
+
+[importlinter:contract:no-second-path-to-a-model]
+# ADR-0052 decision 2 and gold standards §2: purity is proven, not claimed. The package holds no
+# HTTP client and no provider, so summarization *cannot* be performed here even by accident — it
+# crosses the boundary as a SummarizationRequest. `no-sibling-packages` above already bars
+# `modelrack`; this contract bars the do-it-yourself alternative.
+#
+# allow_indirect_imports: these contracts describe what *this package's own modules* import.
+# `baseaicore` is stdlib-only, so no chain reaches these today, but a chain through a dependency
+# would be that dependency's budget to answer for, not a CutCtx import to fix.
+name = CutCtx must hold no HTTP client and no socket
+allow_indirect_imports = True
+type = forbidden
+source_modules = cutctx
+forbidden_modules =
+    httpx
+    requests
+    aiohttp
+    urllib3
+    urllib
+    http
+    socket
+    ssl
+    asyncio
+
+[importlinter:contract:no-persistence]
+# ADR-0052 decision 2: no database, no filesystem. CutCtx never persists anything (spec §10); the
+# caller stores plans and reports. The stdlib halves matter as much as the third-party ones: a
+# `pathlib` import here would be the first step of a cache nobody asked for.
+name = CutCtx must touch no database and no filesystem
+allow_indirect_imports = True
+type = forbidden
+source_modules = cutctx
+forbidden_modules =
+    sqlalchemy
+    alembic
+    sqlite3
+    os
+    io
+    pathlib
+    shutil
+    tempfile
+    glob
+    subprocess
+    logging
+
+[importlinter:contract:no-clock-and-no-randomness]
+# The one package in the suite that needs no clock. A plan carries no time, because a plan must be
+# byte-identical on re-derivation (spec §11 contract 4) and appears in an audit record. If a
+# `CompactionReport` wants a timestamp, the caller stamps it. Randomness is barred for the same
+# reason: it is the other way a re-derived plan stops matching the one that was recorded.
+name = CutCtx must read no clock and draw no randomness
+allow_indirect_imports = True
+type = forbidden
+source_modules = cutctx
+forbidden_modules =
+    datetime
+    time
+    random
+    secrets
+    uuid

cutctx-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+        args: [--fix=lf]
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks

cutctx-0.1.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0: `0.x`).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-03
+
+The first release. Phases 1 and 2 of the
+[development plan](docs/packages/cutctx/development-plan.md) — the vocabulary, the invariants, and
+the four shipped policies.
+
+### Added — Phase 2, the policy set
+
+* **`ObservationMaskingPolicy`** — replaces old `TOOL` bodies with a labelled stub carrying the
+  original's **sha256 and token estimate, never an excerpt** (spec §14): the original may hold a
+  secret, and a "first 200 characters" preview is a leak with an extra step. The turn stays in the
+  view at its own position, which is why masking orphans nothing and is legal under contract 3.
+  Reasoning turns are left byte-identical — that is the whole value of the policy, and a property
+  asserts it rather than hoping for it.
+* **`SummarizingPolicy`** — folds the oldest contiguous unpinned span into one planned summary turn
+  and one `SummarizationRequest`. It **plans a summarization and never performs one** (ADR-0052):
+  no model, no HTTP client, no prompt text, and a `prompt_id` naming a versioned record.
+* **`PolicyChain`** and **`default_chain`** — masking → summarizing → drop-oldest, stopping as soon
+  as the budget fits.
+* **`DEFAULT_PLACEHOLDER`** and **`GROUP_ID_PREFIX`**, so a consumer reading a plan can recognise a
+  shipped policy's output.
+* **Cross-matrix determinism goldens** for all four policies, over the Phase-1 fixtures at every
+  Phase-1 budget (dev-plan AC2) and over a second fixture set large enough to actually produce a
+  stub and a summary group — because the Phase-1 transcripts are reached by keeping and dropping
+  alone, and a golden set that locked in only those would lock in nothing new.
+* **A property suite over every shipped policy**, against oracles restated from the spec in a
+  different shape from the implementation (`maskable_ids` counts backwards where the policy slices;
+  `exchange_rule_holds` keys on the correlation id with no notion of position).
+* **`acceptance/plan_and_apply.py`** — spec §20 criterion 2 as a runnable check rather than a
+  demonstration, exiting non-zero when a claim fails.
+
+### Decided — Phase 2
+
+* **Contract 3 said the wrong thing, and the document was amended.** Read literally, "masked
+  together" forbade the `ObservationMaskingPolicy` §7 ships. Phase 1 enforced the reading that the
+  prohibition is on *separation* — and what separates is *removal* — and left the decision to this
+  row. Having built the policy, the reading is confirmed: within one exchange, either every member
+  is retained (`KEEP`/`MASK`, mixed freely) or every member is removed by the same action. The spec
+  now states the enforced rule.
+* **A chain composes over a projection, not over an applied view.** Applying requires summaries and
+  this package produces none, so the chain builds the view each plan *would* produce — a masked
+  turn's replacement is in the plan, a summary turn's id is derived and its estimate is
+  `target_tokens` — and lifts the next policy's decisions back onto the real transcript. **One
+  plan is built, once, through `_invariants.build_plan`.** A later policy that removes a summary
+  turn removes everything folded into it, and a half-removed exchange is escalated to the removing
+  action before the plan is built rather than being rejected after.
+* **Ordering is transcript position at every step**, never a `dict` or `set` iteration order. The
+  development plan named "nondeterminism via dict ordering in group assembly" as this phase's
+  likely failure mode, and it is the kind that reproduces only under an unlucky `pytest-randomly`
+  seed unless the ordering is structural.
+* **A summary group's id is a digest of its span's turn ids** — never a counter and never a uuid.
+  A counter would renumber when a chain composed the policies differently, and the id is in the
+  plan's bytes *and* in the summary turn's derived id.
+* **Masking stops as soon as the budget fits**, oldest result first, the way `DropOldestPolicy`
+  does; `keep_recent_results` is a floor that does not move for the budget. Masking every eligible
+  result would cost the model observations for nothing.
+* **A result smaller than its own stub is left alone.** A stub costs about thirty tokens, so
+  masking a two-token result would *increase* the estimate, and a transcript of many tiny results
+  would grow under a policy whose purpose is shrinking.
+* **A planned summary's token figure is `target_tokens`** — an estimate of a text that does not
+  exist yet — and the executor does not re-estimate the text it is handed. That is contract 5
+  working as intended; recomputing anything in the report is exactly what makes plan and report
+  able to disagree.
+
+### Fixed — Phase 2
+
+* **`SummarizingPolicy` folded a span even when the transcript already fitted the budget**, which
+  spent a model call and replaced turns the model could still have read. Found by the property
+  `test_a_transcript_that_already_fits_is_left_alone_by_every_shipped_policy`, which runs over
+  every shipped policy: the other three check the budget inside a loop over reductions, and this
+  one has no such loop, so it needed the check stated explicitly.
+
+### Added — Phase 1
+
+* **Transcript model** — `TranscriptTurn`, `Transcript`, `Role`, `Action`, `CompactionBudget`,
+  with `tool_call_id` as a *correlation* id so that a multi-call assistant turn and all of its
+  results form one tool exchange.
+* **Plan vocabulary** — `TurnAction`, `TurnReplacement`, `SummarizationRequest`, `CompactionPlan`,
+  `CompactedTranscript`, `CompactionReport`, `CompactionPolicy`. `CompactionReport` is the body of
+  the suite's `context.compacted` event (spec §11 contract 7) and carries no timestamp.
+* **`cutctx._invariants`** — spec §11 contracts 1–3 in one place, plus the token arithmetic and
+  the `budget_unmet` determination. `CompactionPlan` takes the transcript and budget it is a plan
+  *for* as `InitVar`s and validates against them at construction, so there is no path to an
+  unvalidated plan.
+* **`BudgetUnsatisfiable`** naming both numbers, `SummaryMissing` naming the group,
+  `PlanTranscriptMismatch` naming the difference — all under `CompactionError`, all subclassing
+  `baseaicore.SuiteError`.
+* **`CharRatioEstimator`** (`chars_per_token=4.0`) behind the `TokenEstimator` protocol, with the
+  ratio recorded on plans that used it and never presented as a count.
+* **`CompactionExecutor.apply`** — masking, summary substitution, `summaries` fulfilment, and a
+  report whose figures are copied from the plan rather than recomputed.
+* **`DropOldestPolicy`** — drops whole tool exchanges, oldest first, until the budget fits;
+  `budget_unmet` when it cannot, `BudgetUnsatisfiable` when nothing could.
+* Property-based invariant suite (`hypothesis`), determinism goldens, an import-graph purity test,
+  and the spec §15 performance targets behind the `performance` marker.
+
+[Unreleased]: https://github.com/JPKell/CutCtx/commits/main

cutctx-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to CutCtx
+
+This repository is one component of the Local AI Suite. Before changing anything, read
+`docs/packages/cutctx/spec.md` and the current
+phase in `development-plan.md` — both are in this repository's `docs/` folder, copied from the suite's
+central documentation set so this repository can be worked on independently.
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+## Required reading, in order
+
+1. This component's spec — purpose, scope, non-goals, and especially §11, the public contracts
+   `cutctx._invariants` exists to enforce.
+2. `development-plan.md` in the same folder — the phase you are implementing, its acceptance
+   criteria and its tests.
+3. `src/cutctx/_invariants.py`'s module docstring — the rules, how contract 3 is read, and why
+   protection propagates through a tool exchange.
+
+## Rules that apply to every change here
+
+* Follow the architecture's dependency direction.
+  This repository's `.importlinter` enforces it in CI; do not weaken that file to make an import work.
+* **Purity is the product.** No I/O of any kind: no network, no filesystem, no database, no
+  environment, no clock, no randomness, no logging. Five `import-linter` contracts and an
+  import-allowlist test enforce it; do not weaken either to make an import work.
+* **Every policy routes through `cutctx._invariants`.** A `CompactionPlan` cannot be constructed
+  without the transcript and budget it is a plan *for*, and construction validates against them —
+  so there is no unvalidated plan. Build yours with `_invariants.build_plan`, which also does the
+  token arithmetic and the `budget_unmet` determination; a test asserts that every module under
+  `policies/` does.
+* **An estimate is never presented as a count** (ADR-0016): token figures are estimates, and the
+  character-ratio default's ratio rides on the plan that used it.
+* **Prompts are named, never carried** — `prompt_id` refers to a versioned record in the
+  *application's* prompt pack. No prompt text belongs in this package.
+* **Plans are byte-identical on re-derivation.** Nothing may depend on dict insertion order, on a
+  clock, or on randomness. Changing a policy's behaviour bumps its `version` and its goldens.
+* Every phase's acceptance criteria in `development-plan.md` must be demonstrable, not merely
+  test-covered — the plan states what to run and what a person should see.
+
+## Before opening a pull request
+
+```bash
+ruff format --check .
+ruff check .
+mypy src tests
+lint-imports
+pytest -m "not live and not performance"
+```
+
+All of the above run in CI (`.github/workflows/ci.yml`); a red CI run blocks merge. Coverage floor
+is **95 %** (a shared package, not an application).
+
+### Replaying a failing property test
+
+The invariant suite is property-based. `pytest-randomly` reseeds every test, so a failure is not
+reproducible from the command line alone — but the hypothesis profile in `tests/conftest.py` sets
+`print_blob=True`, so each failure prints a `@reproduce_failure(...)` decorator. Paste it onto the
+failing test to replay that exact example; the `--randomly-seed=` line pytest prints reproduces the
+*ordering*. A failure that only appears under one seed is a real bug, never a reason to pin one.
+
+New properties belong beside the existing ones, and new generators in `tests/strategies.py`. Build
+transcripts **by construction**, never by `filter`: heavy filtering gives flaky health-check
+failures and useless shrinking. And state a property against `tests/oracles.py` — the untouchable
+set and the tool exchanges restated from the spec — rather than against the implementation's own
+helpers, or the property moves with the bug.
+
+## Commit style
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`, `perf:`, `build:`,
+`ci:`), with `!` or a `BREAKING CHANGE:` footer for breaking changes. Update `CHANGELOG.md` under
+`## [Unreleased]` for any user-visible change.