capability 1.0.0__py3-none-any.whl

capability/__init__.py

@@ -0,0 +1,64 @@
+"""capability — type-safe composable primitives.
+
+A *capability* is an immutable value that carries its own contribution to a typed context. A
+*fold* threads a context through a sequence of capabilities, applying each (open-world: unknown
+ones are skipped). The same capabilities run through different `Phase`s give different,
+independent results — validation, docs, DDL — and `Phase`s compose into a `Compiler` with
+set-like operators (`+ - & |`) that folds every phase over the values in one pass.
+
+Five properties, by construction:
+
+- **self-describing** — a capability carries its own contribution (no external visitor),
+- **composable** — phases compose into compilers, and compilers into each other,
+- **inspectable** — capabilities and contexts are immutable data (`explain` is free),
+- **open-world** — add a capability or a target without editing the core (`isinstance` dispatch),
+- **type-safe** — the typed `apply` is checked at the call site; `pyright --strict` clean.
+
+The whole engine is `fold` + a `Step`. Everything else is optional layers.
+
+    from capability import Phase, by_protocol
+
+    validate = Phase(Rule, by_protocol(Validated, lambda c, ctx: c.validate(ctx)))
+    rule = validate.run(fields)
+
+`fold`/`afold` are the same overloaded function: a sync step returns the context; an async
+step returns a coroutine. The recommended dispatch is the type-safe `by_protocol`; a
+reflection-based alternative (dispatch by method *name*) lives in `capability.reflect`.
+"""
+
+from capability._attach import from_annotated, from_sidecar
+from capability._compiler import Bundle, Compiler
+from capability._core import AsyncStep, Capability, Step, afold, fold
+from capability._dispatch import Table, by_protocol, by_table, chain
+from capability._phase import Phase
+from capability._trace import FoldStep, Trace, explain, traced_fold
+from capability._folds import Children, TreeStep, fold_tree, rfold, scan
+
+__version__ = "1.0.0"
+__author__ = "prostomarkeloff"
+
+__all__ = (
+    "AsyncStep",
+    "Bundle",
+    "Capability",
+    "Children",
+    "Compiler",
+    "FoldStep",
+    "Phase",
+    "Step",
+    "Table",
+    "Trace",
+    "TreeStep",
+    "afold",
+    "by_protocol",
+    "by_table",
+    "chain",
+    "explain",
+    "fold",
+    "fold_tree",
+    "from_annotated",
+    "from_sidecar",
+    "rfold",
+    "scan",
+    "traced_fold",
+)

capability/_attach.py

@@ -0,0 +1,44 @@
+"""Attach — pluggable extractors for *where capabilities live*.
+
+The library is agnostic about the carrier. These helpers cover the two common ones without
+reflection (`get_args` / `vars` / `__mro__` are sanctioned introspection, not `getattr`):
+
+- `from_annotated(tp)`  — capabilities packed into `Annotated[T, cap, cap, ...]` metadata.
+- `from_sidecar(cls, attr=...)` — capabilities stored in a class-level sidecar attribute.
+
+Both return `tuple[Capability, ...]`; since `Capability` is the empty marker, every metadata
+object qualifies. Narrow to a concrete capability type in the phase that consumes them.
+"""
+
+import typing
+
+from capability._core import Capability
+
+
+def from_annotated(tp: typing.Any) -> tuple[Capability, ...]:
+    """Return the metadata objects of an `Annotated[T, *metadata]` form (empty for plain types).
+
+    `tp` is intentionally `Any`: annotation forms are not ordinary `type`s."""
+    args = typing.get_args(tp)
+    if not args:
+        return ()
+    return tuple(args[1:])
+
+
+def from_sidecar(cls: type, *, attr: str, inherit: bool = True) -> tuple[Capability, ...]:
+    """Return capabilities stored under `attr` on a class. Reflection-free (`vars` + `__mro__`).
+
+    With `inherit=True` (default) the attribute is resolved along the MRO — the nearest class that
+    defines it wins, so a subclass inherits a base's capabilities. With `inherit=False` only
+    `cls`'s own body is read; bases are ignored. Either way, a missing attribute yields `()`."""
+    if inherit:
+        for klass in cls.__mro__:
+            found = vars(klass).get(attr)
+            if found is not None:
+                return tuple(found)
+        return ()
+    own = vars(cls).get(attr)
+    return tuple(own) if own is not None else ()
+
+
+__all__ = ("from_annotated", "from_sidecar")

