@confect/core 9.0.0-next.0 → 9.0.0-next.10

package/CHANGELOG.md

@@ -1,5 +1,266 @@
 # @confect/core
 
+## 9.0.0-next.10
+
+### Patch Changes
+
+- 9eec71c: Generate the published `.d.ts` declarations with the TypeScript compiler instead of tsdown's declaration bundler. tsdown now emits JavaScript only (`dts: false`); each package has a composite `tsconfig.src.json`, and `tsc -b` emits the declarations into `dist/` as part of the build. (`@confect/cli` is the exception: it ships only a binary, so it emits no declarations at all.)
+
+  The emitted types are equivalent to before—same exported surface, same inferred shapes—so no consumer-facing type changes. One incidental improvement comes with the switch: declaration maps (`.d.ts.map`) now ship alongside the types (with `src/` included in the published files, so "go to definition" lands on the original source).
+
+## 9.0.0-next.9
+
+### Major Changes
+
+- 4894959: Make Node-runtime functions first-class and remove the separate `node` namespace.
+
+  A function group's runtime is now declared solely by its spec — `GroupSpec.makeNode()` for a Node action group, `GroupSpec.make()` for a Convex group — exactly like vanilla Convex's per-file `"use node"` directive. The `confect/node/` directory is no longer special: Node specs/impls are ordinary colocated `.spec.ts`/`.impl.ts` pairs that can live anywhere in `confect/`, and codegen emits the `"use node"` directive into the generated `convex/` module based on the spec. This is safe because v9's per-group registries already isolate each Convex function's bundle from every other group's impl, so Node-only code can no longer leak into a Convex-runtime bundle regardless of namespace.
+
+  ### Why
+
+  The `node` namespace existed only because the pre-v9 architecture aggregated every function's impl into one module that all generated `convex/` modules imported; Node functions had to be quarantined into a separate spec/impl/registry tree so Convex-runtime functions wouldn't transitively import Node-only code. v9's per-group isolation removed that constraint, so the namespace was no longer load-bearing — only ergonomic overhead that diverged from vanilla Convex (which identifies Node modules per-file, with no directory requirement).
+
+  ### Breaking changes
+
+  - **API namespace removed.** A Node group at `confect/email.spec.ts` is now referenced as `refs.public.email.send` instead of `refs.public.node.email.send`. Node groups are ordinary groups in the refs tree, nesting preserved like any other group.
+  - **Generated layout changed.** Node modules are emitted at `convex/<path>.ts` (carrying `"use node"`) instead of `convex/node/<path>.ts`, and their registries at `confect/_generated/registeredFunctions/<path>.ts`. The single assembled `confect/_generated/spec.ts` now contains every group regardless of runtime; `confect/_generated/nodeSpec.ts` is no longer generated (codegen deletes any stale copy on upgrade).
+  - **`@confect/core` API.** Removed `Spec.makeNode`, `Spec.merge`, and `Spec.isConvexSpec`/`Spec.isNodeSpec`. `Spec` is now a single mixed-runtime container (`Spec.make()` accepts groups of any runtime). `Refs.make(spec)` takes a single argument (the unified spec) instead of `(convexSpec, nodeSpec)`. `GroupSpec.makeNode()`/`makeNodeAt()` and `FunctionSpec.publicNodeAction()`/`internalNodeAction()` are unchanged; `GroupSpec` subgroups may now be of any runtime (a group is just a namespace for its children).
+
+  ### Migration
+
+  1. Move any `confect/node/<path>.spec.ts`/`.impl.ts` files to wherever you want them under `confect/` (e.g. `confect/<path>.spec.ts`); the `node/` directory has no special meaning anymore. Their specs already use `GroupSpec.makeNode()`, so no spec-body change is needed — only fix the impl's relative import of `_generated/schema` if its depth changed.
+  2. Update call sites to drop the `node` segment: `refs.public.node.<group>.<fn>` → `refs.public.<group>.<fn>`.
+  3. Replace `Refs.make(spec, nodeSpec)` with `Refs.make(spec)` (codegen does this for `_generated/refs.ts` automatically).
+  4. Run `confect codegen`. The `convex/` tree and `confect/_generated/` are re-emitted; the stale `_generated/nodeSpec.ts` is removed.
+
+## 9.0.0-next.8
+
+### Patch Changes
+
+- 3fec285: Import Effect from its submodule paths internally to shrink per-function cold-start bundles.
+
+  Confect's packages now import Effect modules from their submodule paths (`import * as Schema from "effect/Schema"`) instead of the `"effect"` barrel (`import { Schema } from "effect"`).
+
+  ### Why
+
+  A barrel import of a namespace re-export defeats esbuild's tree-shaking: accessing `Schema.X` from `import { Schema } from "effect"` retains the _entire_ `Schema` namespace, because the bundler can't prune property access on the barrel's `export * as Schema`. So every Convex function's cold-start bundle was pulling all of `effect/Schema` and `effect/Stream` — and, transitively through Schema's `Arbitrary`, `fast-check` — whether the function used them or not.
+
+  Importing from the submodule path tree-shakes normally. On a minimal function this cut the bundle esbuild produces by ~54% (the `effect/Schema` module alone by ~75%) and its cold-start module-evaluation time by ~35%, with `fast-check` dropped entirely. This is also the import style Effect v4 recommends, so it's forward-compatible. A `no-restricted-imports` ESLint rule now enforces it across the codebase (type-only imports and `@effect/vitest` are exempt).
+
+  No API changes — your existing code keeps working.
+
+  ### Getting the full win in your own code
+
+  This change shrinks the Confect code in every function bundle, but a function's bundle also includes your own `confect/tables/*` and `*.spec.ts` files. esbuild retains the union across all importers, so a single barrel import anywhere in a function's module graph re-pins the whole `effect/Schema` namespace and undoes the reduction. To get the full bundle/cold-start savings, import Effect from its submodule paths in your own Confect files too:
+
+  ```diff
+  - import { Schema } from "effect";
+  + import * as Schema from "effect/Schema";
+  ```
+
+  Bare helpers (`pipe`, `flow`, `identity`) come from `"effect/Function"`.
+
+## 9.0.0-next.7
+
+### Patch Changes
+
+- 5d19484: Stabilize the identity of `@confect/react` hook results across renders.
+
+  `useQuery` previously decoded and wrapped the Convex result on every render, handing consumers a brand new `QueryResult` even when the underlying Convex data was unchanged. Effects and memoization that depend on the result's identity (e.g. `useEffect(..., [user])` derived via `QueryResult.match`) would re-run on every render, which could escalate into `Maximum update depth exceeded`. The decoded `QueryResult` is now memoized by the (referentially stable) Convex result, so unchanged data keeps a stable identity.
+
+  `useMutation` and `useAction` now return a stable callback via `useCallback`, matching the identity contract of Convex's own hooks, instead of allocating a fresh function each render.
+
+  `Ref.getFunctionReference` now caches the Convex function reference by function name, so repeated calls for the same ref return the same reference.
+
+## 9.0.0-next.6
+
+### Major Changes
+
+- 46045a9: Reduce per-function cold-start cost: make `FunctionSpec` schemas lazy and keep each Convex function's bundle scoped to its own group.
+
+  Previously, loading a single Convex function still paid for the whole project — importing the codegen-assembled `_generated/spec.ts` ran `Schema.Struct(...)` / `Schema.Array(...)` for every function at module load, and each per-function bundle transitively imported `_generated/api.ts` → `_generated/spec.ts` (every spec). A function's cold-start cost now scales with its own group rather than the size of the project.
+
+  ### Lazy `FunctionSpec` schemas
+
+  `FunctionSpec.*` (`publicQuery` / `internalQuery` / `publicMutation` / `internalMutation` / `publicAction` / `internalAction` / `publicNodeAction` / `internalNodeAction`) takes `args`, `returns`, and (optional) `error` as `() => Schema` thunks instead of bare schemas. The resulting provenance exposes them as sync lazy memoised getters (the same pattern `Table.make` uses), so importing `_generated/spec.ts` builds no schemas — construction is deferred to the first invocation that compiles validators or runs a codec.
+
+  Migration — wrap each schema in `() =>`:
+
+  ```diff
+    FunctionSpec.publicQuery({
+      name: "list",
+  -   args: Schema.Struct({}),
+  -   returns: Schema.Array(notes.Doc),
+  +   args: () => Schema.Struct({}),
+  +   returns: () => Schema.Array(notes.Doc),
+    })
+  ```
+
+  ### Impls take the `DatabaseSchema`, and group paths resolve impl-side
+
+  `FunctionImpl.make` and `GroupImpl.make` now take the runtime `DatabaseSchema` (the default export of `_generated/schema.ts`) as their first argument instead of the whole `Api`. The handler's ctx-service types only ever depended on the database schema, and switching impls to import `_generated/schema` instead of `_generated/api` removes `_generated/spec.ts` (and the function specs it transitively imports) from every per-function bundle.
+
+  Each function also registers under a flat, single-segment key into a fresh, isolated `Registry` provided per group by `RegisteredFunctions.buildForGroup` (and the CLI's impl validation), so no group-path lookup against `api.spec` is needed. As a result `Spec#addPath`, `Spec#paths`, and `Api.resolveGroupPathUnsafe` are removed; `GroupImpl` / `FunctionImpl` drop their group-path type parameter; and the codegen-emitted `_generated/spec.ts` / `nodeSpec.ts` no longer contain a `.addPath(...)` chain (the `.addAt(...)` / `.addGroupAt(...)` assembly tree that `Refs.make` consumes is unchanged).
+
+  Migration — in each `*.impl.ts`, import the database schema and pass it where you passed `api` / `nodeApi`:
+
+  ```diff
+  - import api from "../_generated/api";        // (or nodeApi from "../_generated/nodeApi")
+  + import databaseSchema from "../_generated/schema";
+
+  - const insert = FunctionImpl.make(api, notes, "insert", handler);
+  + const insert = FunctionImpl.make(databaseSchema, notes, "insert", handler);
+
+  - export default GroupImpl.make(api, notes).pipe(Layer.provide(insert), GroupImpl.finalize);
+  + export default GroupImpl.make(databaseSchema, notes).pipe(Layer.provide(insert), GroupImpl.finalize);
+  ```
+
+  Node impls migrate identically (from `nodeApi` to the same `_generated/schema`); only their specs differ (`GroupSpec.makeNode()`). Hand-rolled tests that built a `Spec` via `.addPath(group, "dot.path")` should drop those calls.
+
+  ### `buildForGroup` and the generated registries
+
+  `RegisteredFunctions.buildForGroup` takes the `DatabaseSchema` value plus the group's own `GroupSpec` as a single type argument (`buildForGroup<typeof groupSpec>(…)`, returning `RegisteredFunctionsForGroupSpec<Group>`); the `api` / `groupPath` parameters and the `ForGroupPath` dot-path navigation are gone. `RegisteredConvexFunction.make` / `RegisteredNodeFunction.make` take the `DatabaseSchema` rather than the `Api`. Each `_generated/registeredFunctions/{path}.ts` imports the runtime schema and references its group's leaf spec **type-only** (`typeof import("…/{group}.spec")["default"]`), so it never imports a spec module at runtime.
+
+  ### `_generated/api.ts` / `nodeApi.ts` are no longer emitted, and `Api` is removed
+
+  Nothing imports them anymore, so `confect codegen` no longer emits `_generated/api.ts` / `_generated/nodeApi.ts` and deletes any copies left over from earlier versions. The `Api` module itself (`@confect/server/Api` — `Api.make`, the `Api` type, `Api.resolveGroupPathUnsafe`, etc.) is **removed entirely**: impls and the generated registries take the `DatabaseSchema` value and the spec directly, so the combined database-schema-plus-spec `Api` is no longer used anywhere.
+
+  ### Net effect
+
+  A function's `convex/{path}.ts` bundle now imports only its own group's registry → its own `.impl` + `_generated/schema` (table schemas, built lazily) + its own group's spec. No `_generated/api.ts`, no project-wide `_generated/spec.ts`, and no sibling-group impls/specs. Re-run `confect codegen` after upgrading.
+
+- 762f7eb: Split the deploy-time Convex schema from the runtime `DatabaseSchema`, make `confect/tables/` the single source of truth — including the table name, which is now derived from the filename — and make per-table schema construction lazy.
+
+  Previously, `confect/schema.ts` was user-authored and `DatabaseSchema` carried a `convexSchemaDefinition` field that was eagerly rebuilt on every `.addTable(...)`. That field was an `O(n²)` allocation for `n` tables, and it forced both the deploy CLI (which only needs `defineSchema(...)`) and the runtime (which only needs the table codec lookup) through the same module — so any runtime function bundle dragged in `convex/server`'s `defineSchema`. Issue 1.
+
+  Codegen now scans `confect/tables/*.ts` (every file must default-export a `Table`) and emits two siblings:
+
+  - `confect/_generated/schema.ts` — the runtime `DatabaseSchema`, consumed by `_generated/api.ts`. Imports `@confect/server` but never `convex/server`.
+  - `confect/_generated/convexSchema.ts` — the Convex deploy `SchemaDefinition`, re-exported one-line from `convex/schema.ts`. Imports `convex/server` but never `@confect/server`.
+
+  The `convexSchemaDefinition` field is removed from `DatabaseSchema` and `Api`. `TestConfect.layer` now takes the Convex schema definition as a separate argument so it can stay aligned with the deploy artifact without bringing the runtime schema along for the ride.
+
+  ### Filename-derived table names
+
+  The table name is now derived from the file's basename — `confect/tables/notes.ts` defines a table called `notes`. `Table.make` no longer accepts a name argument and returns an _unnamed_ `Table` value; codegen invokes that value with the filename to produce the bound table.
+
+  This eliminates a class of subtle infelicities: the file basename and the table name can never drift out of sync, cross-table `_id` references are type-constrained against the actual set of declared tables (catching typos at compile time), and ESM cycle hazards for mutual cross-table `Id` references are gone because authoring files no longer transitively import each other.
+
+  Codegen now emits two new sets of files alongside `_generated/schema.ts` and `_generated/convexSchema.ts`:
+
+  - `confect/_generated/id.ts` — a single `Id` constructor whose argument is type-constrained to the union of your table names. Use `Id("notes")` everywhere you previously wrote `GenericId.GenericId("notes")`.
+  - `confect/_generated/tables/<name>.ts` — one thin wrapper per table that binds the unnamed value from `confect/tables/<name>.ts` to its filename. This is what other modules (specs, impls, HTTP handlers) default-import to reach a table's `Doc`, `Fields`, and `tableName`.
+
+  Table filenames must be valid JS identifiers, may not start with `_` (Convex reserves underscore-prefixed names for system tables), and may not collide with reserved JS keywords like `import.ts`. Pick a casing convention you like — Confect's example code uses `snake_case` (`notes.ts`, `user_profiles.ts`).
+
+  The bound `Table`'s `name` property has been renamed to `tableName`. This avoids a silent collision with the built-in `Function.prototype.name` that JavaScript carries on every function value (including the new unnamed-callable `UnnamedTable`).
+
+  ### Lazy per-table schema construction
+
+  `Table.make` takes a `() => Schema.Struct({...})` callback rather than a bare struct, and a bound `Table`'s `Fields`, `Doc`, and `tableDefinition` are lazy memoised getters that only invoke that callback on first access.
+
+  Previously, every `confect/tables/<name>.ts` module ran `Schema.Struct({...})` (and the corresponding `compileTableSchema` / `defineTable` work) at module-load time. Because the codegen-emitted `_generated/schema.ts` is imported transitively from every per-group function bundle, loading any one function eagerly built _every_ table's schema graph — paying a cold-start cost proportional to the whole project, not just the function being invoked.
+
+  The bound `Table` now exposes `Fields` / `Doc` / `tableDefinition` as lazy getters that compute their value on first access, then replace themselves with a plain non-writable data property so second-and-subsequent accesses are observably indistinguishable from a plain property (and skip all function-call overhead). The result: a function bundle only pays the schema-construction cost for tables it actually touches via `db.table(name)` (which reaches `Fields` through `Document.decode`). The `UnnamedTable` callable no longer exposes `Fields` or `tableDefinition` — read these off the bound `Table` (the generated `_generated/tables/<name>.ts` wrapper already binds the name).
+
+  ### Migration
+
+  1. Delete your `confect/schema.ts`. Codegen will refuse to run while a stray copy is present.
+  2. Rename each `confect/tables/<Name>.ts` to a valid JS identifier in your chosen casing convention (e.g. `confect/tables/notes.ts`). The basename becomes the table name; you no longer pass it as an argument.
+  3. Convert each table file to a **default-export-only** unnamed module: drop the name argument from `Table.make`, wrap the field-schema struct in a `() => ...` callback, and switch any `GenericId.GenericId("users")` references to `Id("users")` imported from `../_generated/id`:
+
+     ```diff
+     - import { GenericId } from "@confect/core";
+       import { Table } from "@confect/server";
+       import { Schema } from "effect";
+     + import { Id } from "../_generated/id";
+
+     - export default Table.make(
+     -   "notes",
+     -   Schema.Struct({
+     -     userId: Schema.optional(GenericId.GenericId("users")),
+     -     text: Schema.String,
+     -   }),
+     - );
+     + export default Table.make(() =>
+     +   Schema.Struct({
+     +     userId: Schema.optional(Id("users")),
+     +     text: Schema.String,
+     +   }),
+     + );
+     ```
+
+  4. Rewire every consumer site (specs, impls, integration tests, HTTP handlers, etc.) to import from the generated wrapper rather than directly from `tables/`. The wrapper is also where you now read `Doc` / `Fields` / `tableDefinition` (the unnamed `Table.make(...)` callable no longer exposes them):
+
+     ```diff
+     - import Notes from "../tables/Notes";
+     + import notes from "../_generated/tables/notes";
+
+     - returns: Schema.Array(Notes.Doc),
+     + returns: Schema.Array(notes.Doc),
+     ```
+
+  5. Replace every remaining `GenericId.GenericId("x")` call site with `Id("x")` from `_generated/id` (in spec `args`/`returns`, in `TaggedError` schemas, in `TestConfect.run`, etc.).
+  6. If you read `table.name` anywhere off a bound `Table`, rename it to `table.tableName`.
+  7. Re-run `confect codegen`. It will create `confect/_generated/schema.ts`, `confect/_generated/convexSchema.ts`, `confect/_generated/id.ts`, and one `confect/_generated/tables/<name>.ts` wrapper per table; and it will rewrite `convex/schema.ts` to a one-line re-export.
+  8. If you use `@confect/test`, pass the generated Convex schema definition to `TestConfect.layer`:
+
+     ```diff
+     - import confectSchema from "./confect/schema";
+     + import confectSchema from "./confect/_generated/schema";
+     + import convexSchema from "./confect/_generated/convexSchema";
+
+       export const layer = TestConfect_.layer(
+         confectSchema,
+     +   convexSchema,
+         import.meta.glob("./convex/**/!(*.*.*)*.*s"),
+       );
+     ```
+
+  ### New warning: no tables discovered
+
+  If a Confect project has no tables — either `confect/tables/` is missing entirely or it exists but contains no `.ts` files — codegen now emits a yellow `⚠` warning and continues, producing an empty `DatabaseSchema.make()` / `defineSchema({})`. Table-free backends (e.g. action-only proxies, webhook bridges) are still legal; the warning just catches the much more common case of a typoed directory name or files placed at the wrong path. To silence it, add at least one `Table.make(...)` module under `confect/tables/`.
+
+  ### New error: invalid table filename
+
+  Codegen now rejects table files whose basename is not a valid JS identifier (e.g. `user-profiles.ts`), starts with `_` (reserved for Convex system tables), or shadows a reserved JS keyword (e.g. `import.ts`). Rename the offending file to fix it — for example, `user-profiles.ts` → `user_profiles.ts` or `userProfiles.ts`.
+
+## 9.0.0-next.5
+
+## 9.0.0-next.4
+
+## 9.0.0-next.3
+
+### Patch Changes
+
+- 6d85210: Resolve `FunctionImpl` / `GroupImpl` group paths via an immutable `paths` map on `Spec` instead of identity-walking the assembled tree.
+
+  ### Why
+
+  Since `9.0.0-next.1`, codegen has wrapped every parent leaf that has sibling subdirectory specs in `<parent>.addGroupAt("child", <child>)`. Because `GroupSpec.addGroupAt` is immutable, that produced a fresh object in the assembled tree, while the parent's `*.impl.ts` continued to hold a reference to the original imported leaf. The runtime resolver compared by `===`, so every such impl failed `validateImpl` with "Could not resolve group path for the provided GroupSpec." Child impls happened to work only because `GroupSpec.withName` was secretly mutating its argument in place to keep the child's identity stable — an asymmetry that was load-bearing for one half of the API and broken for the other.
+
+  ### What changed
+
+  - `@confect/core/Spec` carries a new `readonly paths: ReadonlyMap<GroupSpec.AnyWithProps, string>` field and exposes a chainable `Spec#addPath(group, path)` builder. `add` / `addAt` / `merge` propagate `paths` unchanged; `merge` re-prefixes a node spec's entries with `"node."` to match the merged tree.
+  - `@confect/core/GroupSpec.withName` is now pure: it returns a fresh copy when the name differs and no longer rewrites the input in place. No new identity-tracking machinery is introduced.
+  - `@confect/server/FunctionImpl.make` and `GroupImpl.make` resolve their group path via `api.spec.paths.get(group)` — an O(1) map lookup instead of a tree walk — and throw a clearer error pointing at `Spec.addPath` when the spec hasn't been registered.
+  - `@confect/server/GroupPath` (the old identity-based resolver) is deleted.
+  - `@confect/cli` codegen emits one `.addPath(<binding>, "<dot.path>")` call per leaf in `_generated/spec.ts` (and `_generated/nodeSpec.ts`) so the imported leaves carry their full paths into the assembled spec value.
+
+  ### User-facing impact
+
+  - Spec authoring (`*.spec.ts`) and impl authoring (`*.impl.ts`) APIs are unchanged. `FunctionImpl.make(api, spec, name, handler)` and `GroupImpl.make(api, spec)` keep their exact signatures.
+  - Generated `_generated/spec.ts` (and `_generated/nodeSpec.ts`) pick up one `.addPath(...)` chain entry per leaf on the next `confect codegen` run. The shape is fully immutable — no module-load mutation, no hidden side effects.
+  - Hand-rolled tests that construct a `Spec` and pass it to `Api.make` must now also call `.addPath(spec, "dot.path")` for any group they intend to look up.
+
+  ### Fixes
+
+  This eliminates the runtime regression introduced in `9.0.0-next.1` for any project layout where a `confect/{path}.spec.ts` declares functions alongside a sibling `confect/{path}/` subdirectory of further specs.
+
+## 9.0.0-next.2
+
+## 9.0.0-next.1
+
 ## 9.0.0-next.0
 
 ### Major Changes
@@ -15,6 +276,7 @@
   Splitting impl across colocated `*.impl.ts` files is the vehicle for fixing that. With this change, `confect codegen` emits one `_generated/registeredFunctions/{path}.ts` per group, and each generated `convex/` module imports only its own group's per-group registry — which in turn imports only its own sibling `.impl.ts`. A Convex function's cold-start bundle now scales with its own group's impl rather than with the size of the whole project.
 
   ### Breaking changes
+
   - `GroupSpec.make()` and `GroupSpec.makeNode()` no longer take a name argument; the group name is derived from the spec file's path within `confect/`.
   - `FunctionImpl.make(api, groupSpec, fn, handler)` and `GroupImpl.make(api, groupSpec)` now take the imported sibling spec object as their second argument instead of a dot-path string.
   - Every `GroupImpl` pipeline must end with `GroupImpl.finalize`, which only typechecks once every function declared by the spec has a corresponding `FunctionImpl` provided to the group layer. `GroupImpl.finalize` snapshots the names of every registered function onto the produced `Finalized` `GroupImpl` service value, and `confect codegen` reads those names to verify per-function coverage against the spec at runtime.
@@ -23,6 +285,7 @@
   - Every module under `convex/` is re-emitted to import from `_generated/registeredFunctions/{path}` instead of the previous aggregate file. Users who commit `convex/` to source control should expect a full rewrite of that directory on first codegen.
 
   ### Migration
+
   1. For each existing group, create a colocated `confect/{path}.spec.ts` and `confect/{path}.impl.ts` pair (under a subdirectory for nested groups).
      - In each spec, call `GroupSpec.make()` (or `GroupSpec.makeNode()`) without a name and `export default` the result.
      - In each impl, default-import the sibling spec (e.g. `import notes from "./notes.spec"`), pass it to `FunctionImpl.make`/`GroupImpl.make` in place of the previous dot-path string, append `GroupImpl.finalize` to the pipeline, and `export default` the resulting `GroupImpl` layer:
@@ -30,7 +293,7 @@
        export default GroupImpl.make(api, notes).pipe(
          Layer.provide(list),
          Layer.provide(insert),
-         GroupImpl.finalize,
+         GroupImpl.finalize
        );
        ```
   2. Delete root `confect/spec.ts`, `confect/impl.ts`, `confect/nodeSpec.ts`, `confect/nodeImpl.ts`, and any parent aggregator spec/impl files. (`confect codegen` will also delete any of these it finds, plus the stale `_generated/registeredFunctions.ts` and `_generated/nodeRegisteredFunctions.ts`, so this step can be skipped.)
@@ -68,7 +331,7 @@
 
   export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
     "NoteNotFound",
-    { noteId: GenericId.GenericId("notes") },
+    { noteId: GenericId.GenericId("notes") }
   ) {}
 
   export const notes = GroupSpec.make("notes").addFunction(
@@ -77,7 +340,7 @@
       args: Schema.Struct({ noteId: GenericId.GenericId("notes") }),
       returns: Notes.Doc,
       error: NoteNotFound,
-    }),
+    })
   );
   ```
 
@@ -97,7 +360,7 @@
         .table("notes")
         .get(noteId)
         .pipe(Effect.mapError(() => new NoteNotFound({ noteId })));
-    }),
+    })
   );
   ```
 
@@ -169,6 +432,7 @@
   Unspecified failures continue to reject the promise.
 
   ### Migration
+
   - For each `useQuery` call site, replace `result === undefined` checks and direct property access with `QueryResult.match` (or the lower-level `QueryResult.isLoading`/`isSuccess`/`isFailure` predicates).
   - For each `useMutation`/`useAction` call site whose ref now declares an `error` schema, unwrap the resolved `Either` (e.g. with `Either.match`); call sites against refs without an `error` schema need no change.
 

package/dist/FunctionProvenance.d.ts

@@ -1,116 +1,122 @@
-import { Data, Schema } from "effect";
-import { DefaultFunctionArgs } from "convex/server";
-import * as effect_Unify0 from "effect/Unify";
-
-//#region src/FunctionProvenance.d.ts
-declare namespace FunctionProvenance_d_exports {
-  export { AnyConfect, AnyConvex, Confect, Convex, FunctionProvenance };
-}
-type FunctionProvenance = Data.TaggedEnum<{
-  Confect: {
-    args: Schema.Schema.AnyNoContext;
-    returns: Schema.Schema.AnyNoContext;
-    error?: Schema.Schema.AnyNoContext;
-  };
-  Convex: {};
+import type { DefaultFunctionArgs } from "convex/server";
+import type { Schema } from "effect";
+import * as Data from "effect/Data";
+export type FunctionProvenance = Data.TaggedEnum<{
+    Confect: {
+        args: Schema.Schema.AnyNoContext;
+        returns: Schema.Schema.AnyNoContext;
+        error?: Schema.Schema.AnyNoContext;
+    };
+    Convex: {};
 }>;
-interface Confect<Args extends Schema.Schema.AnyNoContext, Returns extends Schema.Schema.AnyNoContext, Error extends Schema.Schema.AnyNoContext = never> {
-  readonly _tag: "Confect";
-  readonly args: Args;
-  readonly returns: Returns;
-  readonly error?: Error;
+export interface Confect<Args extends Schema.Schema.AnyNoContext, Returns extends Schema.Schema.AnyNoContext, Error extends Schema.Schema.AnyNoContext = never> {
+    readonly _tag: "Confect";
+    readonly args: Args;
+    readonly returns: Returns;
+    readonly error?: Error;
 }
-interface AnyConfect extends Confect<Schema.Schema.AnyNoContext, Schema.Schema.AnyNoContext, Schema.Schema.AnyNoContext> {}
-interface Convex<Args extends DefaultFunctionArgs, Returns> {
-  readonly _tag: "Convex";
-  readonly _args: Args;
-  readonly _returns: Returns;
+export interface AnyConfect extends Confect<Schema.Schema.AnyNoContext, Schema.Schema.AnyNoContext, Schema.Schema.AnyNoContext> {
 }
-interface AnyConvex extends Convex<DefaultFunctionArgs, any> {}
-declare const FunctionProvenance: {
-  readonly Confect: Data.Case.Constructor<{
-    readonly _tag: "Confect";
-    readonly args: Schema.Schema.AnyNoContext;
-    readonly returns: Schema.Schema.AnyNoContext;
-    readonly error?: Schema.Schema.AnyNoContext;
-  }, "_tag">;
-  readonly Convex: Data.Case.Constructor<{
-    readonly _tag: "Convex";
-    readonly _args: DefaultFunctionArgs;
-    readonly _returns: any;
-  }, "_tag">;
-  readonly $is: <Tag extends "Confect" | "Convex">(tag: Tag) => (u: unknown) => u is Extract<{
-    readonly _tag: "Confect";
-    readonly args: Schema.Schema.AnyNoContext;
-    readonly returns: Schema.Schema.AnyNoContext;
-    readonly error?: Schema.Schema.AnyNoContext;
-  }, {
-    readonly _tag: Tag;
-  }> | Extract<{
+export interface Convex<Args extends DefaultFunctionArgs, Returns> {
     readonly _tag: "Convex";
-    readonly _args: DefaultFunctionArgs;
-    readonly _returns: any;
-  }, {
-    readonly _tag: Tag;
-  }>;
-  readonly $match: {
-    <const Cases extends {
-      readonly Confect: (args: {
+    readonly _args: Args;
+    readonly _returns: Returns;
+}
+export interface AnyConvex extends Convex<DefaultFunctionArgs, any> {
+}
+export declare const FunctionProvenance: {
+    readonly Confect: Data.Case.Constructor<{
         readonly _tag: "Confect";
         readonly args: Schema.Schema.AnyNoContext;
         readonly returns: Schema.Schema.AnyNoContext;
         readonly error?: Schema.Schema.AnyNoContext;
-      }) => any;
-      readonly Convex: (args: {
+    }, "_tag">;
+    readonly Convex: Data.Case.Constructor<{
         readonly _tag: "Convex";
         readonly _args: DefaultFunctionArgs;
         readonly _returns: any;
-      }) => any;
-    }>(cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never }): (value: {
-      readonly _tag: "Confect";
-      readonly args: Schema.Schema.AnyNoContext;
-      readonly returns: Schema.Schema.AnyNoContext;
-      readonly error?: Schema.Schema.AnyNoContext;
-    } | {
-      readonly _tag: "Convex";
-      readonly _args: DefaultFunctionArgs;
-      readonly _returns: any;
-    }) => effect_Unify0.Unify<ReturnType<Cases["Confect" | "Convex"]>>;
-    <const Cases extends {
-      readonly Confect: (args: {
+    }, "_tag">;
+    readonly $is: <Tag extends "Confect" | "Convex">(tag: Tag) => (u: unknown) => u is Extract<{
         readonly _tag: "Confect";
         readonly args: Schema.Schema.AnyNoContext;
         readonly returns: Schema.Schema.AnyNoContext;
         readonly error?: Schema.Schema.AnyNoContext;
-      }) => any;
-      readonly Convex: (args: {
+    }, {
+        readonly _tag: Tag;
+    }> | Extract<{
         readonly _tag: "Convex";
         readonly _args: DefaultFunctionArgs;
         readonly _returns: any;
-      }) => any;
-    }>(value: {
-      readonly _tag: "Confect";
-      readonly args: Schema.Schema.AnyNoContext;
-      readonly returns: Schema.Schema.AnyNoContext;
-      readonly error?: Schema.Schema.AnyNoContext;
-    } | {
-      readonly _tag: "Convex";
-      readonly _args: DefaultFunctionArgs;
-      readonly _returns: any;
-    }, cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never }): effect_Unify0.Unify<ReturnType<Cases["Confect" | "Convex"]>>;
-  };
-};
-declare const Confect: <Args extends Schema.Schema.AnyNoContext, Returns extends Schema.Schema.AnyNoContext, Error extends Schema.Schema.AnyNoContext = never>(args: Args, returns: Returns, error?: Error) => {
-  readonly _tag: "Confect";
-  readonly args: Schema.Schema.AnyNoContext;
-  readonly returns: Schema.Schema.AnyNoContext;
-  readonly error?: Schema.Schema.AnyNoContext;
+    }, {
+        readonly _tag: Tag;
+    }>;
+    readonly $match: {
+        <const Cases extends {
+            readonly Confect: (args: {
+                readonly _tag: "Confect";
+                readonly args: Schema.Schema.AnyNoContext;
+                readonly returns: Schema.Schema.AnyNoContext;
+                readonly error?: Schema.Schema.AnyNoContext;
+            }) => any;
+            readonly Convex: (args: {
+                readonly _tag: "Convex";
+                readonly _args: DefaultFunctionArgs;
+                readonly _returns: any;
+            }) => any;
+        }>(cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never; }): (value: {
+            readonly _tag: "Confect";
+            readonly args: Schema.Schema.AnyNoContext;
+            readonly returns: Schema.Schema.AnyNoContext;
+            readonly error?: Schema.Schema.AnyNoContext;
+        } | {
+            readonly _tag: "Convex";
+            readonly _args: DefaultFunctionArgs;
+            readonly _returns: any;
+        }) => import("effect/Unify").Unify<ReturnType<Cases["Confect" | "Convex"]>>;
+        <const Cases extends {
+            readonly Confect: (args: {
+                readonly _tag: "Confect";
+                readonly args: Schema.Schema.AnyNoContext;
+                readonly returns: Schema.Schema.AnyNoContext;
+                readonly error?: Schema.Schema.AnyNoContext;
+            }) => any;
+            readonly Convex: (args: {
+                readonly _tag: "Convex";
+                readonly _args: DefaultFunctionArgs;
+                readonly _returns: any;
+            }) => any;
+        }>(value: {
+            readonly _tag: "Confect";
+            readonly args: Schema.Schema.AnyNoContext;
+            readonly returns: Schema.Schema.AnyNoContext;
+            readonly error?: Schema.Schema.AnyNoContext;
+        } | {
+            readonly _tag: "Convex";
+            readonly _args: DefaultFunctionArgs;
+            readonly _returns: any;
+        }, cases: Cases & { [K in Exclude<keyof Cases, "Confect" | "Convex">]: never; }): import("effect/Unify").Unify<ReturnType<Cases["Confect" | "Convex"]>>;
+    };
 };
-declare const Convex: <_Args extends DefaultFunctionArgs, _Returns>() => {
-  readonly _tag: "Convex";
-  readonly _args: DefaultFunctionArgs;
-  readonly _returns: any;
+/**
+ * Build a `Confect` provenance from lazy schema thunks. `args`, `returns`,
+ * and `error` are exposed as sync lazy memoised getters (via {@link Lazy.defineProperty})
+ * that only evaluate their thunk on first access, mirroring how `Table`
+ * defers `Fields`/`Doc`/`tableDefinition`. This keeps importing the assembled
+ * `_generated/spec.ts` cheap — no `Schema.Struct(...)` / `Schema.Array(...)`
+ * work runs at module load; it is deferred to the first invocation that
+ * actually compiles validators or runs a codec.
+ *
+ * The object is built by hand rather than through `FunctionProvenance.Confect`
+ * because the `Data` constructor copies its input with `Object.assign`, which
+ * would force the getters at construction time and defeat the laziness.
+ * `error` is only installed when an `errorThunk` is provided, so its absence
+ * is observable via `"error" in provenance` without forcing anything; nothing
+ * relies on `Data`'s structural `Equal`/`Hash` for provenance values.
+ */
+export declare const Confect: <Args extends Schema.Schema.AnyNoContext, Returns extends Schema.Schema.AnyNoContext, Error extends Schema.Schema.AnyNoContext = never>(args: () => Args, returns: () => Returns, error?: () => Error) => Confect<Args, Returns, Error>;
+export declare const Convex: <_Args extends DefaultFunctionArgs, _Returns>() => {
+    readonly _tag: "Convex";
+    readonly _args: DefaultFunctionArgs;
+    readonly _returns: any;
 };
-//#endregion
-export { AnyConfect, AnyConvex, Confect, Convex, FunctionProvenance, FunctionProvenance_d_exports };
 //# sourceMappingURL=FunctionProvenance.d.ts.map

package/dist/FunctionProvenance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FunctionProvenance.d.ts","names":[],"sources":["../src/FunctionProvenance.ts"],"mappings":";;;;;;;;KAIY,kBAAA,GAAqB,IAAA,CAAK,UAAA;EACpC,OAAA;IACE,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,YAAA;IACpB,OAAA,EAAS,MAAA,CAAO,MAAA,CAAO,YAAA;IACvB,KAAA,GAAQ,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAExB,MAAA;AAAA;AAAA,UAQe,OAAA,cACF,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,SAEnB,IAAA;EAAA,SACA,IAAA,EAAM,IAAA;EAAA,SACN,OAAA,EAAS,OAAA;EAAA,SACT,KAAA,GAAQ,KAAA;AAAA;AAAA,UAGF,UAAA,SAAmB,OAAA,CAClC,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA,EACd,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA,UAGC,MAAA,cAAoB,mBAAA;EAAA,SAC1B,IAAA;EAAA,SACA,KAAA,EAAO,IAAA;EAAA,SACP,QAAA,EAAU,OAAA;AAAA;AAAA,UAGJ,SAAA,SAAkB,MAAA,CAAO,mBAAA;AAAA,cAE7B,kBAAA;EAAA;;mBArCH,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;EAAA;;oBAIf,mBAAA;IAAA;;;;mBAND,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA;IAAA;;;oBAIf,mBAAA;IAAA;;;;;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;MAAA;;wBAIf,mBAAA;QAAA;;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;MAAA;sBAIf,mBAAA;MAAA;;;;;uBAND,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;QAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA;MAAA;;wBAIf,mBAAA;QAAA;;;;qBAND,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;MAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;IAAA;MAAA;sBAIf,mBAAA;MAAA;;;;cAiCE,OAAA,gBACE,MAAA,CAAO,MAAA,CAAO,YAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA,gBAChB,MAAA,CAAO,MAAA,CAAO,YAAA,UAE5B,IAAA,EAAM,IAAA,EACN,OAAA,EAAS,OAAA,EACT,KAAA,GAAQ,KAAA;EAAA;iBA9CA,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,kBACX,MAAA,CAAO,MAAA,CAAO,YAAA;EAAA,iBACf,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA;AAAA,cAoDb,MAAA,iBAAwB,mBAAA;EAAA;kBAhD1B,mBAAA;EAAA"}
+{"version":3,"file":"FunctionProvenance.d.ts","sourceRoot":"","sources":["../src/FunctionProvenance.ts"],"names":[],"mappings":"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"}

package/dist/FunctionProvenance.js

@@ -1,5 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { Data } from "effect";
+import { defineProperty } from "./Lazy.js";
+import * as Data from "effect/Data";
 
 //#region src/FunctionProvenance.ts
 var FunctionProvenance_exports = /* @__PURE__ */ __exportAll({
@@ -8,11 +9,29 @@ var FunctionProvenance_exports = /* @__PURE__ */ __exportAll({
 	FunctionProvenance: () => FunctionProvenance
 });
 const FunctionProvenance = Data.taggedEnum();
-const Confect = (args, returns, error) => FunctionProvenance.Confect({
-	args,
-	returns,
-	...error !== void 0 ? { error } : {}
-});
+/**
+* Build a `Confect` provenance from lazy schema thunks. `args`, `returns`,
+* and `error` are exposed as sync lazy memoised getters (via {@link Lazy.defineProperty})
+* that only evaluate their thunk on first access, mirroring how `Table`
+* defers `Fields`/`Doc`/`tableDefinition`. This keeps importing the assembled
+* `_generated/spec.ts` cheap — no `Schema.Struct(...)` / `Schema.Array(...)`
+* work runs at module load; it is deferred to the first invocation that
+* actually compiles validators or runs a codec.
+*
+* The object is built by hand rather than through `FunctionProvenance.Confect`
+* because the `Data` constructor copies its input with `Object.assign`, which
+* would force the getters at construction time and defeat the laziness.
+* `error` is only installed when an `errorThunk` is provided, so its absence
+* is observable via `"error" in provenance` without forcing anything; nothing
+* relies on `Data`'s structural `Equal`/`Hash` for provenance values.
+*/
+const Confect = (args, returns, error) => {
+	const provenance = { _tag: "Confect" };
+	defineProperty(provenance, "args", args);
+	defineProperty(provenance, "returns", returns);
+	if (error !== void 0) defineProperty(provenance, "error", error);
+	return provenance;
+};
 const Convex = () => FunctionProvenance.Convex({});
 
 //#endregion