[Upd4ting]

Why

A user upgrading @antelopejs/interface-database to 0.4.0 should learn from its release notes which changes break their code and how to adapt. Today the ## v0.4.0 section of CHANGELOG.md and the v0.4.0 GitHub release name #91 only as "Drop casts, thenable queries and caller-typed schema lookups". Its upgrade notes live in UPGRADING.md. The release commit (7268503) does not copy them, so this PR does, as AGENTS.md asks.

What

This adds a ### Upgrade notes block under ## v0.4.0 in CHANGELOG.md, right after the compare link, where the v0.3.0 block sits. It holds the UPGRADING.md v0.4.0 bullets verbatim, snippets included. It lists no implementer action: database modules implement nothing new, and the conformance suite in dist/tests already runs every query with run().

Pending step for Antony

I have not edited the v0.4.0 GitHub release body. Paste the text under Release notes to paste into https://github.com/AntelopeJS/interface-database/releases/tag/v0.4.0. It is the current release body with the same upgrade-notes block after the compare link.

Release notes to paste

[compare changes](https://github.com/AntelopeJS/interface-database/compare/v0.3.3...v0.4.0)

### Upgrade notes

- **A query is no longer a promise.** `Query` has no `then()`, and `QueryExecution` no longer extends `PromiseLike`. `await query` gives back the query object and sends nothing to the provider. Run a query with `run()`, or read it with `cursor()` or `for await`. A query in `Promise.all([...])`, or returned from an `async` function, is no longer run either. TypeScript rejects a query passed where a `PromiseLike` is expected, and the `typescript/await-thenable` lint rule reports `await` on a query and a query passed to `Promise.all`, `Promise.race` or another promise aggregator. The conformance suite in `dist/tests` runs every query with `run()`. A database module implements nothing new.

  ```ts
  // Before
  const adults = await users.filter((u) => u.key("age").ge(18));
  // After
  const adults = await users.filter((u) => u.key("age").ge(18)).run();
  ```

- **`cast()` returns a new object.** `Datum#cast`, `Stream#cast` and `ValueProxy#cast` return a new object with the same stages, built by the new `StagedObject` constructor form `new X(undefined, previous)`, which records no stage. `cast()` on a `Table`, a `Selection` or a `SingleSelection` returns a plain `Stream` or `Datum`, the class its type already declared. Code that compared the result with its receiver, or relied on it keeping the subclass methods at runtime, such as a table's `insert` or `getAll`, keeps the receiver instead.

  ```ts
  // Before: the same object, still a Table at runtime
  table.cast<Row>() === table; // true
  // After: a new Stream with the same stages
  table.cast<Row>() === table; // false
  table.cast<Row>().build(); // equal to table.build()
  ```

- **`Schema.get()` takes no type arguments.** The registry keeps none, so `Schema.get(id)` returns `Schema<any, unknown> | undefined`: tables hold `any` documents, and the definition is typed `unknown`. A typed lookup such as `Schema.get<{ users: User }>(id)` fails to compile (TS2558). Query typed tables through the schema object the constructor returned. On the runtime entry, `Schema.list().get(id)` returns the schema with its definition typed `SchemaDefinition`.

  ```ts
  // Before
  const schema = Schema.get<{ users: User }>("myapp")!;
  // After: export the schema you define, and import it
  export const schema = new Schema<{ users: User }>("myapp", definition);
  ```

- **The build-only `Query<T>` keeps its result type.** Loaded from `@antelopejs/interface-database/staged-query` alone, `Query<T>` now uses `T`, so `ExtractType` reads the result type of a `Datum` or a `Stream` a mapper returns, and a `Query<string>` is no longer assignable to a `Query<number>`. Code that relied on that assignment fails to compile.

  ```ts
  // Before, build-only entry: compiled, typed unknown
  const q: Query<number> = schema.createInstance(); // Query<string>
  // After: TS2322
  ```

- **`StagedObject#callfunc` checks its argument classes.** The protected method takes one or two `StagedConstructor`s, and each must build the parameter type `func` declares. A subclass that passed `ValueProxy<unknown>` for a parameter typed `ValueProxy<T>` passes `ValueProxy<T>`.

  ```ts
  // Before
  this.callfunc(mapper, Stream<T>, ValueProxy<unknown>);
  // After
  this.callfunc(
    mapper,
    Stream<T>,
    ValueProxy<K extends keyof T ? T[K] : unknown>,
  );
  ```

### 🚀 Enhancements

- **staged-query:** ⚠️  Drop casts, thenable queries and caller-typed schema lookups ([#91](https://github.com/AntelopeJS/interface-database/pull/91))

### 💅 Refactors

- **tests:** Drop the no-unused-expressions suppression ([#88](https://github.com/AntelopeJS/interface-database/pull/88))

### 📖 Documentation

- **readme:** List the mysql and postgres backends among the implementations ([#89](https://github.com/AntelopeJS/interface-database/pull/89))

### ✅ Tests

- **atomic:** Move off-contract refusal checks into an untyped spec ([#90](https://github.com/AntelopeJS/interface-database/pull/90))

### 🤖 CI

- **release:** Accept an exact release-version on dispatch ([#92](https://github.com/AntelopeJS/interface-database/pull/92))

#### ⚠️ Breaking Changes

- **staged-query:** ⚠️  Drop casts, thenable queries and caller-typed schema lookups ([#91](https://github.com/AntelopeJS/interface-database/pull/91))

### ❤️ Contributors

- Antony Rizzitelli ([@Upd4ting](http://github.com/Upd4ting))

Proof

The inserted block matches UPGRADING.md's v0.4.0 block line for line:

$ diff <(grep -v '^$' notes-from-UPGRADING.md) <(grep -v '^$' block-in-CHANGELOG.md) && echo verbatim
verbatim

CHANGELOG diff:

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bb189cc..d22fdb7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,57 @@
 
 [compare changes](https://github.com/AntelopeJS/interface-database/compare/v0.3.3...v0.4.0)
 
+### Upgrade notes
+
+- **A query is no longer a promise.** `Query` has no `then()`, and `QueryExecution` no longer extends `PromiseLike`. `await query` gives back the query object and sends nothing to the provider. Run a query with `run()`, or read it with `cursor()` or `for await`. A query in `Promise.all([...])`, or returned from an `async` function, is no longer run either. TypeScript rejects a query passed where a `PromiseLike` is expected, and the `typescript/await-thenable` lint rule reports `await` on a query and a query passed to `Promise.all`, `Promise.race` or another promise aggregator. The conformance suite in `dist/tests` runs every query with `run()`. A database module implements nothing new.
+
+  ```ts
+  // Before
+  const adults = await users.filter((u) => u.key("age").ge(18));
+  // After
+  const adults = await users.filter((u) => u.key("age").ge(18)).run();
+  ```
+
+- **`cast()` returns a new object.** `Datum#cast`, `Stream#cast` and `ValueProxy#cast` return a new object with the same stages, built by the new `StagedObject` constructor form `new X(undefined, previous)`, which records no stage. `cast()` on a `Table`, a `Selection` or a `SingleSelection` returns a plain `Stream` or `Datum`, the class its type already declared. Code that compared the result with its receiver, or relied on it keeping the subclass methods at runtime, such as a table's `insert` or `getAll`, keeps the receiver instead.
+
+  ```ts
+  // Before: the same object, still a Table at runtime
+  table.cast<Row>() === table; // true
+  // After: a new Stream with the same stages
+  table.cast<Row>() === table; // false
+  table.cast<Row>().build(); // equal to table.build()
+  ```
+
+- **`Schema.get()` takes no type arguments.** The registry keeps none, so `Schema.get(id)` returns `Schema<any, unknown> | undefined`: tables hold `any` documents, and the definition is typed `unknown`. A typed lookup such as `Schema.get<{ users: User }>(id)` fails to compile (TS2558). Query typed tables through the schema object the constructor returned. On the runtime entry, `Schema.list().get(id)` returns the schema with its definition typed `SchemaDefinition`.
+
+  ```ts
+  // Before
+  const schema = Schema.get<{ users: User }>("myapp")!;
+  // After: export the schema you define, and import it
+  export const schema = new Schema<{ users: User }>("myapp", definition);
+  ```
+
+- **The build-only `Query<T>` keeps its result type.** Loaded from `@antelopejs/interface-database/staged-query` alone, `Query<T>` now uses `T`, so `ExtractType` reads the result type of a `Datum` or a `Stream` a mapper returns, and a `Query<string>` is no longer assignable to a `Query<number>`. Code that relied on that assignment fails to compile.
+
+  ```ts
+  // Before, build-only entry: compiled, typed unknown
+  const q: Query<number> = schema.createInstance(); // Query<string>
+  // After: TS2322
+  ```
+
+- **`StagedObject#callfunc` checks its argument classes.** The protected method takes one or two `StagedConstructor`s, and each must build the parameter type `func` declares. A subclass that passed `ValueProxy<unknown>` for a parameter typed `ValueProxy<T>` passes `ValueProxy<T>`.
+
+  ```ts
+  // Before
+  this.callfunc(mapper, Stream<T>, ValueProxy<unknown>);
+  // After
+  this.callfunc(
+    mapper,
+    Stream<T>,
+    ValueProxy<K extends keyof T ? T[K] : unknown>,
+  );
+  ```
+
 ### 🚀 Enhancements
 
 - **staged-query:** ⚠️  Drop casts, thenable queries and caller-typed schema lookups ([#91](https://github.com/AntelopeJS/interface-database/pull/91))

pnpm run checks:

Checks: 11 passed, 0 failed.

The CI docs check reads only README.md and docs/, so this PR does not change its inputs.