fix(core): fail-fast Defect when bind/let gets a non-object scope

bind/let live on the general Result surface, so a primitive Ok (e.g.
Ok(5).bind(...)) could reach the scope merge and `{ ...5 }` would
silently collapse to `{}`, dropping the prior scope. Route the merge
through a `scopeOf` guard that throws on a non-object value; the
surrounding try turns it into a Defect — misuse surfaced as the bug it
is, not a silent drop. Covers sync + async bind/let. A `this: object`
constraint was rejected: TS does not hard-enforce a constraint inferred
solely from `this`, and it breaks `AsyncRes implements AsyncResult`.

Also fix two doc snippets to import the constructors they use
(do-notation `Ok`, index `Defect`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: btravers

docs/guide/do-notation.md

@@ -39,6 +39,8 @@ the normal surface, so you can mix in `map`, `flatMap`, `match`, and the rest
 freely, and a thrown callback still becomes a `Defect`:
 
 ```ts
+import { Do, Ok } from "unthrown";
+
 Do()
   .bind("n", () => Ok(2))
   .let("doubled", ({ n }) => n * 2)

docs/index.md

@@ -39,7 +39,7 @@ features:
 ## At a glance
 
 ```ts
-import { Ok, Err, fromPromise, type Result } from "unthrown";
+import { Ok, Err, Defect, fromPromise, type Result } from "unthrown";
 
 class NotFound extends TaggedError("NotFound") {}
 

packages/core/src/core.ts

@@ -99,7 +99,7 @@ class Res<T, E> {
       if (r.tag !== "Ok") return passThrough(r);
       // The merged scope can't be spelled at the type level (a computed key
       // widens to an index signature), so the constructed Ok is cast to `Bound`.
-      return okRes({ ...(this.value as object), [name]: r.value }) as unknown as Result<
+      return okRes({ ...scopeOf(this.value), [name]: r.value }) as unknown as Result<
         Bound<T, K, U>,
         E | E2
       >;
@@ -115,7 +115,7 @@ class Res<T, E> {
   ): Result<Bound<T, K, U>, E> {
     if (this.tag !== "Ok") return passThrough(this);
     try {
-      return okRes({ ...(this.value as object), [name]: f(this.value) }) as unknown as Result<
+      return okRes({ ...scopeOf(this.value), [name]: f(this.value) }) as unknown as Result<
         Bound<T, K, U>,
         E
       >;
@@ -321,6 +321,31 @@ function passThrough<T, E>(self: Result<unknown, unknown>): Result<T, E> {
   return self as unknown as Result<T, E>;
 }
 
+/**
+ * Validate that a `bind`/`let` scope is a real (non-null) object before merging a
+ * key into it.
+ *
+ * @remarks
+ * Do-notation accumulates an **object** scope: a chain starts at `Do()` (an
+ * empty object) and every `bind`/`let` returns an object, so in typed code the
+ * scope is always an object. The method lives on the general `Result` surface,
+ * though, so a primitive `Ok` (e.g. `Ok(5).bind(...)`, or a chain whose value was
+ * `map`-ped away from its scope) could reach it. Rather than let `{ ...5 }`
+ * silently collapse to `{}` and drop the prior scope, we throw here — the
+ * surrounding `try` turns it into a {@link Defect}, surfacing the misuse as the
+ * bug it is (a defect is a bug, not an absent value). A `this: object` constraint
+ * was rejected: TypeScript does not hard-enforce a constraint inferred solely
+ * from `this`, and it breaks `AsyncRes implements AsyncResult`.
+ *
+ * @internal
+ */
+function scopeOf(value: unknown): object {
+  if (typeof value !== "object" || value === null) {
+    throw new TypeError("bind/let requires an object scope — start a do-chain with Do()");
+  }
+  return value;
+}
+
 /**
  * The sole runtime implementation of {@link AsyncResult}: wraps a
  * `Promise<Result>` constructed never to reject. Operates on the public `Result`
@@ -406,7 +431,7 @@ export class AsyncRes<T, E> implements AsyncResult<T, E> {
         try {
           const inner = await f(r.value);
           if (inner.tag !== "Ok") return passThrough(inner);
-          return okRes({ ...(r.value as object), [name]: inner.value }) as unknown as Result<
+          return okRes({ ...scopeOf(r.value), [name]: inner.value }) as unknown as Result<
             Bound<T, K, U>,
             E | E2
           >;
@@ -422,7 +447,7 @@ export class AsyncRes<T, E> implements AsyncResult<T, E> {
       this.promise.then((r) => {
         if (r.tag !== "Ok") return passThrough(r);
         try {
-          return okRes({ ...(r.value as object), [name]: f(r.value) }) as unknown as Result<
+          return okRes({ ...scopeOf(r.value), [name]: f(r.value) }) as unknown as Result<
             Bound<T, K, U>,
             E
           >;

packages/core/src/do.spec.ts

@@ -62,6 +62,21 @@ describe("Do / bind / let", () => {
         .isDefect(),
     ).toBe(true);
   });
+
+  it("turns bind/let on a non-object scope into a Defect (misuse, not a silent drop)", () => {
+    // `bind`/`let` live on the general surface; calling them on a primitive `Ok`
+    // would otherwise spread `{ ...5 }` into `{}` and silently drop the value.
+    expect(
+      Ok(5)
+        .bind("a", () => Ok(1))
+        .isDefect(),
+    ).toBe(true);
+    expect(
+      Ok(5)
+        .let("a", () => 1)
+        .isDefect(),
+    ).toBe(true);
+  });
 });
 
 describe("Do / bind / let — async", () => {
@@ -97,4 +112,16 @@ describe("Do / bind / let — async", () => {
       });
     expect(fromLet.isDefect()).toBe(true);
   });
+
+  it("turns an async bind/let on a non-object scope into a Defect", async () => {
+    const fromBind = await Ok(5)
+      .toAsync()
+      .bind("a", () => Ok(1));
+    expect(fromBind.isDefect()).toBe(true);
+
+    const fromLet = await Ok(5)
+      .toAsync()
+      .let("a", () => 1);
+    expect(fromLet.isDefect()).toBe(true);
+  });
 });

packages/core/src/types.ts

@@ -84,7 +84,9 @@ export type ResultMethods<T, E> = {
    * step. `f` receives the scope accumulated so far and returns a `Result`; on
    * `Ok` the value is added as `{ ...scope, [name]: value }`, on `Err`/`Defect`
    * the chain short-circuits. Errors union (`E | E2`). A throw becomes a
-   * `Defect`. (`let` is the pure-value counterpart.)
+   * `Defect` — as does calling `bind` on a non-object scope (e.g. `Ok(5).bind`),
+   * which is misuse: the scope is always an object inside a real `Do()` chain.
+   * (`let` is the pure-value counterpart.)
    *
    * @typeParam K - the key the bound value is stored under.
    * @typeParam U - the bound value type.