Skip to content

E22 — Pykit simplification

State Closed
Start Date 2026-11-14
Closed Date 2026-11-17
Feature State Iteration Stories
F22.1 — Short specs with stable work records Closed release-9 2 Closed
F22.2 — One current explanation per audience Closed release-9 2 Closed
F22.3 — Behavioral tests and performance baselines Closed release-9 3 Closed
F22.4 — Commons with explicit side effects Closed release-9 5 Closed
F22.5 — CLI invocation state with a clear lifetime Closed release-9 2 Closed
F22.6 — Installer transactions with honest recovery Closed release-9 3 Closed
F22.7 — HTTP policy with bounded readiness Closed release-9 3 Closed
F22.8 — Auth policy and bounded caches Closed release-9 5 Closed
F22.9 — Django adapters with safe parsing and ownership Closed release-9 3 Closed
F22.10 — FastAPI adapters with clear validation boundaries Closed release-9 3 Closed
F22.11 — SQLAlchemy bulk work with explicit bounds Closed release-9 2 Closed
F22.12 — Tabular helpers without redundant copies Closed release-9 2 Closed
F22.13 — Small release utilities with one metadata path Closed release-9 2 Closed

Simplify the existing ten packages, their tests and documentation. Give shared policy one owner, remove redundant work, and keep framework adapters focused on translation. Correctness defects found during the review get regression cases before refactoring. Performance work starts with measurements and preserves the observable contract unless a separate decision explicitly changes it.

The review and proposed design explains the evidence, priorities, tradeoffs and measurement plan. Features are in Release 9; implementation is limited to its stories, and the epic authorizes no dependency addition, publishing or history rewrite.

Order

  1. F22.3 establishes behavioral coverage and representative measurements.
  2. Fix the correctness cases in each affected package before moving its code.
  3. F22.4 to F22.13 simplify packages independently. Shared HTTP policy in F22.7 and identity policy in F22.8 precede their adapter changes in F22.9/F22.10.
  4. F22.2 updates consumer documentation with each package change. F22.1 cuts settled spec prose after those changes, preserving unfinished work.

A decision story is settled with the owner before the stories that depend on it. A build story gets its brief, _briefs/<story>.md, when it is next, so each brief is written against current code. A contract settled while writing a brief goes into the story's acceptance, because the brief is deleted when the story closes.

Scope constraints

  • Keep published package boundaries, optional extras and curated facades. A source move within a package must preserve supported imports; a move across packages follows ADR-0002 and has no compatibility alias.
  • Keep RFC wire behavior, security controls, denied-path tests, transaction guarantees and standalone package installs. An intentional behavior change needs its own regression test, changelog entry and versioning assessment.
  • Do not reopen deferred Azure, codegen, messaging, fixtures, Celery or queue work, or promote parked ideas. E15's deferred extractions stay there.
  • Generated tasks, workflows and routing rules remain kiln-owned. Any desired change to their contract is a separate upstream request, not an in-place edit.
  • Preserve permanent IDs, closed work and shipped release records. No squash, branch deletion, retagging or replacement of the existing epic inventory.

Completion

Each feature supplies observable acceptance below. Package changes pass the narrow relevant tests, formatting, typing and import checks through task; the completed epic passes task validate. The performance comparison names inputs, environment, time, peak memory and operation counts; it makes no unmeasured speedup claim. Documentation generation is idempotent and all eleven sites build strictly through task docs:build.

Considered and rejected

  • A package split or a universal adapter framework as the default cleanup. Neither follows from file size or duplicated syntax alone.
  • A fixed line-count or percentage reduction target. It rewards relocating complexity and deleting useful contracts; acceptance follows behavior and eliminated duplication instead.
  • Rewriting specs into a new taxonomy or squashing repository history. Existing IDs, unfinished features and released packages make this a separate decision.