feat(core): add do-notation (Do / bind / let)

[btravers]

Implements fluent do-notation — Do().bind(name, fn).let(name, fn) — in the style of neverthrow #680, adapted to unthrown's three-channel model.

import { Do } from "unthrown";

const view = Do()
  .bind("user", () => findUser(id))               // Result<User, NotFound>
  .bind("org", ({ user }) => findOrg(user.orgId)) // Result<Org, NotFound>
  .let("label", ({ user, org }) => `${user.name} @ ${org.name}`)
  .map(({ user, org, label }) => render(user, org, label));
// Result<View, NotFound>

API

• Do() — entry point: ok({}), an empty object scope. Capitalised because do is reserved.
• bind(name, f) — f receives the scope so far and returns a Result; on Ok its value is added under name (a readonly accumulating object), on Err/Defect the chain short-circuits. Error types union (E | E2). On AsyncResult, f may return a Result or an AsyncResult (never a raw Promise — Thesis docs: sync to shipped APIs + fix format pre-commit hook #3).
• let(name, f) — the pure-value counterpart.
• It's just a Result at every step, so you can interleave map/flatMap/match/etc. To go async, lift with toAsync().

Invariants preserved

A throw in any bind/let callback becomes a Defect; Err/Defect short-circuits/passes through. Both are added to the throw→Defect and Defect-passthrough guards in invariants.spec.ts.

A note on scope

This reverses a stated exclusion — CLAUDE.md had do-notation on the "deliberately excluded" list. Per your request I've shipped the fluent form and updated the spec; the generator (gen/safeTry) style remains out of scope. The one cost: bind/let's T & {…} return type forced four casts in interop.ts (the all* family) to widen from as to as unknown as — noted in the diff.

Tests & docs

• do.spec.ts (sync + async: accumulation, short-circuit, error union, defect passthrough, throw→defect) and three types.test-d.ts assertions (scope accumulation, error union, readonly keys, async parity).
• New Do Notation guide page + sidebar; added to the method-surface list and the "Choosing a Combinator" cheatsheet; CLAUDE.md surface/invariant/facade updated; minor changeset.
• Full gate green; 100% core line/function coverage held.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds fluent do-notation to unthrown’s Result / AsyncResult surface via a new Do() entry point plus bind/let chaining methods, with accompanying tests, documentation, and a changeset.

Changes:

• Introduces Do() plus bind(name, f) and let(name, f) for sequential, scope-accumulating pipelines on both Result and AsyncResult.
• Adds runtime + type-level tests to enforce short-circuiting and invariants (throw→Defect, Defect passthrough).
• Documents the new feature and wires it into the VitePress sidebar and project spec/changeset.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/core/src/types.ts	Adds Prettify and extends the public method surface with bind/let typings.
packages/core/src/types.test-d.ts	Adds type assertions for scope accumulation, readonly keys, and async parity.
packages/core/src/invariants.spec.ts	Extends invariant tests to cover bind/let throw→Defect and Defect passthrough.
packages/core/src/interop.ts	Adjusts casts in all* helpers to accommodate widened scope typing interactions.
packages/core/src/index.ts	Exports Do from the core package entry point.
packages/core/src/facade.ts	Exposes Do on the Result companion facade for discoverability.
packages/core/src/do.ts	Implements Do() as the empty-scope seed (ok({})).
packages/core/src/do.spec.ts	Adds runtime tests for do-notation behavior (sync + async).
packages/core/src/core.ts	Implements bind/let on Result and AsyncResult runtime classes.
docs/guide/do-notation.md	Adds a new guide page explaining Do/bind/let (sync + async usage).
docs/guide/core-concepts.md	Updates method-surface overview to include do-notation.
docs/guide/choosing-a-combinator.md	Adds do-notation to the “Choosing a Combinator” cheatsheet table.
docs/.vitepress/config.ts	Adds “Do Notation” to the guide sidebar nav.
CLAUDE.md	Updates library spec/invariants and clarifies generator do-notation remains excluded.
.changeset/do-notation.md	Publishes a minor changeset describing the new API.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 52 out of 52 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

packages/effect/README.md:28

• After renaming constructors to Ok/Err, this snippet still uses ok/err in the .match(...) handlers, but those identifiers are no longer imported/defined, so the example is broken. Use explicit lambdas (or otherwise define handlers) instead of relying on the old constructor names.