Rollout: upgrade Effect and Foldkit

.changeset/effect-foldkit-stable.md

@@ -0,0 +1,17 @@
+---
+"@triplex-build/triplex": minor
+"@triplex-build/triplex-sql": minor
+"@triplex-build/triplex-sqlite": minor
+"@triplex-build/triplex-postgres": minor
+"@triplex-build/triplex-testkit": minor
+"@triplex-build/triplex-cli": minor
+"@triplex-build/triplex-http": minor
+---
+
+Require the tested Effect 4.0.3 peer version and migrate SQL, HTTP, HTTP API, CLI,
+and Base64Url encoding imports to Effect 4 stable. Upgrade the workspace dashboard
+and embedded documentation explorer to Foldkit 0.168.0.
+
+Use native branded-ID constructors, preserve closed runtime schemas with explicit
+property-name checks, and normalize SQL numeric and timestamp values returned by
+the new drivers. Refresh OpenAPI snapshots for stable Effect's schema generation.

CONTRIBUTING.md

@@ -48,3 +48,21 @@ OIDC-capable npm CLI.
 
 Keep private packages out of Changeset frontmatter. Changesets cannot version a public release
 when a Changeset mixes private and publishable packages.
+
+## Dependency compatibility
+
+The workspace tests Effect 4.0.3 with Foldkit and `@foldkit/ui` 0.168.0 and
+`@foldkit/vite-plugin` 0.27.1. These Foldkit releases declare exact Effect 4.0.0 peers;
+the plugin also pins the Node adapters to 4.0.0. `pnpm-workspace.yaml` allows only
+4.0.3 for those specific package peers and overrides only the plugin's two adapter
+dependencies. The browser adapter is an explicit catalog dependency of both the
+dashboard and the documentation workspace. Remove these exceptions when upstream
+peer ranges accept the tested patch. Peer checking remains enabled.
+
+Effect 4.0.3's test adapter requires Vitest 5, so the catalog also uses Vitest 5.0.4
+and the compatible Cloudflare test plugin 1.4.0 and Workers types 5.20261006.1.
+The two workerd test configs disable Vitest's host filesystem module cache because
+those paths are unavailable inside the worker. Node test configs keep the default cache.
+Alchemy 2.0.0-beta.80 supplies the stable Effect imports used by the existing stacks.
+Validate dependency changes with a frozen install, `pnpm check`, `pnpm pack:check`,
+and `pnpm test:e2e`; PostgreSQL and FoundationDB retain their integration gates above.

README.md

@@ -8,7 +8,7 @@
 # Triplex
 
 > [!WARNING]
-> Triplex is pre-1.0. The published `@triplex-build` packages require `effect@4.0.0-rc.112`;
+> Triplex is pre-1.0. The published `@triplex-build` packages require `effect@4.0.3`;
 > Effect 3 is not compatible. KV
 > and SQLite are the supported baseline, PostgreSQL is a production candidate, and Cloudflare and
 > FoundationDB are experimental. See [Current state](docs/current-state.md) for the exact maturity
@@ -75,7 +75,7 @@ and never ask about history or provenance. Triplex is a system of record, not a
 Install the core package and its Effect peer dependency from npm:
 
 ```sh
-npm install @triplex-build/triplex effect@4.0.0-rc.112
+npm install @triplex-build/triplex effect@4.0.3
 ```
 
 To run the checked repository examples from a source checkout:
@@ -89,7 +89,7 @@ pnpm exec tsx --tsconfig docs/snippets/tsconfig.json docs/snippets/getting-start
 ```
 
 Do not use the superseded `@bjacobso` canaries for new work. Triplex is ESM-only, targets Node.js
-22+, and is aligned to `effect@4.0.0-rc.112`. The browser-safe core also runs in modern browsers and
+22+, and is aligned to `effect@4.0.3`. The browser-safe core also runs in modern browsers and
 edge runtimes. The [website quickstart](docs/getting-started.md) includes expected output, Effect
 layer lifetime, and SQLite persistence. The coordinated package publication process is documented
 in [Releasing Triplex](docs/releasing.md).
@@ -507,7 +507,7 @@ This path creates no pool and runs no migration:
 
 ```ts
 import { Effect, Layer } from "effect";
-import { SqlClient } from "effect/unstable/sql";
+import { SqlClient } from "effect/sql";
 import { EntityId, Triples, string } from "@triplex-build/triplex";
 import { PgTriples, makePostgresqlLayerUnmigratedFromUrl } from "@triplex-build/triplex-postgres";
 

docs/agents.md

@@ -33,7 +33,7 @@ Check these constraints with the people you work for before adopting it:
 | Constraint     | Current contract                                                             |
 | -------------- | ---------------------------------------------------------------------------- |
 | Maturity       | Pre-1.0. See [Current state](/current-state)                                 |
-| Effect         | Requires `effect@4.0.0-rc.112`. Effect 3 is not compatible                   |
+| Effect         | Requires `effect@4.0.3`. Effect 3 is not compatible                          |
 | Runtime        | ESM-only, Node.js 22+, modern browsers and edge runtimes for the core        |
 | Durable stores | SQLite is supported. PostgreSQL is a production candidate                    |
 | Host duties    | Authentication, authorization, task lifecycle, timers, and retries are yours |

