@danieljvdm/dev-kit 0.11.3 → 0.13.0

package/skills/build-effect-apis/references/effect-atom-client.md

@@ -0,0 +1,161 @@
+# Effect API clients
+
+Derive clients from the shared `HttpApi`; keep request types, response types,
+and expected errors owned by the contract.
+
+- [Inventory the client boundary](#inventory-the-client-boundary)
+- [Build one Atom API service](#build-one-atom-api-service)
+- [Define queries](#define-queries)
+- [Define mutations and invalidation](#define-mutations-and-invalidation)
+- [Use a direct client outside React](#use-a-direct-client-outside-react)
+
+## Inventory the client boundary
+
+Before changing Atom code, locate every `RegistryProvider`, runtime factory,
+`AtomHttpApi.Service`, query atom, mutation atom, reactivity-key constructor,
+and route aggregate. Confirm the installed `effect` and `@effect/atom-react`
+versions before copying signatures.
+
+## Build one Atom API service
+
+Create one module-scoped runtime factory and one `AtomHttpApi.Service`. Share a
+memo map when multiple client services must reuse layers.
+
+```ts
+import { Effect, Layer } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiMiddleware } from "effect/unstable/httpapi";
+import { Atom, AtomHttpApi } from "effect/unstable/reactivity";
+import { ApplicationApi, Authenticate } from "@app/domain";
+
+export const AuthenticateClient = HttpApiMiddleware.layerClient(
+  Authenticate,
+  Effect.fn("AuthenticateClient")(function* ({ next, request }) {
+    const token = yield* readAccessToken;
+    return yield* next(HttpClientRequest.bearerToken(request, token));
+  }),
+);
+
+const ApiHttpClient = Layer.mergeAll(FetchHttpClient.layer, AuthenticateClient);
+
+export const appRuntime = Atom.context({
+  memoMap: Layer.makeMemoMapUnsafe(),
+});
+
+export const ApiClient = AtomHttpApi.Service()("ApiClient", {
+  api: ApplicationApi,
+  httpClient: ApiHttpClient,
+  runtime: appRuntime,
+  baseUrl: "/api",
+  transformClient: (client) =>
+    HttpClient.mapRequest(client, (request) =>
+      HttpClientRequest.setHeader(request, "x-request-id", requestId()),
+    ),
+});
+```
+
+Define the runtime, service, key constructors, queries, and mutations outside
+React renders. Keep browser-only identity access behind the client boundary.
+When contract middleware sets `requiredForClient`, satisfy it with
+`HttpApiMiddleware.layerClient` in the `httpClient` layer. Reserve
+`transformClient` for transport-wide behavior such as correlation headers,
+base URL changes, tracing, or retries; do not bypass declared API security with
+an unrelated raw header transform.
+
+## Define queries
+
+```ts
+export const projectKeys = {
+  collection: ["projects"] as const,
+  project: (id: ProjectId) => [`project:${id}`] as const,
+};
+
+export const projectAtom = Atom.family((projectId: ProjectId) =>
+  ApiClient.query("projects", "getProject", {
+    params: { projectId },
+    timeToLive: "5 minutes",
+    reactivityKeys: projectKeys.project(projectId),
+  }).pipe(Atom.swr({ staleTime: "30 seconds", revalidateOnMount: true })),
+);
+```
+
+`query(group, endpoint, request)` returns an `Atom<AsyncResult<...>>`. The
+service memoizes encoded request keys internally; a public `Atom.family` still
+expresses domain ownership and cache policy through a stable scalar or Effect
+`Hash`/`Equal` key.
+
+Query options have distinct jobs:
+
+- `timeToLive` controls idle registry retention;
+- `reactivityKeys` registers invalidation subscriptions;
+- `serializationKey` enables decoded-only hydration serialization and is not
+  the runtime cache key;
+- `responseMode` changes the response and error shape.
+
+Keep secrets out of serialization keys, URL state, hydration payloads, and
+client-visible layers.
+
+## Define mutations and invalidation
+
+```ts
+export const updateProjectMutation = ApiClient.mutation("projects", "updateProject");
+
+const updateProject = useAtomSet(updateProjectMutation, { mode: "promise" });
+
+await updateProject({
+  params: { projectId },
+  payload: patch,
+  reactivityKeys: [...projectKeys.collection, ...projectKeys.project(projectId)],
+});
+```
+
+Successful mutations invalidate matching keys; failed mutations do not.
+Centralize reactivity-key constructors because mismatched strings fail silently.
+When one mutation affects several exact keys, flatten their arrays; an array
+containing key arrays registers those nested arrays as different keys.
+
+Exact array keys invalidate only exact matches. Record-form keys are
+hierarchical in current Effect v4 implementations: a property registers both
+its broad name and each `property:id` combination. Confirm this against the
+installed version before relying on it.
+
+Choose invalidation breadth from the server write:
+
+- invalidate an entity key when only its detail changed;
+- invalidate the collection when membership, ordering, totals, or filters can
+  change;
+- invalidate every affected namespace when a write crosses aggregates.
+
+Combine invalidation with manual refresh only when two requests are intended.
+Keep navigation, toasts, form reset, and presentation-level optimistic state
+with the initiating UI.
+
+## Use a direct client outside React
+
+```ts
+import { Effect } from "effect";
+import { FetchHttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiClient, HttpApiMiddleware } from "effect/unstable/httpapi";
+import { ApplicationApi, Authenticate } from "@app/domain";
+import { AccessToken, AccessTokenLive } from "./AccessToken";
+
+const AuthenticateClient = HttpApiMiddleware.layerClient(
+  Authenticate,
+  Effect.fn("AuthenticateClient")(function* ({ next, request }) {
+    const token = yield* AccessToken;
+    return yield* next(HttpClientRequest.bearerToken(request, token.value));
+  }),
+);
+
+const program = Effect.gen(function* () {
+  const client = yield* HttpApiClient.make(ApplicationApi, {
+    baseUrl: "https://api.example.com",
+  });
+  return yield* client.projects.getProject({ params: { projectId } });
+}).pipe(Effect.provide([FetchHttpClient.layer, AuthenticateClient, AccessTokenLive]));
+```
+
+Use the direct client in services, scripts, tests, and non-React applications.
+Provide every required contract middleware at the client composition root.
+Transform the underlying `HttpClient` once for non-contract headers, tracing,
+retry, or base behavior rather than repeating it at every call site.

package/skills/build-effect-apis/references/effect-atom-lifecycle.md

@@ -0,0 +1,78 @@
+# Effect Atom lifecycle
+
+Treat query atoms as shared read state and mutations as actions owned by an
+initiating UI or workflow. Choose registry scope, atom identity, retention,
+freshness, polling, and cancellation independently.
+
+## Registry and runtime scope
+
+`RegistryProvider` creates its registry on first render; later option changes do
+not rebuild it. Provider unmount schedules disposal after a short grace period,
+while moving or keying the provider changes the cache boundary. Place one
+provider around the application subtree that should share client state; nested
+or route-local providers create separate caches.
+
+The registry stores nodes, values, subscriptions, idle timers, and finalizers.
+An Atom runtime supplies Effect services, and `Atom.context({ memoMap })` lets
+several runtimes share layer construction. Create neither a registry nor a memo
+map per query or render. Keep request-specific authentication out of a
+process-global server memo map.
+
+## Stable identity and families
+
+Export fixed queries directly. Use `Atom.family` when a parameter selects the
+resource. Prefer a primitive family argument; give object keys deliberate Effect
+`Equal`/`Hash` semantics or reuse the same object. Calling a family with a stable
+primitive during render already returns its stable member; an extra `useMemo`
+does not improve identity.
+
+## Three independent clocks
+
+| Control                                         | Clock starts                 | Effect                                                                                  | It does not mean           |
+| ----------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------- | -------------------------- |
+| Registry/default idle TTL or query `timeToLive` | When the atom becomes unused | Retain the cached node until idle eviction                                              | The value remains fresh    |
+| `Atom.swr({ staleTime })`                       | At the latest success        | Revalidate stale data on configured mount/focus signals while showing the prior success | The node survives unmount  |
+| `Atom.withRefresh(interval)`                    | While its wrapper is mounted | Force periodic refresh until disposal                                                   | Fresh requests are skipped |
+
+Set retention long enough for the intended navigation/remount reuse window.
+`staleTime` cannot rescue an already evicted node. Manual refresh, invalidation,
+and polling are forceful and do not consult SWR freshness. Applying `keepAlive`
+to a polling wrapper intentionally keeps that polling lifetime alive.
+
+Atom registries are in-memory caches, not durable or shared storage. New tabs,
+hard reloads, processes, and providers have separate caches. Idle TTL is not a
+maximum-entry bound; finite TTLs are important for unbounded family keys.
+
+## React mounts and action ownership
+
+- `useAtomValue(atom)` subscribes for rendering;
+- `useAtomSet(atom)` mounts a writable atom and returns a setter;
+- `useAtom(atom)` subscribes and writes when one component owns both behaviors.
+
+Use `useAtom` instead of pairing `useAtomValue` and `useAtomSet` for the same
+atom in one component. The split form creates a value subscription plus a
+separate mount and obscures ownership.
+
+Unmount releases only that hook's subscription or mount. Registry eviction waits
+for remaining consumers and idle TTL, then runs node finalizers. Component
+unmount, registry eviction, and `Atom.Interrupt` are distinct events.
+
+Use `Atom.Interrupt` for explicit cancellation. A cleanup write publishes an
+interrupted `AsyncResult.Failure`; it is not passive unmount release, can run
+during React Strict Mode replay, and can cancel work owned by another consumer.
+
+Place a multi-request action in an owner that lives for the whole sequence. If
+navigation or disconnect must not leave a partially completed fan-out, use a
+stable workflow atom/service or one durable server-side command.
+
+## Keep aggregates stable
+
+`AsyncResult.all` returns the first non-success input, so an aggregate is only
+as reusable as its least-stable input. A newly allocated or evicted input
+returns to `Initial` and makes the aggregate appear reset even while other
+queries remain cached.
+
+Define every input as a module-scoped singleton or stable family member with
+compatible retention. Aggregate inside a derived atom so the registry owns
+recomputation; memoizing only the `AsyncResult.all` call does not repair an
+unstable input atom.

package/skills/build-effect-apis/references/effect-atom-testing.md

@@ -0,0 +1,74 @@
+# Deterministic Effect Atom testing
+
+Test cache policy below React first with `AtomRegistry.make()`. Add a React
+integration test for provider placement, hook behavior, browser-only SSR
+boundaries, hydration, or Strict Mode ownership.
+
+Use fake timers, a request counter, controllable Effects, and explicit mounts:
+
+```ts
+const registry = AtomRegistry.make({ defaultIdleTTL: 1_000 });
+const unmount = registry.mount(queryAtom);
+const first = registry.get(queryAtom);
+
+// Flush Effect work and advance the test runner's fake timers.
+
+unmount();
+```
+
+Use the repository's established `Effect.yieldNow` or test-clock pattern rather
+than wall-clock sleeps. Prefer installed APIs and predicates such as
+`AsyncResult.isSuccess`; use the cleanup returned by `registry.mount(atom)`.
+
+## Remount reuse
+
+1. Mount and resolve the query; assert request count `1`.
+2. Unmount, advance less than idle TTL, and remount the same atom identity.
+3. Assert cached success is immediately available and no fresh request occurs.
+
+## Stale refresh
+
+1. Resolve once through an SWR wrapper.
+2. Advance past `staleTime` but not idle TTL.
+3. Remount or emit the injected focus signal.
+4. Assert the previous success remains with `waiting: true`, then a second
+   success arrives and request count becomes `2`.
+5. Prove a fresh mount or focus signal does not request.
+
+## TTL eviction
+
+1. Resolve and unmount.
+2. Advance to just before TTL and assert reuse.
+3. Advance through TTL, flush disposal, and remount.
+4. Assert initial/waiting behavior and a new request.
+
+## Polling cleanup
+
+1. Mount the `Atom.withRefresh` wrapper and resolve once.
+2. Advance one interval and assert one forced refresh.
+3. Unmount, advance several intervals, and assert the counter stops changing.
+
+## Mutation invalidation
+
+1. Mount list and detail queries with explicit keys.
+2. Run a successful mutation and assert only intended queries refresh.
+3. Run a failed mutation and assert nothing invalidates.
+4. Dispose the queries and assert invalidation handlers are removed.
+
+## Strict Mode and action ownership
+
+Render the owner inside `StrictMode`. Prove development setup-cleanup replay
+does not write `Atom.Interrupt` or publish an interrupted failure before an
+explicit cancellation. For multi-request actions, unmount during the sequence
+and prove the chosen policy. If the atom is shared, prove unmounting one
+consumer does not cancel work still owned by another.
+
+## Aggregate stability
+
+Mount a route atom using `AsyncResult.all`, resolve every input, unmount, and
+remount inside the retention window. Assert the aggregate never returns to
+`Initial`. Then expire one input and prove that input causes the reset.
+
+For runtime/layer tests, seed `runtime.layer` through `RegistryProvider`
+`initialValues` with a deterministic test layer. Replace network services
+without changing the production atom graph.

package/skills/build-effect-apis/references/runtime-assembly.md

@@ -0,0 +1,56 @@
+# Standard runtime assembly
+
+Use this branch for conventional Node/Bun processes, generated documentation,
+and Web-standard handlers. Confirm platform package names against the installed
+versions.
+
+## Compose routes before choosing the runtime
+
+```ts
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { Layer } from "effect";
+import { HttpRouter, HttpServer } from "effect/unstable/http";
+import { HttpApiBuilder, HttpApiScalar } from "effect/unstable/httpapi";
+import { createServer } from "node:http";
+import { ApplicationApi } from "@app/domain/http";
+
+const ApplicationHttpLive = Layer.mergeAll(ProjectsHandlersLive, AuthenticateLive).pipe(
+  Layer.provide(ApplicationServicesLive),
+);
+
+const ApiRoutes = HttpApiBuilder.layer(ApplicationApi, {
+  openapiPath: "/openapi.json",
+}).pipe(Layer.provide(ApplicationHttpLive));
+
+const DocsRoute = HttpApiScalar.layer(ApplicationApi, { path: "/docs" });
+const AllRoutes = Layer.mergeAll(ApiRoutes, DocsRoute);
+```
+
+Build the typed API route and documentation route from the same contract. Merge
+raw routes here only when the API schema cannot represent their transport, and
+ensure they independently enforce equivalent identity and security behavior.
+
+## Run a long-lived server
+
+```ts
+const HttpServerLive = HttpRouter.serve(AllRoutes).pipe(
+  Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })),
+);
+
+Layer.launch(HttpServerLive).pipe(NodeRuntime.runMain);
+```
+
+Use the matching platform server layer for Bun or another runtime. Keep the
+platform choice at this composition root.
+
+## Export a Web handler
+
+```ts
+export const { handler, dispose } = HttpRouter.toWebHandler(
+  AllRoutes.pipe(Layer.provide(HttpServer.layerServices)),
+);
+```
+
+Use the Web handler for serverless and framework adapters that accept standard
+`Request` and `Response` values. Preserve and call `dispose` when the host has a
+lifecycle hook; do not recreate the handler and its runtime for every request.

package/skills/build-effect-apis/references/server-and-middleware.md

@@ -0,0 +1,174 @@
+# Server handlers and middleware
+
+Implement the shared contract with group handlers, application services, and
+layers. Confirm names against the installed Effect version; examples here use
+the Effect v4 `effect/unstable/httpapi` surface.
+
+- [Implement thin group handlers](#implement-thin-group-handlers)
+- [Declare security middleware in the shared contract](#declare-security-middleware-in-the-shared-contract)
+- [Implement security middleware on the server](#implement-security-middleware-on-the-server)
+- [Assemble layers at the runtime edge](#assemble-layers-at-the-runtime-edge)
+- [Use response escape hatches deliberately](#use-response-escape-hatches-deliberately)
+
+## Implement thin group handlers
+
+Resolve application services once in the group builder, then map every endpoint
+identifier to one handler. Use `Effect.fn` for callbacks that return Effects.
+
+```ts
+import { Effect } from "effect";
+import { HttpApiBuilder } from "effect/unstable/httpapi";
+import { ApplicationApi } from "@app/domain/http";
+import { Projects } from "../services/Projects";
+
+export const ProjectsHandlersLive = HttpApiBuilder.group(
+  ApplicationApi,
+  "projects",
+  Effect.fn("ProjectsApi.handlers")(function* (handlers) {
+    const projects = yield* Projects;
+
+    return handlers
+      .handle("listProjects", () => projects.list().pipe(Effect.orDie))
+      .handle("getProject", ({ params }) =>
+        projects
+          .get(params.projectId)
+          .pipe(Effect.catchReasons("ProjectsError", { ProjectNotFound: Effect.fail }, Effect.die)),
+      );
+  }),
+);
+```
+
+Handlers receive decoded `params`, `query`, `headers`, and `payload`. Check
+cross-field invariants at this boundary when schemas cannot express them, then
+call one application workflow. Keep persistence, transactions, retries, and
+multi-service orchestration in services.
+
+Reconcile the service error channel with the endpoint contract here. Use
+`Effect.orDie` when an endpoint declares no service failures. Use
+`Effect.catchReason`, `Effect.catchReasons`, or `Effect.unwrapReason` when an
+application service wraps domain reasons: re-fail only reasons declared by the
+endpoint and turn unexpected infrastructure or invariant failures into defects.
+Finish when each handler's expected error type is a subset of the endpoint's
+declared error schema.
+
+## Declare security middleware in the shared contract
+
+Keep the middleware declaration in the shared contract package so server,
+OpenAPI, and generated clients see the same requirement. Keep its implementation
+out of that package.
+
+```ts
+// packages/domain/src/http/authorization.ts
+import { Context, Schema } from "effect";
+import { HttpApiGroup, HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+
+export class CurrentActor extends Context.Service<CurrentActor, { readonly id: string }>()(
+  "app/CurrentActor",
+) {}
+
+export class Unauthorized extends Schema.TaggedError<Unauthorized>()(
+  "Unauthorized",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+export class Authenticate extends HttpApiMiddleware.Service<
+  Authenticate,
+  {
+    readonly provides: CurrentActor;
+    readonly requires: never;
+  }
+>()("app/Authenticate", {
+  requiredForClient: true,
+  security: { bearer: HttpApiSecurity.bearer },
+  error: Unauthorized,
+}) {}
+
+export const ProjectsApi = HttpApiGroup.make("projects")
+  .add(GetProjectEndpoint, ListProjectsEndpoint)
+  .middleware(Authenticate)
+  .prefix("/projects");
+```
+
+`requiredForClient` makes the generated client require a matching client-side
+middleware layer. The security declaration also owns credential decoding and
+OpenAPI security metadata; do not manually decode an `Authorization` header for
+this case.
+
+## Implement security middleware on the server
+
+A security middleware implementation is keyed by the names in its `security`
+object. It can use server-only services without leaking them into clients.
+
+```ts
+// apps/api/src/http/Authenticate.ts
+import { Effect, Layer, Redacted } from "effect";
+import { Authenticate, CurrentActor, Unauthorized } from "@app/domain/http";
+import { Actors } from "../services/Actors";
+
+export const AuthenticateLive = Layer.effect(
+  Authenticate,
+  Effect.gen(function* () {
+    const actors = yield* Actors;
+
+    return Authenticate.of({
+      bearer: Effect.fn("Authenticate.bearer")(function* (httpEffect, { credential }) {
+        const actor = yield* actors
+          .authenticate(Redacted.value(credential))
+          .pipe(
+            Effect.catch(() => Effect.fail(new Unauthorized({ message: "Invalid bearer token" }))),
+          );
+
+        return yield* Effect.provideService(httpEffect, CurrentActor, actor);
+      }),
+    });
+  }),
+);
+```
+
+Use ordinary `HttpApiMiddleware.Service` implementations for request logging,
+tenancy, correlation IDs, or other cross-cutting work that is not a declared
+security scheme. Those implementations may access `HttpServerRequest`, but they
+must decode raw headers, cookies, and external values before providing services.
+When middleware uses `requires` and `provides`, confirm ordering from the
+installed docs: the outer middleware that requires a service is attached before
+the inner middleware that provides it.
+
+Every error a middleware can return belongs in its `error` schema. Keep the
+server layer separate from the shared declaration so importing the contract
+never pulls secrets, repositories, or platform services into a client bundle.
+
+## Assemble layers at the runtime edge
+
+```ts
+const ProjectsHandlersProvided = ProjectsHandlersLive.pipe(Layer.provide(ApplicationServicesLive));
+
+const ApiLive = HttpApiBuilder.layer(ApplicationApi, {
+  openapiPath: "/api/openapi.json",
+}).pipe(
+  Layer.provide(ProjectsHandlersProvided),
+  Layer.provide(AuthenticateLive),
+  Layer.provideMerge(HttpRuntimePrerequisitesLive),
+);
+```
+
+The exact HTTP platform/router/server layers vary by runtime. Keep that wiring
+at the entrypoint, provide all group and middleware layers, and let the type
+system expose missing requirements. Verify that the OpenAPI path composes with
+any API prefix as intended.
+
+For a conventional Node/Bun process, generated docs route, or serverless web
+handler, read [runtime-assembly.md](runtime-assembly.md).
+
+Transport-wide middleware such as CORS may wrap the final HTTP application.
+Keep API middleware for contract-visible behavior and runtime HTTP middleware
+for concerns that also apply to raw or non-API routes.
+
+## Use response escape hatches deliberately
+
+Return typed success values and declared errors for ordinary endpoints. Use
+`HttpServerResponse` when the boundary must pass through an upstream response,
+redirect, set cookies, stream, or control a non-default success status or body.
+Use Effect request and cookie APIs to parse boundary state. Reserve unsafe JSON
+response constructors for values whose safety is established elsewhere; encode
+ordinary typed 4xx failures through the endpoint's declared error schemas.

package/skills/build-effect-apis/references/shared-contracts.md

@@ -0,0 +1,108 @@
+# Shared contracts
+
+Use a runtime-neutral domain package as the protocol boundary shared by the
+server and every typed client.
+
+## Package shape
+
+```text
+packages/domain/
+├── package.json
+└── src/
+    ├── models/
+    │   ├── ids.ts
+    │   ├── errors.ts
+    │   └── views.ts
+    └── http/
+        ├── endpoints/
+        │   ├── get-project.ts
+        │   └── update-project.ts
+        ├── authorization.ts
+        ├── project-api.ts
+        ├── application-api.ts
+        └── index.ts
+```
+
+Export the root API, contract-visible middleware declarations, and any genuinely
+reusable schemas. Keep middleware implementations, server handlers, React,
+database clients, secrets, platform bindings, and runtime layers out of this
+package. A workspace export map can expose `./http`, `./models`, and endpoint
+subpaths when consumers need them.
+
+## Model the wire
+
+Use schemas for every external value. Prefer reusable named classes for DTOs,
+branded scalar schemas for identifiers, and serializable tagged errors with
+HTTP status metadata for expected failures.
+
+```ts
+import { Schema } from "effect";
+import { HttpApiSchema } from "effect/unstable/httpapi";
+
+export const ProjectId = Schema.String.pipe(Schema.brand("ProjectId"));
+export type ProjectId = typeof ProjectId.Type;
+
+export class ProjectDto extends Schema.Class<ProjectDto>("ProjectDto")({
+  id: ProjectId,
+  name: Schema.NonEmptyString,
+}) {}
+
+export class ProjectNotFoundError extends Schema.TaggedError<ProjectNotFoundError>()(
+  "ProjectNotFoundError",
+  { id: ProjectId },
+) {}
+
+export const ProjectNotFound = ProjectNotFoundError.pipe(HttpApiSchema.status("NotFound"));
+```
+
+Keep success schemas limited to successful values. Put every expected 4xx/5xx
+failure in `error`; defects remain defects. Reuse a tuple of transport errors
+only when the same set is genuinely standard across endpoints.
+
+Make DTOs describe the wire exactly. If clients receive `id`, expose `id` even
+when a persistence model uses `publicId`; map between them in a small boundary
+function. Keep endpoint-specific request DTOs beside their endpoint and move a
+DTO into shared models only when multiple contracts reuse the same concept.
+
+## Define one endpoint per file
+
+An endpoint declares the complete request and response contract inline.
+
+```ts
+import { HttpApiEndpoint } from "effect/unstable/httpapi";
+import { ProjectDto, ProjectId, ProjectNotFound } from "../../models";
+import { RequestHeaders } from "../headers";
+
+export const GetProjectEndpoint = HttpApiEndpoint.get("getProject", "/projects/:projectId", {
+  params: { projectId: ProjectId },
+  headers: RequestHeaders,
+  success: ProjectDto,
+  error: ProjectNotFound,
+});
+```
+
+Use the operation identifier as a stable protocol name: handlers and generated
+clients address it directly. Represent optional query values with the installed
+version's optional schema operator, such as `Schema.optionalKey`.
+
+If headers use `Schema.Class`, generated client input may require a constructed
+class instance rather than a structurally similar object. Encode a representative
+instance in a test so this contract stays explicit.
+
+## Compose groups and the root
+
+```ts
+import { HttpApi, HttpApiGroup } from "effect/unstable/httpapi";
+import { GetProjectEndpoint, UpdateProjectEndpoint } from "./endpoints";
+
+export const ProjectsApi = HttpApiGroup.make("projects")
+  .add(GetProjectEndpoint, UpdateProjectEndpoint)
+  .prefix("/projects");
+
+export const ApplicationApi = HttpApi.make("application").add(ProjectsApi).prefix("/api");
+```
+
+Group and root files compose; endpoint files specify. Re-export through index
+files so server and clients import the same `ApplicationApi` value. A contract
+change is complete only after all affected handlers, callers, tests, and
+OpenAPI output agree with it.