snekok 0.1.0__tar.gz

snekok-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: snekok
+Version: 0.1.0
+Summary: Small, typed tools for treating expected failures as values
+Requires-Python: >=3.14
+Requires-Dist: annotated-types>=0.7.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: typing-extensions>=4.15.0
+Description-Content-Type: text/markdown
+
+# snekok
+
+Small, typed tools for treating expected failures as values in Python.
+
+```python
+from snekok.result import Err, Ok, Result
+
+
+def parse_port(raw: str) -> Result[int, str]:
+    if raw.isdecimal():
+        return Ok(int(raw))
+    return Err("port must be an integer")
+
+
+port = parse_port("8080")
+if isinstance(port, Err):
+    print(port.error)
+else:
+    print(port.unwrap())
+```
+
+The `Result` API deliberately stays small: `Ok`, `Err`, `Result`, `unwrap`,
+`unwrap_error`, and the `map`, `map_error`, `and_then`, and `and_then_async`
+composition methods required by concrete consumers. It does not attempt to provide a
+functional-programming framework.
+
+## Validated scalar aliases
+
+`NonEmptySecretStr`, `NonEmptyStr`, and `NonNegativeInt` are constrained nominal
+aliases with Pydantic support:
+
+```python
+from pydantic import BaseModel
+
+from snekok.types import NonEmptySecretStr, NonEmptyStr, NonNegativeInt
+from snekok.validation import validate_python
+
+
+class ApiSettings(BaseModel):
+    api_key: NonEmptySecretStr
+
+
+label = validate_python(NonEmptyStr, "hello").unwrap()
+retry_count = validate_python(NonNegativeInt, 0).unwrap()
+settings = ApiSettings.model_validate({"api_key": "secret-value"})
+assert settings.api_key.get_secret_value() == "secret-value"
+```
+
+Pydantic rejects an empty value. Static type checkers also reject an ordinary
+`SecretStr` where `NonEmptySecretStr` is required, preventing unvalidated secrets
+from crossing the typed boundary.
+
+See [`docs/result.md`](docs/result.md) for the Result contract. Pinned design references
+for `dmmulroy/better-result` and `dry-python/returns` live in
+[`docs/research/`](docs/research/).

snekok-0.1.0/README.md

@@ -0,0 +1,55 @@
+# snekok
+
+Small, typed tools for treating expected failures as values in Python.
+
+```python
+from snekok.result import Err, Ok, Result
+
+
+def parse_port(raw: str) -> Result[int, str]:
+    if raw.isdecimal():
+        return Ok(int(raw))
+    return Err("port must be an integer")
+
+
+port = parse_port("8080")
+if isinstance(port, Err):
+    print(port.error)
+else:
+    print(port.unwrap())
+```
+
+The `Result` API deliberately stays small: `Ok`, `Err`, `Result`, `unwrap`,
+`unwrap_error`, and the `map`, `map_error`, `and_then`, and `and_then_async`
+composition methods required by concrete consumers. It does not attempt to provide a
+functional-programming framework.
+
+## Validated scalar aliases
+
+`NonEmptySecretStr`, `NonEmptyStr`, and `NonNegativeInt` are constrained nominal
+aliases with Pydantic support:
+
+```python
+from pydantic import BaseModel
+
+from snekok.types import NonEmptySecretStr, NonEmptyStr, NonNegativeInt
+from snekok.validation import validate_python
+
+
+class ApiSettings(BaseModel):
+    api_key: NonEmptySecretStr
+
+
+label = validate_python(NonEmptyStr, "hello").unwrap()
+retry_count = validate_python(NonNegativeInt, 0).unwrap()
+settings = ApiSettings.model_validate({"api_key": "secret-value"})
+assert settings.api_key.get_secret_value() == "secret-value"
+```
+
+Pydantic rejects an empty value. Static type checkers also reject an ordinary
+`SecretStr` where `NonEmptySecretStr` is required, preventing unvalidated secrets
+from crossing the typed boundary.
+
+See [`docs/result.md`](docs/result.md) for the Result contract. Pinned design references
+for `dmmulroy/better-result` and `dry-python/returns` live in
+[`docs/research/`](docs/research/).

snekok-0.1.0/docs/research/README.md