capability/_compiler.py

@@ -0,0 +1,80 @@
+"""The compiler algebra — compose `Phase`s and run them over one description in a single pass.
+
+`Compiler` is a keyed set of phases with set-like operators (`+ - & |`). Running it folds the
+*same* item sequence through every phase once (banana-split fusion) and returns a `Bundle`.
+
+`Bundle.get(phase)` is typed: it returns the phase's own context type `C`. The heterogeneous
+storage is the one place the package keeps an explicit `typing.Any` (a heterogeneous typed map
+cannot be expressed otherwise in Python) — it is quarantined here and never leaks: callers only
+ever touch the typed `get`.
+"""
+
+import dataclasses
+import typing
+from collections.abc import Iterable
+
+from capability._phase import Phase
+
+
+def _key[Cap](phase: Phase[Cap, typing.Any]) -> str:
+    return phase.name or f"@{id(phase)}"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Bundle[Cap]:
+    """The result of running a `Compiler`: each phase's context, retrievable by the phase.
+
+    Access is type-safe via `get`; the internal store is heterogeneous by necessity."""
+
+    entries: tuple[tuple[Phase[Cap, typing.Any], typing.Any], ...]
+
+    def get[C](self, phase: Phase[Cap, C]) -> C:
+        """Return the context this `phase` produced. Keyed the same way as the compiler algebra —
+        by `phase.name` (or by identity for anonymous phases) — so an equivalently-named phase
+        resolves to the same entry instead of a surprising `KeyError`."""
+        wanted = _key(phase)
+        for stored, value in self.entries:
+            if _key(stored) == wanted:
+                return value
+        raise KeyError(wanted)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Compiler[Cap]:
+    """A composable, keyed set of phases. Operators key phases by `Phase.name` (anonymous
+    phases key by identity), giving an idempotent semilattice over phase sets."""
+
+    phases: tuple[Phase[Cap, typing.Any], ...] = ()
+
+    def run(self, items: Iterable[Cap]) -> Bundle[Cap]:
+        """Fold one materialised item sequence through every phase, once each."""
+        seq = tuple(items)
+        return Bundle(tuple((phase, phase.run(seq)) for phase in self.phases))
+
+    def __add__(self, other: "Compiler[Cap] | Phase[Cap, typing.Any]") -> "Compiler[Cap]":
+        """Left-biased union. Idempotent (`A + A == A`): phases already present win."""
+        added = other.phases if isinstance(other, Compiler) else (other,)
+        seen = {_key(phase) for phase in self.phases}
+        extra = tuple(phase for phase in added if _key(phase) not in seen)
+        return Compiler((*self.phases, *extra))
+
+    def __sub__(self, other: "Compiler[Cap]") -> "Compiler[Cap]":
+        """Restriction: drop phases whose key appears in `other`."""
+        drop = {_key(phase) for phase in other.phases}
+        return Compiler(tuple(phase for phase in self.phases if _key(phase) not in drop))
+
+    def __and__(self, other: "Compiler[Cap]") -> "Compiler[Cap]":
+        """Intersection: keep only phases whose key appears in both."""
+        keep = {_key(phase) for phase in other.phases}
+        return Compiler(tuple(phase for phase in self.phases if _key(phase) in keep))
+
+    def __or__(self, other: "Compiler[Cap]") -> "Compiler[Cap]":
+        """Right-biased merge: `other`'s phases override same-keyed phases in `self`."""
+        override = {_key(phase): phase for phase in other.phases}
+        merged = tuple(override.get(_key(phase), phase) for phase in self.phases)
+        present = {_key(phase) for phase in self.phases}
+        extra = tuple(phase for phase in other.phases if _key(phase) not in present)
+        return Compiler((*merged, *extra))
+
+
+__all__ = ("Bundle", "Compiler")

capability/_core.py