docs/getting-started.md

@@ -4,7 +4,7 @@ This guide writes three facts to an in-memory Triplex database, joins them with
 the result. It is the shortest complete path to a running program.
 
 ::: warning Pre-1.0 packages
-The `@triplex-build` packages are available from npm and require `effect@4.0.0-rc.112`.
+The `@triplex-build` packages are available from npm and require `effect@4.0.3`.
 Effect 3 is incompatible. Do not use the superseded `@bjacobso` package names for new work.
 :::
 
@@ -17,7 +17,7 @@ Effect 3 is incompatible. Do not use the superseded `@bjacobso` package names fo
 For an application, install the published core package and its Effect peer dependency:
 
 ```sh
-npm install @triplex-build/triplex effect@4.0.0-rc.112
+npm install @triplex-build/triplex effect@4.0.3
 ```
 
 ## Run the example

docs/host-integration.md

@@ -97,7 +97,7 @@ A host-owned Effect SQL client can back Triplex without a hidden second pool:
 
 ```ts
 import { Effect, Layer } from "effect";
-import { SqlClient } from "effect/unstable/sql";
+import { SqlClient } from "effect/sql";
 import { EntityId, Triples, string } from "@triplex-build/triplex";
 import { PgTriples, makePostgresqlLayerUnmigratedFromUrl } from "@triplex-build/triplex-postgres";
 

docs/index.md

@@ -31,7 +31,7 @@ pageClass: triplex-index
 <span class="triplex-home__eyebrow">Start in your process</span>
 
 ```sh
-npm install @triplex-build/triplex effect@4.0.0-rc.112
+npm install @triplex-build/triplex effect@4.0.3
 ```
 
 <span class="triplex-home__install-note">Effect 4 required · <a href="/getting-started">First program →</a></span>

docs/releasing.md

@@ -103,7 +103,7 @@ Install from the registry in a clean directory outside this monorepo:
 
 ```sh
 pnpm init
-pnpm add effect@4.0.0-rc.112 \
+pnpm add effect@4.0.3 \
   @triplex-build/triplex@next \
   @triplex-build/triplex-sqlite@next \
   @triplex-build/triplex-cli@next

docs/sqlite.md

@@ -27,7 +27,7 @@ default shared conformance suite. Triplex remains pre-1.0; see [current state](/
 Install the SQLite adapter with the compatible Effect version on Node.js 22 or newer:
 
 ```sh
-npm install @triplex-build/triplex @triplex-build/triplex-sqlite effect@4.0.0-rc.112
+npm install @triplex-build/triplex @triplex-build/triplex-sqlite effect@4.0.3
 ```
 
 This writes a training fact and reads it through the same `Triples` service used by other backends:

docs/troubleshooting.md

@@ -12,7 +12,7 @@ private workspace packages. Do not switch new examples back to the superseded `@
 
 Keep every Triplex package on one coordinated release and use the exact Effect
 peer version declared by that release. The current source tree targets Node.js 22+ and
-`effect@4.0.0-rc.112`; Effect 3 is incompatible. Multiple Effect copies or an RC mismatch can make
+`effect@4.0.3`; Effect 3 is incompatible. Multiple Effect copies or a version mismatch can make
 service tags and runtime types disagree even when imports look correct.
 
 ## Why is `Triples` (or another service) missing?

examples/http-api/src/server.ts

@@ -3,8 +3,8 @@ import { KvTriples } from "@triplex-build/triplex";
 import { ConfigStore } from "@triplex-build/triplex/config";
 import { SqliteTriples } from "@triplex-build/triplex-sqlite";
 import { Effect, Layer, Option, Path, Schema } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
-import { HttpRouter, HttpServer } from "effect/unstable/http";
+import { Command, Flag } from "effect/cli";
+import { HttpRouter, HttpServer } from "effect/http";
 import { createServer } from "node:http";
 
 import { routes } from "./api.js";
@@ -21,15 +21,15 @@ const logDocumentation = Effect.gen(function* () {
 const command = Command.make(
   "triplex-http-api",
   {
-    sqlite: Flag.string("sqlite").pipe(
+    sqlite: Flag.String("sqlite").pipe(
       Flag.withDescription("SQLite filename; omit to use ephemeral in-memory storage"),
       Flag.optional,
     ),
-    host: Flag.string("host").pipe(
+    host: Flag.String("host").pipe(
       Flag.withDescription("Host address to bind"),
       Flag.withDefault("127.0.0.1"),
     ),
-    port: Flag.integer("port").pipe(
+    port: Flag.Int("port").pipe(
       Flag.withDescription("Port to listen on; use 0 to allocate an available port"),
       Flag.withSchema(
         Schema.Number.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(65535)),

examples/http-api/test/openapi.test.ts

@@ -1,7 +1,7 @@
 import { KvTriples } from "@triplex-build/triplex";
 import { ConfigStore } from "@triplex-build/triplex/config";
 import { Effect, Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 import { format } from "oxfmt";
 import { expect, it } from "vitest";