@@ -0,0 +1,40 @@
+# Result design research
+
+These notes preserve the primary-source research that informed snekok. They are
+a design reference, not snekok's public contract; the contract lives in
+[`../result.md`](../result.md).
+
+## Snapshots
+
+| Reference | Pinned source | Best used for |
+| --- | --- | --- |
+| [`dmmulroy/better-result`](better-result.md) | 3.0.1, `75d0b106` | Result algebra, typed errors, generator composition, async, and transport tradeoffs |
+| [`dry-python/returns`](returns.md) | 0.29.0, `cf5e2548` | Result algebra, typing, exception capture, pattern matching, and complexity tradeoffs |
+
+## Quick comparison
+
+| Concern | `better-result` | `returns` | Current snekok direction |
+| --- | --- | --- | --- |
+| Core shape | `Ok<T, E> | Err<T, E>` concrete classes | `Success[T]` / `Failure[E]` container | `Ok[T] | Err[E]` |
+| Expected failures | Explicit `Err`; extraction may throw | Explicit `Failure`; extraction may throw | Expected failures are values; programmer faults remain exceptions |
+| Composition | `map`, `mapError`, `andThen`, recovery, generator `yield*` | `map`, `bind`, `alt`, `lash`, pipelines | Add only operations demanded by real refactors |
+| Exception capture | Explicit adapters; callback defects become `Panic` | Explicit `safe` / `future_safe` adapters | Never catch implicitly in `map` or composition |
+| Async | Ordinary `Promise<Result>` plus helpers | Separate `FutureResult`/`IOResult` stack | Prefer async functions returning ordinary `Result` initially |
+| Typing | Conditional types and overloads; no plugin | Covariance, HKT emulation, mypy plugin | Covariant, Pyright-native types without plugins |
+| Validation | First error or partition; no accumulation type | First failure; no core accumulation type | Keep fail-fast semantics; separate validation if needed |
+| Pattern matching | Discriminant, `match`, and tagged errors | Structural matching supported | Structural matching is the initial consumption API |
+
+## Using these notes
+
+Before adding a snekok operation:
+
+1. Start from a concrete consumer refactor and its public test seam.
+2. Check how both references name and type the operation.
+3. Preserve explicit exception boundaries and ordinary Python discoverability.
+4. Prefer a small method or function over HKT, point-free, or effect-container
+   machinery.
+5. Record deliberate divergences in the relevant research note or public
+   contract.
+
+Re-check upstream before relying on implementation details: these are immutable,
+pinned snapshots, not claims about the projects' latest releases.

snekok-0.1.0/docs/research/better-result.md