@@ -0,0 +1,76 @@
+"""The substrate: the `fold` primitive, the `Step`/`AsyncStep` policies, the `Capability` marker.
+
+`fold` is a typed left-fold. It threads an immutable accumulator through a sequence of items,
+applying a *dispatch policy* to each. The policy lives entirely in the `Step` — `fold` itself
+never inspects an item, never names a target. A new target is a new `Step`, not an edit here.
+
+A `Step`/`AsyncStep` is a small frozen wrapper around the dispatch function (not a bare callable).
+Two distinct nominal types is what lets `fold` choose the sync vs async branch with an
+unambiguous `isinstance` — and you never build them by hand: use `by_protocol`/`by_table`/`chain`.
+
+`fold` is `@overload`-ed: a sync `Step` returns the final context; an `AsyncStep` makes `fold`
+return a coroutine. `afold` is a literal alias of `fold` for readers who prefer `await afold(...)`.
+"""
+
+import dataclasses
+import typing
+from collections.abc import Awaitable, Callable, Coroutine, Iterable
+
+
+@typing.runtime_checkable
+class Capability(typing.Protocol):
+    """The universal item marker — an *empty* protocol, so structurally **anything** is a
+    `Capability`. It gives the dispatch combinators a pyrules-clean "any item" type (instead of
+    `object`) while preserving the open-world rule: a capability need not inherit anything; it
+    merely needs some `Step` that knows how to apply it."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Step[Cap, C]:
+    """A sync dispatch policy: wraps `fn(item, ctx) -> ctx`. Built by `by_protocol`/`by_table`/
+    `chain`; consumed by `fold`. A policy that does not recognise an item returns the context
+    unchanged (the open-world skip)."""
+
+    fn: Callable[[Cap, C], C]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class AsyncStep[Cap, C]:
+    """An async dispatch policy: wraps `fn(item, ctx) -> Awaitable[ctx]`. Built by passing an
+    `async def` apply to `by_protocol`; consumed by `fold`/`afold` (which return a coroutine).
+    Disjoint from `Step` so `fold` can branch on `isinstance` with no type ambiguity."""
+
+    fn: Callable[[Cap, C], Awaitable[C]]
+
+
+async def _afold[Cap, C](items: Iterable[Cap], initial: C, step: AsyncStep[Cap, C]) -> C:
+    ctx = initial
+    for item in items:
+        ctx = await step.fn(item, ctx)
+    return ctx
+
+
+@typing.overload
+def fold[Cap, C](
+    items: Iterable[Cap], initial: C, step: AsyncStep[Cap, C]
+) -> Coroutine[typing.Any, typing.Any, C]: ...
+@typing.overload
+def fold[Cap, C](items: Iterable[Cap], initial: C, step: Step[Cap, C]) -> C: ...
+def fold[Cap, C](
+    items: Iterable[Cap], initial: C, step: Step[Cap, C] | AsyncStep[Cap, C]
+) -> C | Coroutine[typing.Any, typing.Any, C]:
+    """Thread `initial` through `items` left-to-right with `step`. Order-dependent, total,
+    reflection-free. Returns the final context for a sync step, or a coroutine for an async one."""
+    if isinstance(step, AsyncStep):
+        return _afold(items, initial, step)
+    ctx = initial
+    for item in items:
+        ctx = step.fn(item, ctx)
+    return ctx
+
+
+afold = fold
+"""Alias of `fold`. Identical overloaded behaviour; reads better as `await afold(...)`."""
+
+
+__all__ = ("AsyncStep", "Capability", "Step", "afold", "fold")

capability/_dispatch.py

@@ -0,0 +1,95 @@
+"""Dispatch combinators — the typed, reflection-free way to build a `Step`.
+
+The library does not pick a side of the Expression Problem; it hands you both directions:
+
+- `by_protocol` is open **on the data side** — add a new capability that implements the
+  protocol and existing folds pick it up. (Use when capabilities proliferate.)
+- `by_table` is open **on the interpreter side** — add a new fold with its own handler
+  table. (Use when targets proliferate.)
+- `chain` runs several policies on one fold pass (keep them the same item type — see `chain`).
+
+`by_protocol` is `@overload`-ed: a sync `apply` yields a `Step`; an async `apply` (an
+`async def`) yields an `AsyncStep` (for `fold`/`afold`). One name, both worlds. None of this
+uses `getattr` or string-dispatch — if you want name-driven dispatch, see `capability.reflect`.
+"""
+
+import inspect
+import typing
+from collections.abc import Awaitable, Callable, Mapping
+
+from capability._core import AsyncStep, Capability, Step
+
+type Table[Cap, C] = Mapping[type[Cap], Callable[[Cap, C], C]]
+"""A handler table for `by_table`: maps an exact capability class to its handler."""
+
+
+@typing.overload
+def by_protocol[P, C](
+    proto: type[P], apply: Callable[[P, C], Awaitable[C]]
+) -> AsyncStep[Capability, C]: ...
+@typing.overload
+def by_protocol[P, C](proto: type[P], apply: Callable[[P, C], C]) -> Step[Capability, C]: ...
+def by_protocol[P, C](
+    proto: type[P], apply: Callable[[P, C], C | Awaitable[C]]
+) -> Step[Capability, C] | AsyncStep[Capability, C]:
+    """Apply `apply(item, ctx)` to items that are instances of `proto`; skip the rest.
+
+    `proto` must be `@runtime_checkable`. Note its runtime cost: `isinstance` against a
+    runtime-checkable Protocol matches on **method-name presence**, not signatures — so the typed
+    `apply` (`lambda c, ctx: c.compile_x(ctx)`) is what gives you the real, signature-checked
+    dispatch at the call site. For async, pass an `async def` apply; the returned `AsyncStep` is
+    consumed by `fold`/`afold`."""
+    if inspect.iscoroutinefunction(apply):
+
+        async def afn(item: Capability, ctx: C) -> C:
+            if isinstance(item, proto):
+                return await apply(item, ctx)
+            return ctx
+
+        return AsyncStep(afn)
+
+    def fn(item: Capability, ctx: C) -> C:
+        if isinstance(item, proto):
+            produced = apply(item, ctx)
+            if isinstance(produced, Awaitable):
+                raise TypeError(
+                    "async apply must be an 'async def', not a coroutine-returning lambda"
+                )
+            return produced
+        return ctx
+
+    return Step(fn)
+
+
+def by_table[Cap, C](table: Table[Cap, C]) -> Step[Cap, C]:
+    """Apply the handler registered for an item's exact class; skip items with no entry.
+
+    Keyed by exact `type(item)` (not `isinstance`), so a handler for a base class does not
+    fire for subclasses — that is what makes the interpreter side independently extensible."""
+
+    def fn(item: Cap, ctx: C) -> C:
+        handler = table.get(type(item))
+        if handler is not None:
+            return handler(item, ctx)
+        return ctx
+
+    return Step(fn)
+
+
+def chain[Cap, C](*steps: Step[Cap, C]) -> Step[Cap, C]:
+    """Compose dispatch policies on one fold pass: apply each `step` to every item, left to right.
+    Use to run several `by_protocol` policies over the same context in a single traversal.
+
+    `Step` is invariant in its item type, so chaining a `by_protocol` (`Step[Capability, C]`) with a
+    narrower `by_table` step won't type-check under strict mode — keep chained steps homogeneous,
+    or build the table as `by_table[Capability, C](...)` (handlers over `Capability`) to mix."""
+
+    def fn(item: Cap, ctx: C) -> C:
+        for inner in steps:
+            ctx = inner.fn(item, ctx)
+        return ctx
+
+    return Step(fn)
+
+
+__all__ = ("Table", "by_protocol", "by_table", "chain")

capability/_folds.py

@@ -0,0 +1,56 @@
+"""Extra fold shapes — cheap variants of the core left `fold`.
+
+The core `fold` (in `_core`) is the canonical left fold: the catamorphism over a flat list.
+These are the neighbours you occasionally want — a right fold, a scan that keeps every
+intermediate context, and the tree catamorphism for recursive descriptions. All are small,
+sync, reflection-free, and read a `Step`'s `.fn` directly.
+"""
+
+from collections.abc import Callable, Iterable
+
+from capability._core import Step
+
+
+def rfold[Cap, C](items: Iterable[Cap], initial: C, step: Step[Cap, C]) -> C:
+    """Right fold: apply `step` to items last-to-first. Equals `fold(reversed(items), ...)`.
+
+    Materialises `items` (needs to walk them in reverse). Use when the natural accumulation runs
+    from the tail — e.g. building a nested wrapper chain outermost-last."""
+    ctx = initial
+    for item in reversed(tuple(items)):
+        ctx = step.fn(item, ctx)
+    return ctx
+
+
+def scan[Cap, C](items: Iterable[Cap], initial: C, step: Step[Cap, C]) -> tuple[C, ...]:
+    """Left scan: every intermediate context, starting with `initial`.
+
+    `scan(xs, init, step)[0] == init`, `scan(...)[-1] == fold(xs, init, step)`, and the length is
+    `len(xs) + 1`. Handy for visualising how a fold evolves, or for incremental/streaming use."""
+    states: list[C] = [initial]
+    ctx = initial
+    for item in items:
+        ctx = step.fn(item, ctx)
+        states.append(ctx)
+    return tuple(states)
+
+
+type Children[N] = Callable[[N], Iterable[N]]
+"""Given a node, yield its child nodes."""
+
+type TreeStep[N, R] = Callable[[N, tuple[R, ...]], R]
+"""Given a node and its already-folded children, produce this node's result."""
+
+
+def fold_tree[N, R](root: N, children: Children[N], step: TreeStep[N, R]) -> R:
+    """Bottom-up catamorphism over a tree: children are folded before their parent. Use it when
+    descriptions are recursive (an expression / query AST) rather than a flat capability tuple."""
+
+    def go(node: N) -> R:
+        folded = tuple(go(child) for child in children(node))
+        return step(node, folded)
+
+    return go(root)
+
+
+__all__ = ("Children", "TreeStep", "fold_tree", "rfold", "scan")