@@ -0,0 +1,86 @@
+# Research: dmmulroy/better-result
+
+## Summary
+
+Primary-source baseline: **better-result 3.0.1**, released **2026-08-11**, commit **`75d0b10654370597d4cad103c5c825d5acd7d3e1`**. It is a TypeScript Result library built around `Ok<T, E> | Err<T, E>`, typed error unions, generator composition, tagged `Error` subclasses, and a strict distinction between expected failures and defects. It is ESM-only, requires TypeScript 5.4 or newer, has no runtime dependencies, and builds to 10.66 kB minified or about 3.25 kB gzip.
+
+The design is more relevant to our research than Better Auth. Better Auth showed one application's mixed exception/value boundaries. better-result is a deliberate Result API, so it gives us concrete answers about construction, composition, error typing, async work, extraction, collections, transport, and callback exceptions.
+
+Its best ideas are the small discriminated runtime shape, inferred error unions, linear generator workflows, ordinary `Promise<Result>` async functions, and tagged domain errors. Its weak points come from ambition in the type layer. The 3.0.1 declaration file is 64 kB, overloads are extensive, and four open issues document inference or callback problems in `match`, partial error matching, taps, and detached tagged-error guards. Runtime values are also mutable despite readonly TypeScript declarations.
+
+## Findings
+
+1. **[informational] The runtime model is direct and inspectable.** `Result<T, E>` is `Ok<T, E> | Err<T, E>`. Both classes expose a serializable `status` discriminant. `Ok` stores `value`; `Err` stores `error`. Callers can narrow with the discriminant, instance guards, or static guards. The second type parameter on `Ok` and first on `Err` are phantom lanes used to preserve inference through unions and generators. This is less abstract than dry-python/returns' interface and HKT stack. [`core.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/core.ts) · [mental model](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/getting-started/mental-model.mdx)
+
+2. **[informational] The core branch operations use discoverable names.** `map`, `mapError`, `andThen`, `tryRecover`, `match`, `unwrapOr`, and `unwrap` cover normal composition. Async continuations and recovery have explicit `andThenAsync` and `tryRecoverAsync` forms. Recovery can widen the success lane; chaining unions the old and new error lanes. This is easier to discover than returns' `alt` and `lash`. Most combinators exist as methods plus static data-first and data-last functions. The three calling styles are convenient, but they account for many overloads. [`core.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/core.ts) · [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [transforming and chaining](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/core/transforming-and-chaining.mdx)
+
+3. **[informational] `Result.gen` is the signature feature.** `Ok[Symbol.iterator]` returns its value without yielding. `Err[Symbol.iterator]` yields itself once. `Result.gen` advances the supplied generator once, so each `yield*` unwraps an `Ok`, while the first `Err` becomes the generator's first yielded value and ends the workflow. Conditional types collect all possible yielded errors into the final union. Tagged errors are also iterable, which makes a direct `yield* new DomainError(...)` a typed guard clause. The implementation closes a short-circuited generator so `finally`, `Symbol.dispose`, and `Symbol.asyncDispose` cleanup runs. Body and cleanup exceptions become `Panic`. This is clever, readable at call sites, and well tested. It also depends on TypeScript-specific iterator typing that does not transfer cleanly to Python type checkers. [`core.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/core.ts) · [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [generator composition](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/core/generator-composition.mdx)
+
+4. **[informational] Async stays `Promise<Result<T, E>>`.** There is no `ResultAsync`, `FutureResult`, or effect-container family. `Result.await` only adds async iterator behavior for `Result.gen`; short pipelines use static combinators through `Promise.then`. This keeps the runtime and mental model much smaller than returns' `IOResult` and `FutureResult`. The cost is some syntactic ceremony: asynchronous generator users must write `yield* Result.await(operation())`, and rejected Promises outside explicit capture are defects. [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [async docs](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/core/async-and-retries.mdx)
+
+5. **[tradeoff] Callback exceptions usually become a separate thrown defect type.** `tryOrPanic` and `tryOrPanicAsync` wrap thrown or rejected callback failures in `Panic`, preserving the original value as `cause`. This applies to transforms, chaining, recovery, observation, exhaustive matching, generators, retry callbacks, and schema validation. Expected failures remain in `E`; bugs do not silently widen it to `unknown`. One exception is `matchErrorPartial`, whose selected handler and fallback run without the wrapper; tests confirm that a fallback exception propagates unchanged. The defect policy is broad but not universal. It is also more opinionated than returns, where exceptions inside ordinary `map` and `bind` callbacks propagate normally. Wrapping changes exception identity and adds another stack layer, so callers must understand that `except OriginalError` style handling would no longer work in a Python port. [`core.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/core.ts) · [`error.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/error.ts) · [panic docs](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/errors/panic-and-defects.mdx)
+
+6. **[informational] Exception capture is explicit at operation boundaries.** `Result.try` and `Result.tryPromise` either map a caught value with a caller-provided `catch` function or return `UnhandledException`. A throwing catch mapper is itself a defect and becomes `Panic`. `Result.try` deliberately rejects Promise-returning functions at the type level. `tryPromise` also has bounded retry, typed attempt context, static or dynamic delay, three backoff modes, jitter, retry predicates, and an optional `AbortSignal`. The signal stops pending delays and later attempts; the attempted operation only stops if user code forwards the signal. Bundling retry policy into a Result constructor is practical but well beyond a minimal algebra. [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [async and retries](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/core/async-and-retries.mdx)
+
+7. **[informational] Tagged errors make domain unions pleasant.** `TaggedError("Tag")<Props>` creates an `Error` subclass with a literal `_tag`, readonly typed properties, class-specific `.is`, JSON output, exhaustive instance `.match`, and generator support. `matchError` also works with structurally tagged error unions. `matchErrorPartial` can transform selected variants and leave the others intact. Adding a variant breaks an exhaustive handler at compile time, which gives errors-as-values much of the usability usually missing in TypeScript. Identity is nominal, however: concrete `.is` uses `instanceof`, so serialized values, other realms, and duplicate class copies need an explicit reconstruction boundary. [`error.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/error.ts) · [tagged errors](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/errors/tagged-errors.mdx) · [matching errors](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/errors/matching-errors.mdx)
+
+8. **[medium] `Result.match` cannot currently infer divergent branch return types.** Its handlers share one generic return `T`, so TypeScript may infer `T` from the success branch and reject a differently shaped error branch instead of returning a union. Open issue [#111](https://github.com/dmmulroy/better-result/issues/111) has a minimal reproduction. Tagged-error matching uses a separate mapped return-union design and does not have the same limitation. This is a real ergonomic gap in the main exit operation at 3.0.1. Python overload design should avoid promising stronger inference than static checkers can deliver.
+
+9. **[medium] The concrete tagged-error guard is unsafe as a detached callback.** `SomeError.is(value)` works because the static method evaluates `value instanceof this`. Passing `SomeError.is` directly to `filter` loses `this`; TypeScript accepts it in that context and runtime throws `TypeError`. Open issue [#112](https://github.com/dmmulroy/better-result/issues/112) documents the bug and the wrapper workaround. A guard factory should return a closed-over plain function, not depend on method binding. [`error.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/error.ts)
+
+10. **[low] Pipeable helpers expose the limits of deferred generic inference.** Open issue [#110](https://github.com/dmmulroy/better-result/issues/110) shows that pipeable `matchErrorPartial` widens the fallback argument to the generic tagged-error base because the concrete union is unknown when handlers are declared. Open issue [#107](https://github.com/dmmulroy/better-result/issues/107) shows `tap` can over-narrow a later Promise pipeline without `NoInfer`, an explicit type argument, or a wrapper lambda. These are not runtime faults. They are evidence that supporting methods, data-first calls, and data-last calls with highly precise unions has a continuing maintenance cost.
+
+11. **[tradeoff] Readonly means compile-time readonly, not immutable values.** `Ok.value`, `Err.error`, and tagged-error payload fields are declared readonly, but constructors do not freeze instances. A direct runtime check against the release build showed `Object.isFrozen(Result.ok(1)) === false`, assignment through an untyped reference changed its value, and tagged errors were likewise mutable. There is also no value equality; ordinary JavaScript reference equality applies. dry-python/returns is stronger here because its containers enforce immutability and value equality. A Python Result should use frozen dataclasses or equivalent runtime enforcement if those properties are part of its contract. [`core.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/core.ts) · [`error.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/error.ts)
+
+12. **[informational] Collection helpers cover both short-circuit and full processing.** `Result.all` preserves tuple value types and returns the first input-order error. `allAsync` runs inputs concurrently, then applies the same rule. `partition` and `partitionAsync` preserve every success and error in separate ordered arrays. `flatten` joins nested error types. This is a useful small set. It does not accumulate independent validation errors into one `Err`; `partition` merely returns two arrays. Rejected raw Promises passed to async collection helpers become `Panic`. [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [collections](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/core/collections.mdx)
+
+13. **[tradeoff] Transport codecs are careful but large for a core Result package.** `Result.codec` accepts four Standard Schema validators: success and error schemas for serialization, then success and error schemas for deserialization. It validates the `{ status, value | error }` envelope, allows domain and wire types to differ, preserves synchronous or asynchronous schema behavior, and returns typed serialization errors. Unsafe forms turn schema mismatch into `Panic`. This fixes a real problem because JSON strips class prototypes and trusted types. It also contributes substantial conditional typing and ties transport policy to the Result package. A smaller library could expose the plain envelope and let schema integrations live in adapters. Tagged error `toJSON()` includes stack and serialized cause, so applications still need redaction policy when bypassing codecs. [`result.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.ts) · [`standard-schema.ts`](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/standard-schema.ts) · [codec docs](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/website/docs/serialization/result-codecs.mdx)
+
+14. **[informational] The implementation is compact at runtime and serious about type tests.** The package has no runtime dependencies. The published 3.0.1 tarball contains seven files and reports 269,124 unpacked bytes, mostly declarations, maps, and README. The minified runtime bundle is 10,665 bytes and 3,268 bytes under gzip. The release source passed strict TypeScript checks, lint, formatting, 360 Vitest tests including 46 compile-time tests, build, and a TypeScript 5.4 consumer check. Tests include monad and functor laws, property-based collection and codec checks, generator cleanup, defect wrapping, and inference regressions. [package manifest](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/package.json) · [tests](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/result.test.ts) · [error type tests](https://github.com/dmmulroy/better-result/blob/75d0b10654370597d4cad103c5c825d5acd7d3e1/src/error.test-d.ts)
+
+## Comparison with dry-python/returns
+
+| Concern | better-result 3.0.1 | returns 0.26.0 |
+| --- | --- | --- |
+| Runtime model | Two concrete classes and a union | ABC plus final Success and Failure variants |
+| Composition | Methods, dual static functions, generator `yield*` | Methods, pointfree helpers, flow/pipe, generator-comprehension `do` |
+| Error naming | `mapError`, `tryRecover` | `alt`, `lash` |
+| Async | Ordinary `Promise<Result>` plus helpers | `FutureResult`, `IOResult`, and effect-aware companions |
+| Typing support | Standard TypeScript conditional types and overloads | HKT emulation plus a mypy plugin for best inference |
+| Domain errors | Built-in tagged `Error` factory and exhaustive matching | Error payload is generic; no comparable built-in tagged-error system |
+| Callback exceptions | Wrapped and thrown as `Panic` | Ordinary callback exceptions propagate |
+| Immutability and equality | Type-level readonly; reference equality | Runtime immutable; value equality |
+| Validation accumulation | None; first error or partition | None in core; first error |
+| Boundary extras | Retry and Standard Schema codecs included | Broader effect/container family instead |
+
+better-result picks a better default vocabulary and a much smaller async model. returns has the stronger Python value semantics. Both become complicated when they try to recover precise typing for advanced composition syntax.
+
+## Lessons for an ergonomic Python Result library
+
+- Start with two frozen, value-equal variants and one obvious `Result[T, E]` union. Keep construction and narrowing plain: `Ok`, `Err`, `is_ok`, `is_err`, `value`, and `error`.
+- Use `map_error` and `or_else` or `recover` rather than mathematical names. `and_then` is established enough to keep.
+- Let async functions return `Awaitable[Result[T, E]]`. Do not add an effect-container family until a concrete use case requires it.
+- Treat linear workflow syntax as optional sugar. better-result proves its value, but Python checkers cannot infer a union of every yielded error as cleanly. Typed method chaining and `match` must work without a plugin first.
+- Keep expected domain failures separate from defects. Do not catch exceptions inside every callback by default. Either let them propagate unchanged or make defect wrapping an explicit, narrowly documented policy that preserves `__cause__`.
+- Provide a typed exception-capture adapter at I/O boundaries. Catch `Exception`, not `BaseException`, and require explicit mapping when callers need a closed domain error type.
+- Model tagged domain errors with frozen dataclasses and literal tags. Prefer guards that are plain functions. Do not rely on bound-method identity or nominal checks for deserialized values.
+- Include `all`, `partition`, and `flatten`. State clearly that ordinary composition stops on the first error. Add a separate `Validation` type only if error accumulation is required.
+- Keep transport validation and retry outside the initial core. Their policies and types can live in optional adapters without making every Result user learn them.
+- Resist offering method, data-first, data-last, pointfree, generator, and pattern APIs all at once. better-result's open typing issues are a useful warning. One excellent method API plus Python pattern matching is a better first release.
+- Make throwing extraction loud. `unwrap` should identify failed invariants, preserve the original error as cause, and stay out of routine control flow.
+
+## Sources and validation
+
+- [better-result 3.0.1 release](https://github.com/dmmulroy/better-result/releases/tag/v3.0.1), published 2026-08-11.
+- Pinned release source at commit [`75d0b10654370597d4cad103c5c825d5acd7d3e1`](https://github.com/dmmulroy/better-result/tree/75d0b10654370597d4cad103c5c825d5acd7d3e1).
+- Official source, tests, package manifest, release workflow, README, and documentation linked in the findings.
+- Current open issues were queried individually with GitHub CLI rather than inferred from source: [#107](https://github.com/dmmulroy/better-result/issues/107), [#110](https://github.com/dmmulroy/better-result/issues/110), [#111](https://github.com/dmmulroy/better-result/issues/111), and [#112](https://github.com/dmmulroy/better-result/issues/112).
+- Local validation in `/tmp/better-result-research-source`: `bun run check`, `bun run lint`, `bun run fmt:check`, `bun run test`, `bun run build`, then `bun run check:typescript-minimum`. All passed. The test run reported 360 passing tests and no type errors.
+- Published npm metadata and tarball were checked directly for package contents, dependency count, provenance metadata, and bundle sizes.
+
+## Gaps and residual risks
+
+- This report targets the latest stable npm release, not unreleased `main`. The repository's main branch was ahead of 3.0.1 when checked.
+- The four cited issues were open when checked and were created after 3.0.1. A later release may fix them.
+- Download counts and popularity were intentionally excluded from design conclusions. They do not verify API quality.
+- No broad downstream-code survey was performed. Compatibility findings come from the release's consumer test and current issue reports.

snekok-0.1.0/docs/research/returns.md

@@ -0,0 +1,233 @@
+# `dry-python/returns`: Result and functional composition
+
+Curated against `returns` **0.29.0**, commit
+[`cf5e2548`](https://github.com/dry-python/returns/tree/cf5e25485921bd02dea637e6f12c163128ba295c).
+The retained subagent report used 0.26.0; the core claims below were reconciled
+with the separately inspected 0.29.0 checkout. Re-check current upstream before
+copying signatures or implementation details.
+
+## Executive summary
+
+`returns.Result[T, E]` is an immutable, covariant, two-track container:
+
+- `Success[T]` transforms and binds on the value track;
+- `Failure[E]` preserves the failure or transforms/recovers on the error track;
+- normal composition does not catch callback exceptions;
+- extraction methods can raise `UnwrapFailedError`;
+- exception capture is explicit through decorators such as `safe`;
+- pattern matching and generator-based do-notation are supported;
+- async/effectful work uses companion containers such as `FutureResult` and
+  `IOResult`;
+- advanced HKT, decorator, and do-notation typing depends on a mypy plugin;
+- core Result composition stops at the first failure rather than accumulating
+  validation errors.
+
+The semantic rigor is valuable. The interface hierarchy, point-free mirror,
+effect-container family, and checker plugin are too much initial surface for
+snekok.
+
+## Construction and representation
+
+Callers construct explicit variants:
+
+```python
+Success(1)
+Failure("invalid")
+```
+
+`Result` itself is an abstract container rather than a public two-argument
+constructor. `Result.from_value` and `Result.from_failure` support generic
+container-oriented construction. `ResultE[T]` aliases
+`Result[T, Exception]`.
+
+Both value and error parameters are covariant. Containers are immutable,
+slotted, comparable by variant and payload, and hashable when their payload is
+hashable.
+
+Snekok keeps the explicit variant idea but uses Python-familiar `Ok` and `Err`
+and represents `Result` directly as their union.
+
+Sources: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py),
+[`container.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/primitives/container.py),
+[`types.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/primitives/types.py).
+
+## Value-track operations
+
+| Operation | Success behavior | Failure behavior |
+| --- | --- | --- |
+| `map(f)` | `Success(f(value))` | passes the failure through |
+| `bind(f)` | runs `f(value)` and flattens its Result | passes the failure through |
+| `apply(container)` | applies a wrapped function | preserves failure semantics |
+| `value_or(default)` | returns the value | returns the eager default |
+| `unwrap()` | returns the value | raises `UnwrapFailedError` |
+
+Ordinary `bind` keeps one error type. Point-free `unify` supports a function
+whose Result has another error type and widens the resulting error channel.
+
+Snekok naming candidates remain `map`, `and_then`, and `unwrap_or`. Partial
+extraction should be conspicuous and unnecessary in normal control flow.
+
+Sources: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py),
+[`unify.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/pointfree/unify.py).
+
+## Error-track operations
+
+| Operation | Failure behavior | Success behavior |
+| --- | --- | --- |
+| `alt(f)` | maps `E -> F` | passes the success through |
+| `lash(f)` | runs `E -> Result[T, F]` and flattens | passes the success through |
+| `failure()` | extracts the error | raises `UnwrapFailedError` |
+| `swap()` | moves the error to success | moves the value to failure |
+
+`alt` and `lash` are mathematically consistent with the wider library but less
+discoverable to many Python users. For snekok, `map_err` and `or_else` or
+`recover_with` are clearer candidates.
+
+Source: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py).
+
+## Exception capture
+
+`safe` wraps a synchronous function and catches `Exception` or configured
+exception classes into `Failure`. `attempt` records the function's single input
+as the failure payload instead of retaining the exception. Async equivalents,
+including `future_safe` and `future_attempt`, produce `FutureResult`.
+
+Important boundary rule: `map` and `bind` callbacks are not implicitly safe. If
+a callback raises, the exception still propagates.
+
+This is a strong precedent for snekok:
+
+- exception conversion should have an explicit name;
+- adapters should catch selected `Exception` subclasses, never control-flow
+  `BaseException` events;
+- normal transformations should not silently alter exception behavior.
+
+Sources: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py),
+[`returns/future.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/future.py).
+
+## Pattern matching
+
+Containers expose positional matching:
+
+```python
+match outcome:
+    case Success(value):
+        use(value)
+    case Failure(error):
+        handle(error)
+```
+
+This is the clearest dependency-light consumption style and directly informed
+snekok's initial API. Python itself does not universally enforce match
+exhaustiveness, so checker configuration remains part of the contract.
+
+Source: [`container.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/primitives/container.py).
+
+## Do-notation
+
+`Result.do` consumes a generator expression:
+
+```python
+Result.do(first + second for first in Success(1) for second in Success(2))
+```
+
+Success iteration yields a value. Failure iteration raises an internal unwrap
+exception that `do` catches and converts back to that failure. The first failure
+short-circuits, and the syntax supports one final yielded expression rather than
+general statement-level do-notation.
+
+The implementation is clever, but typing and maintenance costs outweigh the
+benefit for a small initial library. Method chaining and `match` are simpler.
+
+Sources: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py),
+[do-notation documentation](https://returns.readthedocs.io/en/latest/pages/do-notation.html).
+
+## Point-free pipelines and interfaces
+
+`flow(value, *functions)` executes left-to-right. `pipe(*functions)` builds a
+reusable pipeline. `returns.pointfree` mirrors container methods with curried
+helpers such as `map_`, `bind`, `alt`, `lash`, and `value_or`.
+
+Underneath, capability interfaces split mapping, binding, error mapping,
+recovery, and extraction into reusable abstractions. HKT emulation lets those
+helpers target `Result`, `IOResult`, `FutureResult`, reader containers, and
+other related types.
+
+This is useful when cross-container polymorphism is a goal. It is excessive for
+snekok until at least two real container implementations require the same
+abstraction.
+
+Sources: [`pipeline.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/pipeline.py),
+[`interfaces`](https://github.com/dry-python/returns/tree/0.29.0/returns/interfaces),
+[`pointfree`](https://github.com/dry-python/returns/tree/0.29.0/returns/pointfree).
+
+## Async and effect containers
+
+`FutureResult[T, E]` represents asynchronous computation and resolves through
+`IOResult[T, E]`, preserving that executing the computation is effectful.
+Async-aware mapping and binding bridge ordinary Results, awaitables, Futures,
+and FutureResults.
+
+This models effects precisely but creates a substantial API and learning
+surface. Snekok should initially let ordinary async functions return
+`Result[T, E]`; a separate async abstraction should require concrete composition
+pressure.
+
+Source: [`returns/future.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/future.py).
+
+## Type-checker plugin
+
+The mypy plugin supplies inference hooks for HKT emulation, decorators,
+do-notation, partial/curry helpers, and related constructs that standard mypy
+cannot represent precisely. Other checkers do not run mypy plugins.
+
+Snekok should keep signatures understandable to ordinary Pyright and standard
+PEP typing. Fewer abstractions are preferable to checker-specific magic.
+
+Sources: [plugin documentation](https://returns.readthedocs.io/en/latest/pages/contrib/mypy_plugins.html),
+[`returns_plugin.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/contrib/mypy/returns_plugin.py).
+
+## Validation semantics
+
+`bind`, do-notation, applicative application, and collection helpers preserve
+first-failure semantics. The core API has no accumulating `Validated` type,
+non-empty error collection, or semigroup-constrained combination.
+
+Snekok should not silently make ordinary Result composition accumulate errors.
+If independent validation needs every error, add a distinct abstraction or an
+explicit collection operation.
+
+Sources: [`returns/result.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/result.py),
+[`iterables.py`](https://github.com/dry-python/returns/blob/0.29.0/returns/iterables.py).
+
+## Ideas to retain or avoid
+
+Retain:
+
+- immutable value semantics and covariance;
+- explicit variants and structural matching;
+- typed mapping, binding, error mapping, and recovery when consumers need them;
+- explicit exception-boundary adapters;
+- clear first-failure semantics.
+
+Rename or simplify:
+
+- `alt` -> `map_err`;
+- `lash` -> `or_else` or `recover_with`;
+- prefer methods and IDE discovery over a full point-free mirror.
+
+Avoid initially:
+
+- HKT emulation and a capability-interface lattice;
+- a custom checker plugin;
+- do-notation;
+- `IOResult`, reader, and async container families;
+- implicit exception capture in transformations;
+- mixing accumulating validation into Result's fail-fast semantics.
+
+## Research limits
+
+- This is a pinned source snapshot; latest upstream may differ.
+- Advanced inference varies with mypy and plugin versions.
+- Recommendations are interpretation, not verified upstream behavior and not a
+  commitment to snekok's future API.

snekok-0.1.0/docs/result.md

@@ -0,0 +1,92 @@
+# Result
+
+`Result[T, E]` represents either an expected success or an expected failure:
+
+```python
+from snekok.result import Err, Ok, Result
+
+
+def read_count(raw: str) -> Result[int, str]:
+    if not raw.isdecimal():
+        return Err("count must be an integer")
+    return Ok(int(raw))
+```
+
+## Variants
+
+- `Result[T, E]` is the nominal base type shared by both variants.
+- `Ok(value)` contains a successful `T` in `.value`.
+- `Err(error)` contains a failed `E` in `.error`.
+
+Both variants are immutable, slotted value types. Each carries a phantom type
+for the absent channel, allowing transformations to preserve and widen both
+covariant channels without reconstructing an enclosing result. The nominal base
+keeps annotations and type-checker output compact.
+
+## Consumption
+
+Narrow a concrete variant when its field is needed, then unwrap the base type:
+
+```python
+outcome = read_count(raw)
+if isinstance(outcome, Err):
+    report(outcome.error)
+else:
+    consume(outcome.unwrap())
+```
+
+`unwrap()` returns `T` and raises `RuntimeError` for an `Err`. `unwrap_error()`
+returns `E` and raises `RuntimeError` for an `Ok`. Check the known variant before
+calling either method when both outcomes are expected.
+
+`Ok` and `Err` remain class-pattern compatible, but static type checkers cannot
+consider a nominal class hierarchy sealed. A `match` over `Result[T, E]` therefore
+needs a fallback case even when it handles both built-in variants.
+
+## Composition
+
+Use `map` to transform a success while preserving any error:
+
+```python
+label = read_count(raw).map(lambda count: f"count={count}")
+```
+
+Use `map_error` to translate an expected error while preserving a success:
+
+```python
+identified = read_count(raw).map_error(lambda message: ("invalid_count", message))
+```
+
+Use `and_then` to continue with another fallible operation. Existing and newly
+introduced error channels are combined:
+
+```python
+def require_positive(count: int) -> Result[int, ValueError]:
+    if count <= 0:
+        return Err(ValueError("count must be positive"))
+    return Ok(count)
+
+
+positive = read_count(raw).and_then(require_positive)
+```
+
+`and_then_async` provides the same error propagation for an asynchronous
+continuation:
+
+```python
+async def require_positive_async(count: int) -> Result[int, ValueError]:
+    return require_positive(count)
+
+
+validated = await read_count(raw).and_then_async(require_positive_async)
+```
+
+Transform callbacks are ordinary Python calls. Exceptions raised by them are not
+caught or converted into `Err` values.
+
+## Exception boundary
+
+`Result` describes expected outcomes. It does not catch exceptions implicitly.
+Programmer errors, cancellation, and broken invariants remain exceptions.
+Exception-capture helpers will be introduced only when real boundary code
+establishes their required semantics.

snekok-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "snekok"
+version = "0.1.0"
+description = "Small, typed tools for treating expected failures as values"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "annotated-types>=0.7.0",
+    "pydantic>=2.13.4",
+    "typing-extensions>=4.15.0",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.18",
+    "snektest",
+    "ty==0.0.75",
+]
+
+[tool.uv.sources]
+snektest = { url = "https://github.com/crpier/snektest/archive/b6ff08544eade05804a2fdfd894c2c854145e537.tar.gz" }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ty.rules]
+all = "error"
+missing-override-decorator = "ignore"
+
+[tool.ruff.lint]
+select = [
+    "A", "ANN", "ARG", "ASYNC", "B", "BLE", "C4", "C90", "COM", "DTZ",
+    "E", "EM", "ERA", "EXE", "F", "FBT", "FURB", "G", "I", "INP", "ISC",
+    "LOG", "N", "PERF", "PGH", "PIE", "PL", "PLE", "PLR", "PLW", "PTH",
+    "PYI", "Q", "RET", "RSE", "RUF", "S", "SIM", "SLF", "SLOT", "T10",
+    "T20", "TC", "TID", "TRY", "UP", "W",
+]
+ignore = [
+    "COM812", # Conflicts with the formatter.
+    "E501",   # The formatter handles ordinary line length.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "PLW3201", # Exercise frozen dataclass assignment through its public runtime behavior.
+]