capability/_phase.py

@@ -0,0 +1,29 @@
+"""`Phase` — a reified target: a context factory plus the `Step` that fills it.
+
+A `Phase` is the answer to "what does it mean to compile these capabilities into *this*
+output?" One immutable description (a tuple of capabilities) run through different phases
+yields different, independent results — the "one description, many targets" property.
+"""
+
+import dataclasses
+from collections.abc import Callable, Iterable
+
+from capability._core import Step, fold
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Phase[Cap, C]:
+    """A named fold target: `initial()` seeds the accumulator, `step` is the dispatch policy.
+
+    `name` is used only by the compiler algebra (as the merge key) and by `explain`."""
+
+    initial: Callable[[], C]
+    step: Step[Cap, C]
+    name: str = ""
+
+    def run(self, items: Iterable[Cap]) -> C:
+        """Fold `items` through this phase, returning the accumulated context."""
+        return fold(items, self.initial(), self.step)
+
+
+__all__ = ("Phase",)

capability/_trace.py

@@ -0,0 +1,51 @@
+"""Inspectability — `traced_fold` records every step; `explain` renders it.
+
+Because capabilities and contexts are immutable, "did this step change the context?" is a
+cheap identity check (`before is not after`) — no defensive copies. Tracing is a separate
+function so the hot `fold` path stays branch-free and zero-cost when you do not need it.
+"""
+
+import dataclasses
+from collections.abc import Iterable
+
+from capability._core import Step
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class FoldStep:
+    """One recorded fold step: the item's type name and whether it changed the context."""
+
+    item_type: str
+    changed: bool
+
+
+@dataclasses.dataclass(slots=True)
+class Trace:
+    """A per-call sink for `FoldStep`s. An instance, not module state — pass a fresh one in."""
+
+    steps: list[FoldStep] = dataclasses.field(default_factory=list[FoldStep])
+
+    def record(self, item_type: str, changed: bool) -> None:
+        self.steps.append(FoldStep(item_type, changed))
+
+
+def traced_fold[Cap, C](items: Iterable[Cap], initial: C, step: Step[Cap, C], trace: Trace) -> C:
+    """Like sync `fold`, but append a `FoldStep` to `trace` for each item."""
+    ctx = initial
+    for item in items:
+        before = ctx
+        ctx = step.fn(item, ctx)
+        trace.record(type(item).__qualname__, before is not ctx)
+    return ctx
+
+
+def explain(trace: Trace) -> str:
+    """Render a trace as human-readable lines: which items changed the context, which skipped."""
+    lines = [
+        f"  {fold_step.item_type}: {'changed' if fold_step.changed else 'skipped'}"
+        for fold_step in trace.steps
+    ]
+    return "\n".join(lines)
+
+
+__all__ = ("FoldStep", "Trace", "explain", "traced_fold")

capability/reflect.py

@@ -0,0 +1,34 @@
+"""Name-based dispatch — a legitimate alternative to `by_protocol`.
+
+Dispatch by a method *name* resolved at runtime: any item exposing a method called `method`
+(found by walking the MRO and reading each class `__dict__` via `vars`) gets it applied; the rest
+are skipped. Free of `getattr`, so it stays lint-clean — but name-driven, so the method's
+signature is not checked. The *recommended* path remains `capability.by_protocol` with a typed
+`apply`; reach here when name dispatch is what you want.
+"""
+
+from collections.abc import Callable
+
+from capability._core import Capability, Step
+
+
+def by_method[C](method: str, _context: type[C]) -> Step[Capability, C]:
+    """Apply `item.<method>(ctx)` to items exposing `method`; skip the rest.
+
+    Looks the method up along the item's MRO via `vars` (no `getattr`) and calls it unbound.
+    `_context` is a type-only witness that pins the accumulator type `C` (name dispatch cannot
+    infer it). Unchecked by design: the method's signature is not verified. Prefer
+    `capability.by_protocol` when you can express the call as a typed `apply` lambda."""
+
+    def fn(item: Capability, ctx: C) -> C:
+        for klass in type(item).__mro__:
+            found = vars(klass).get(method)
+            if found is not None:
+                bound: Callable[[Capability, C], C] = found
+                return bound(item, ctx)
+        return ctx
+
+    return Step(fn)
+
+
+__all__ = ("by_method",)

capability-1.0.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: capability
+Version: 1.0.0
+Summary: Type-safe composable primitives.
+Project-URL: Homepage, https://github.com/prostomarkeloff/capability
+Project-URL: Repository, https://github.com/prostomarkeloff/capability
+Project-URL: Issues, https://github.com/prostomarkeloff/capability/issues
+Author: prostomarkeloff
+License-Expression: MIT
+License-File: LICENSE
+Keywords: capabilities,catamorphism,compiler,defunctionalization,dispatch,expression-problem,fold,visitor
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# capability
+
+**Type-safe composable primitives.**
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
+[![Types: pyright strict](https://img.shields.io/badge/types-pyright%20strict-blue)](https://github.com/microsoft/pyright)
+[![Dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](#correctness)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+Every time you turn a structure into outputs — validate it, document it, compile it to SQL, lint
+it — you hand-write the same machinery: an `if isinstance(...)` ladder, a visitor class, a registry
+keyed by type. It is bespoke each time. It does not compose — you can't add a case from outside, or
+run two passes in one traversal, without rewiring it. And the type checker can't see through the
+dispatch, so a missing case is a runtime surprise, not a red squiggle.
+
+A stateless coding agent makes it sharper: it re-derives that machinery from a few thousand lines of
+context, gets one case wrong, and the dispatch hides the gap.
+
+`capability` is the handful of primitives that machinery reduces to: a **fold** over
+**self-describing values**, typed end to end. The values carry their own behaviour; a fold runs
+them; and they compose — a new value, a new pass, a new target are each an addition, never an edit
+to the core.
+
+```bash
+uv add capability        # zero dependencies, stdlib only
+```
+
+## The primitives
+
+A *capability* is a frozen value that carries its own contribution to a typed context. A *fold*
+threads a context through a sequence of them, dispatching to each by an `isinstance` check against a
+protocol — a value that doesn't speak a target's protocol is skipped. Three targets here: a
+request-time validator, a database column, a block of help text.
+
+```python
+from dataclasses import dataclass, replace
+from typing import Protocol, runtime_checkable
+
+from capability import Phase, by_protocol
+
+
+@dataclass(frozen=True, slots=True)
+class Rule:  # a request-time validator
+    max_len: int | None = None
+
+
+@runtime_checkable
+class Validated(Protocol):
+    def validate(self, ctx: Rule) -> Rule: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Ddl:  # a database column
+    column: str = "TEXT"
+
+
+@runtime_checkable
+class Stored(Protocol):
+    def ddl(self, ctx: Ddl) -> Ddl: ...
+
+
+@dataclass(frozen=True, slots=True)
+class Doc:  # help lines, accumulated
+    lines: tuple[str, ...] = ()
+
+
+@runtime_checkable
+class Documented(Protocol):
+    def doc(self, ctx: Doc) -> Doc: ...
+
+
+# Each interpretation reads the context the previous fact left, and extends it.
+@dataclass(frozen=True, slots=True)
+class MaxLen:
+    n: int
+
+    def validate(self, ctx: Rule) -> Rule:
+        return replace(ctx, max_len=self.n)
+
+    def ddl(self, ctx: Ddl) -> Ddl:
+        return replace(ctx, column=f"VARCHAR({self.n})")
+
+    def doc(self, ctx: Doc) -> Doc:
+        return replace(ctx, lines=(*ctx.lines, f"at most {self.n} characters"))
+
+
+@dataclass(frozen=True, slots=True)
+class Unique:
+    def ddl(self, ctx: Ddl) -> Ddl:
+        return replace(ctx, column=f"{ctx.column} UNIQUE")
+
+    def doc(self, ctx: Doc) -> Doc:
+        return replace(ctx, lines=(*ctx.lines, "must be unique"))
+
+
+validate = Phase(Rule, by_protocol(Validated, lambda c, ctx: c.validate(ctx)))
+store = Phase(Ddl, by_protocol(Stored, lambda c, ctx: c.ddl(ctx)))
+document = Phase(Doc, by_protocol(Documented, lambda c, ctx: c.doc(ctx)))
+
+field = (MaxLen(255), Unique())
+
+validate.run(field)  # Rule(max_len=255) — Unique has no validate, skipped
+store.run(field)  # Ddl(column='VARCHAR(255) UNIQUE') — both facts fold in
+document.run(field)  # Doc(lines=('at most 255 characters', 'must be unique'))
+```
+
+Add a fact (`MinLen`, `Indexed`): it implements the protocols it has, the rest skip it. Add a
+target: a new `Phase`, no fact changes. Every piece is a small typed value, and nothing in the core
+enumerates them.
+
+It does not remove the work — `MaxLen` still spells out `validate`, `ddl`, `doc` by hand. It removes
+the *machinery*: no visitor, no registry, no dispatch ladder — and the typed `apply` keeps each call
+honest under `pyright --strict`.
+
+## Compose them
+
+`Phase`s compose into a `Compiler` — a keyed set with set-like operators that folds every phase over
+the facts in a single pass:
+
+```python
+from capability import Compiler
+
+schema = Compiler((validate, store, document))  # a composable set of phases
+bundle = schema.run(field)                       # one traversal, every phase at once
+
+bundle.get(store)     # Ddl(column='VARCHAR(255) UNIQUE')
+bundle.get(document)  # Doc(lines=('at most 255 characters', 'must be unique'))
+
+# compilers compose like sets:  a + b (union)  a - b (restrict)  a & b (intersect)  a | b (override)
+```
+
+The operators form an idempotent semilattice (`A + A == A`), so composing compilers is predictable;
+running one fuses every phase into a single traversal (banana-split). Composition is the point —
+primitives into phases, phases into compilers, compilers into each other. `Bundle.get` is typed: it
+hands back exactly the phase's own context type.
+
+## The whole engine
+
+The core primitive, with the typing stripped, is a left fold:
+
+```python
+def fold(items, initial, step):
+    ctx = initial
+    for item in items:
+        ctx = step(item, ctx)
+    return ctx
+```
+
+`fold` names no target — the meaning is all in `step`, which you build with `by_protocol` /
+`by_table` (you don't hand `fold` a bare lambda; a `Step` carries the policy and lets `fold` pick
+the sync or async path). A new target is a new `step`, not an edit. The package is nine small
+files, ~370 lines, zero dependencies.
+
+**The contexts, protocols, and targets are yours.** The core ships `fold` and the dispatch
+policies; what they compute *to* is your code.
+
+## Layers
+
+Everything past `fold` + a `Step` is a layer you can ignore until you want it.
+
+| Import | What it gives you |
+|---|---|
+| `fold`, `Step` | the primitive: a typed left fold + the dispatch-policy wrapper |
+| `by_protocol` | open on the **data** axis — a new fact that implements the protocol is picked up |
+| `by_table` | open on the **interpreter** axis — dispatch by exact `type`, a per-target handler table |
+| `chain` | run several dispatch policies in one pass |
+| `Phase` | a reified target — a context factory + its step; `Phase.run(items)` |
+| `Compiler`, `Bundle` | compose phases (`+ - & \|`) and run them in one pass; `Bundle.get(phase)` returns that phase's typed context |
+| `fold_tree` | the catamorphism for **recursive** (tree) descriptions |
+| `rfold`, `scan` | a right fold; a left scan that keeps every intermediate context |
+| `traced_fold`, `explain` | record each step and render it — free, because the data is immutable |
+| `from_annotated`, `from_sidecar` | read facts off `Annotated[T, ...]` metadata or a class sidecar |
+| `afold` | the async overload — an `async def` apply makes `fold` return a coroutine |
+| `capability.reflect.by_method` | opt-in name-driven dispatch |
+
+## You've met this before
+
+`capability` is not a new idea — it's a known one, generalised and kept as small typed data:
+
+- **`functools.singledispatch`** registers handlers externally, one function at a time, away from
+  the data. Here the interpretations live *on* the value, and one `fold` runs many at once.
+- **Pydantic's `Annotated` metadata** is this move for a single target — validation. `capability`
+  is the same, generalised to arbitrary phases with an algebra to compose them; `from_annotated`
+  reads exactly that metadata.
+- **Object algebras / tagless-final** are the typed-FP relatives. This is the *data* encoding, so
+  the program stays inspectable — you can print it, diff it, `explain` it — which a closure
+  encoding can't.
+
+## Correctness
+
+- zero dependencies, stdlib only;
+- `src/` is `pyright --strict` clean; 100% branch coverage; the `Compiler` algebra and the fold
+  laws are property-tested;
+- no `getattr` / `hasattr` in the dispatch code. To be exact about what `by_protocol` does at
+  runtime: `isinstance` against a `@runtime_checkable` Protocol, which matches on **method-name
+  presence**, not signatures — the typed `lambda c, ctx: c.validate(ctx)` is what buys the
+  call-site check. Name-driven dispatch is opt-in, in `capability.reflect`.
+
+## Lineage
+
+A capability is Reynolds' (1972) defunctionalised closure — a decision turned from code into an
+inspectable record. The hot path is a left fold; the catamorphism it instances (Meijer–Fokkinga–
+Paterson 1991, after Malcolm 1990) is `fold_tree` / `rfold`, for recursive shapes. And it keeps
+Wadler's Expression Problem open on both axes.
+
+---
+
+<div align="center">
+
+**Small, typed, composable — the rest is yours.**
+
+Made with 🧬 by [@prostomarkeloff](https://github.com/prostomarkeloff)
+
+</div>

capability-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+capability/__init__.py,sha256=MRAlmOcMJPv_Ee_6s-jAJpq7HpUZdnF23UErQpFyN94,2356
+capability/_attach.py,sha256=xDSDyrpqtaM33V7LECZgP50xz_OAPg4cDN2Zh7aWI9Y,1798
+capability/_compiler.py,sha256=MDB7VbZmDWFxefPfUD2tnV9bpzlKJSzN9TPg8P-HT70,3672
+capability/_core.py,sha256=KKVBBVwWCIe4RVixCBuPzJBrn7WeUg_xPQfONumRQOM,3210
+capability/_dispatch.py,sha256=wgs5xCC9cyb0nD9baDn01C_zGv6LsOY2XMS19ZUihF8,3920
+capability/_folds.py,sha256=jGjs15b9AKWfVl4jEcLkc7-ejuNiTYytbo9KbOiQC6U,2170
+capability/_phase.py,sha256=lc2sxHK3dhwNeL9m_YIT2-SDIqAOTaXdud3YtV5tK0g,993
+capability/_trace.py,sha256=qGuxRzEuvryHXbhv0ogFNenLDwlI96Z1fjIjtmQ376A,1702
+capability/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+capability/reflect.py,sha256=kOZs26lIty9gDbczttepY_mFQL3poYyZgeHbO9WrETU,1437
+capability-1.0.0.dist-info/METADATA,sha256=8RCjpl1midL1nN0uS_2Oce3hjhq3bqOEsj-IphnQIW8,9898
+capability-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+capability-1.0.0.dist-info/licenses/LICENSE,sha256=kBpSkOISotXfPuz4LJR2wBk9exHEgcC7BsZH7Jb73M8,1072
+capability-1.0.0.dist-info/RECORD,,

capability-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

capability-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prostomarkeloff
+
+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.