@effect-app/infra 4.0.0-beta.25 → 4.0.0-beta.250

package/src/setupRequest.ts

@@ -0,0 +1,135 @@
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
+import * as Option from "effect-app/Option"
+import { LocaleRef, RequestContext, spanAttributes } from "effect-app/RequestContext"
+import { NonEmptyString255 } from "effect-app/Schema"
+import { ContextMapContainer } from "effect-app/Store"
+import * as Tracer from "effect/Tracer"
+import { SqlClient } from "effect/unstable/sql"
+import { storeId } from "./Store/Memory.js"
+
+const withSqlTransaction = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.serviceOption(SqlClient.SqlClient).pipe(
+    Effect.flatMap(Option.match({
+      onNone: () => self,
+      onSome: (sql) => sql.withTransaction(self).pipe(Effect.orDie)
+    }))
+  )
+
+export const getRequestContext = Effect
+  .all({
+    span: Effect.currentSpan.pipe(Effect.orDie),
+    locale: LocaleRef,
+    namespace: storeId
+  })
+  .pipe(
+    Effect.map(({ locale, namespace, span }) =>
+      RequestContext.make({
+        span: Tracer.externalSpan(span),
+        locale,
+        namespace,
+        name: NonEmptyString255(span.name)
+      })
+    )
+  )
+
+export const getRC = Effect.all({
+  locale: LocaleRef,
+  namespace: storeId
+})
+
+const withRequestSpan = (name = "request", options?: Tracer.SpanOptions) => <R, E, A>(f: Effect.Effect<A, E, R>) =>
+  Effect.andThen(
+    getRC,
+    (ctx) =>
+      f.pipe(
+        Effect.withSpan(name, {
+          ...options,
+          attributes: { ...spanAttributes({ ...ctx, name: NonEmptyString255(name) }), ...options?.attributes }
+        }, {
+          captureStackTrace: options?.captureStackTrace ?? false
+        }),
+        // TODO: false
+        // request context info is picked up directly in the logger for annotations.
+        Effect.withLogSpan(name)
+      )
+  )
+
+export interface SetupRequestOptions {
+  readonly withTransaction?: boolean
+}
+
+// Build `layer` against the ambient (request) scope rather than a sub-scope of the
+// returned Effect. Required when the returned value is a streaming HttpServerResponse:
+// the response body keeps producing chunks (and using layer-provided state) after the
+// Effect returns, so a sub-scope would close too early and run finalizers mid-stream.
+export const provideOnRequestScope =
+  <ROut, E2, RIn>(layer: Layer.Layer<ROut, E2, RIn>) => <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    Effect.gen(function*() {
+      const requestScope = yield* Effect.scope
+      // Fresh MemoMap per request: `Layer.buildWithScope` would otherwise reuse
+      // the ambient MemoMap living on the HTTP server fiber, sharing the built
+      // value (e.g. ContextMap) across every request handled by that server.
+      const memoMap = yield* Layer.makeMemoMap
+      const ctx = yield* Layer.buildWithMemoMap(layer, memoMap, requestScope)
+      return yield* Effect.provide(self, ctx)
+    })
+
+export const setupRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self
+      .pipe(
+        options?.withTransaction === true ? withSqlTransaction : (_) => _,
+        withRequestSpan(name, options),
+        Effect.provide(ContextMapContainer.layer, { local: true })
+      )
+
+// Streaming variant: binds ContextMapContainer to the ambient (request) scope so its
+// finalizer (clear()) runs only after the response body is fully drained, not when the
+// outer Effect returns its HttpServerResponse value. Use for handlers that return a
+// streaming HttpServerResponse (e.g. SSE) — see RequestContextMiddleware for context.
+export const setupStreamingRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self.pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      provideOnRequestScope(ContextMapContainer.layer)
+    )
+
+// TODO: consider integrating Effect.withParentSpan
+export function setupRequestContext<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  options?: SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    ContextMapContainer.layer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(requestContext.name),
+      Effect.provide(layer, { local: true })
+    )
+}
+
+export function setupRequestContextWithCustomSpan<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  name: string,
+  options?: Tracer.SpanOptions & SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    ContextMapContainer.layer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      Effect.provide(layer, { local: true })
+    )
+}

package/src/test.ts

@@ -1,4 +1,4 @@
-import { S } from "effect-app"
+import * as S from "effect-app/Schema"
 import { copy } from "effect-app/utils"
 import { generate } from "./arbs.js"
 
@@ -16,7 +16,7 @@ export const createRandomInstance = <A extends object, I, R>(s: S.Codec<A, I, R>
 /**
  * Like `createRandomInstance`, but takes encoded values rather than decoded ones.
  */
-export const createRandomInstanceI = <A extends object, I>(s: S.Codec<A, I, never> & { fields: S.Struct.Fields }) => {
+export const createRandomInstanceI = <A extends object, I>(s: S.Codec<A, I> & { fields: S.Struct.Fields }) => {
   const gen = generate(S.toArbitrary(s))
   const encode = S.encodeSync(s)
   const decode = S.decodeSync(s)

package/test/auth.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as Effect from "effect-app/Effect"
+import { HttpHeaders } from "effect-app/http"
+import { SignJWT } from "jose"
+import { checkJWTI, InvalidRequestError, InvalidTokenError, UnauthorizedError } from "../src/internal/auth.js"
+
+const issuer = "https://issuer.example.com/"
+const audience = "effect-app"
+const secret = "test-secret-test-secret-test-secret"
+
+const makeToken = () =>
+  new SignJWT({ scope: "read:all" })
+    .setProtectedHeader({ alg: "HS256", typ: "at+jwt" })
+    .setIssuer(issuer)
+    .setAudience(audience)
+    .setIssuedAt()
+    .setExpirationTime("10m")
+    .sign(new TextEncoder().encode(secret))
+
+describe("checkJWTI", () => {
+  it.effect(
+    "validates a bearer token from headers",
+    Effect.fnUntraced(function*() {
+      const token = yield* Effect.promise(() => makeToken())
+
+      yield* checkJWTI({
+        audience,
+        issuer,
+        secret,
+        strict: true,
+        tokenSigningAlg: "HS256"
+      })(HttpHeaders.fromRecordUnsafe({ authorization: `Bearer ${token}` }))
+    })
+  )
+
+  it.effect(
+    "fails on malformed authorization headers",
+    Effect.fnUntraced(function*() {
+      const error = yield* Effect.flip(
+        checkJWTI({
+          audience,
+          issuer,
+          secret,
+          tokenSigningAlg: "HS256"
+        })(HttpHeaders.fromRecordUnsafe({ authorization: "Basic abc" }))
+      )
+
+      expect(error).toBeInstanceOf(InvalidRequestError)
+      expect(error.status).toBe(400)
+    })
+  )
+
+  it.effect(
+    "fails when the token is missing",
+    Effect.fnUntraced(function*() {
+      const error = yield* Effect.flip(
+        checkJWTI({
+          audience,
+          issuer,
+          secret,
+          tokenSigningAlg: "HS256"
+        })(HttpHeaders.empty)
+      )
+
+      expect(error).toBeInstanceOf(UnauthorizedError)
+      expect(error.status).toBe(401)
+    })
+  )
+
+  it.effect(
+    "allows missing tokens when auth is optional",
+    Effect.fnUntraced(function*() {
+      yield* checkJWTI({
+        audience,
+        authRequired: false,
+        issuer,
+        secret,
+        tokenSigningAlg: "HS256"
+      })(HttpHeaders.empty)
+    })
+  )
+
+  it.effect(
+    "fails when the token signature is invalid",
+    Effect.fnUntraced(function*() {
+      const token = yield* Effect.promise(() => makeToken())
+
+      const error = yield* Effect.flip(
+        checkJWTI({
+          audience,
+          issuer,
+          secret: "wrong-secret-wrong-secret-wrong-secret",
+          tokenSigningAlg: "HS256"
+        })(HttpHeaders.fromRecordUnsafe({ authorization: `Bearer ${token}` }))
+      )
+
+      expect(error).toBeInstanceOf(InvalidTokenError)
+      expect(error.status).toBe(401)
+    })
+  )
+})

package/test/contextProvider.test.ts

@@ -1,12 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
 import { expectTypeOf, it } from "@effect/vitest"
-import { Effect, Layer, Scope, ServiceMap } from "effect-app"
-import { ContextProvider, mergeContextProviders, MergedContextProvider } from "../src/api/ContextProvider.js"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
+import * as Scope from "effect/Scope"
+import { ContextProvider, mergeContextProviders, MergedContextProvider } from "../src/ContextProvider.js"
 import { CustomError1, Some, SomeElse, SomeService } from "./fixtures.js"
 
 // @effect-diagnostics-next-line missingEffectServiceDependency:off
-class MyContextProvider extends ServiceMap.Service<MyContextProvider>()(
+class MyContextProvider extends Context.Service<MyContextProvider>()(
   "MyContextProvider",
   {
     make: Effect.gen(function*() {
@@ -20,7 +23,7 @@ class MyContextProvider extends ServiceMap.Service<MyContextProvider>()(
         yield* Effect.logInfo("MyContextProviderGen", "this is a generator")
         yield* Effect.succeed("this is a generator")
 
-        return Some.serviceMap({ a: 1 }) 
+        return Some.context({ a: 1 })
       })
     })
   }
@@ -28,7 +31,7 @@ class MyContextProvider extends ServiceMap.Service<MyContextProvider>()(
   static readonly Default = Layer.effect(this, this.make)
 }
 
-class MyContextProvider2 extends ServiceMap.Service<MyContextProvider2>()(
+class MyContextProvider2 extends Context.Service<MyContextProvider2>()(
   "MyContextProvider2",
   {
     make: Effect.gen(function*() {
@@ -37,7 +40,7 @@ class MyContextProvider2 extends ServiceMap.Service<MyContextProvider2>()(
       return Effect.gen(function*() {
         // we test without dependencies, so that we end up with an R of never.
 
-        return SomeElse.serviceMap({ b: 2 })
+        return SomeElse.context({ b: 2 })
       })
     })
   }
@@ -45,7 +48,7 @@ class MyContextProvider2 extends ServiceMap.Service<MyContextProvider2>()(
   static readonly Default = Layer.effect(this, this.make)
 }
 
-class MyContextProvider2Gen extends ServiceMap.Service<MyContextProvider2Gen>()(
+class MyContextProvider2Gen extends Context.Service<MyContextProvider2Gen>()(
   "MyContextProvider2Gen",
   {
     make: Effect.gen(function*() {
@@ -54,7 +57,7 @@ class MyContextProvider2Gen extends ServiceMap.Service<MyContextProvider2Gen>()(
       return function*() {
         // we test without dependencies, so that we end up with an R of never
 
-        return SomeElse.serviceMap({ b: 2 })
+        return SomeElse.context({ b: 2 })
       }
     })
   }
@@ -63,7 +66,7 @@ class MyContextProvider2Gen extends ServiceMap.Service<MyContextProvider2Gen>()(
 }
 
 // @effect-diagnostics-next-line missingEffectServiceDependency:off
-class MyContextProviderGen extends ServiceMap.Service<MyContextProviderGen>()(
+class MyContextProviderGen extends Context.Service<MyContextProviderGen>()(
   "MyContextProviderGen",
   {
     make: Effect.gen(function*() {
@@ -77,7 +80,7 @@ class MyContextProviderGen extends ServiceMap.Service<MyContextProviderGen>()(
         yield* Effect.logInfo("MyContextProviderGen", "this is a generator")
         yield* Effect.succeed("this is a generator")
 
-        return Some.serviceMap({ a: 1 })
+        return Some.context({ a: 1 })
       }
     })
   }
@@ -100,7 +103,7 @@ export const someContextProvider = ContextProvider({
       // currently the effectful context provider cannot trigger an error when building the per request context
       // if (Math.random() > 0.5) return yield* new CustomError2()
 
-      return Some.serviceMap({ a: 1 })
+      return Some.context({ a: 1 })
     })
   })
 })
@@ -119,7 +122,7 @@ export const someContextProviderGen = ContextProvider({
       // currently the effectful context provider cannot trigger an error when building the per request context
       // if (Math.random() > 0.5) return yield* new CustomError2()
 
-      return Some.serviceMap({ a: 1 })
+      return Some.context({ a: 1 })
     }
   })
 })

package/test/controller.test.ts

@@ -1,16 +1,20 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 /* eslint-disable @typescript-eslint/no-unsafe-member-access */
-import { type MakeContext, type MakeErrors, makeRouter } from "@effect-app/infra/api/routing"
+import { type MakeContext, type MakeErrors, makeRouter } from "@effect-app/infra/routing"
 import { expect, expectTypeOf, it } from "@effect/vitest"
-import { Effect, Layer, S, Scope, ServiceMap } from "effect-app"
 import { InvalidStateError, makeRpcClient, UnauthorizedError } from "effect-app/client"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
 import { DefaultGenericMiddlewares } from "effect-app/middleware"
 import * as RpcX from "effect-app/rpc"
 import { MiddlewareMaker } from "effect-app/rpc"
+import * as S from "effect-app/Schema"
 import { TypeTestId } from "effect-app/TypeTest"
+import * as Scope from "effect/Scope"
 import { type RpcSerialization } from "effect/unstable/rpc"
-import { DefaultGenericMiddlewaresLive, DevModeMiddlewareLive } from "../src/api/routing/middleware.js"
-import { sort } from "../src/api/routing/tsort.js"
+import { DefaultGenericMiddlewaresLive, DevModeMiddlewareLive } from "../src/routing/middleware.js"
+import { sort } from "../src/routing/tsort.js"
 import { AllowAnonymous, AllowAnonymousLive, CustomError1, RequestContextMap, RequireRoles, RequireRolesLive, Some, SomeElse, SomeService, Test, TestLive } from "./fixtures.js"
 
 class MyContextProvider extends RpcX.RpcMiddleware.Tag<MyContextProvider, {
@@ -99,7 +103,7 @@ class MyContextProvider2
 
 //
 
-class Str extends ServiceMap.Service<Str, "str">()("str") {}
+class Str extends Context.Service<Str, "str">()("str") {}
 
 export class BogusMiddleware extends RpcX.RpcMiddleware.Tag<BogusMiddleware>()("BogusMiddleware") {
   static Default = Layer.make(this, {
@@ -188,13 +192,6 @@ const middlewareQuater = MiddlewareMaker
 
 expectTypeOf(middleware["Service"]).toEqualTypeOf<typeof middlewareQuater["Service"]>()
 
-const middleware2 = MiddlewareMaker
-  .Tag()("middleware", RequestContextMap)
-  .middleware(MyContextProvider)
-  .middleware(RequireRoles, Test)
-  .middleware(AllowAnonymous)
-  .middleware(...DefaultGenericMiddlewares, BogusMiddleware, MyContextProvider2)
-
 export const middleware3 = MiddlewareMaker
   .Tag()("middleware", RequestContextMap)
   .middleware(...genericMiddlewares)
@@ -202,14 +199,17 @@ export const middleware3 = MiddlewareMaker
   .middleware(Test)
   .middleware(BogusMiddleware)
 
-export const { TaggedRequest: Req } = makeRpcClient(RequestContextMap)
+export const { TaggedRequestFor } = makeRpcClient(middleware)
+const Req = TaggedRequestFor("Something")
+const Command = Req.Command
+const Query = Req.Query
 
-export class Eff extends Req<Eff>()("Eff", {}, { success: S.Void }) {}
-export class Gen extends Req<Gen>()("Gen", {}) {}
+export class Eff extends Command<Eff>()("Eff", {}, { success: S.Void }) {}
+export class Gen extends Command<Gen>()("Gen", {}) {}
 
 expectTypeOf(Eff.error).toEqualTypeOf<typeof Gen.error>()
 
-export class DoSomething extends Req<DoSomething>()("DoSomething", {
+export class DoSomething extends Command<DoSomething>()("DoSomething", {
   id: S.String
 }, { success: S.Void }) {}
 
@@ -227,20 +227,20 @@ export class DoSomething extends Req<DoSomething>()("DoSomething", {
 //   )
 // )
 
-export class GetSomething extends Req<GetSomething>()("GetSomething", {
+export class GetSomething extends Query<GetSomething>()("GetSomething", {
   id: S.String
-}, { success: S.String }) {}
+}, { success: S.String, error: UnauthorizedError }) {}
 
-export class GetSomething2 extends Req<GetSomething2>()("GetSomething2", {
+export class GetSomething2 extends Query<GetSomething2>()("GetSomething2", {
   id: S.String
-}, { success: S.NumberFromString }) {}
+}, { success: S.FiniteFromString }) {}
 
-const Something = { Eff, Gen, DoSomething, GetSomething, GetSomething2, meta: { moduleName: "Something" as const } }
+const Something = { Eff, Gen, DoSomething, GetSomething, GetSomething2 }
 
 // const client = ApiClientFactory.makeFor(Layer.empty)(Something)
 // client.pipe(Effect.map(c => c.DoSomething.name))
 
-export class SomethingService extends ServiceMap.Service<SomethingService>()(
+export class SomethingService extends Context.Service<SomethingService>()(
   "SomethingService",
   {
     make: Effect.gen(function*() {
@@ -260,7 +260,7 @@ declare const a: {
   (opt: { b: 3 }): void
 }
 
-export class SomethingRepo extends ServiceMap.Service<SomethingRepo>()(
+export class SomethingRepo extends Context.Service<SomethingRepo>()(
   "SomethingRepo",
   {
     make: Effect.gen(function*() {
@@ -273,7 +273,7 @@ export class SomethingRepo extends ServiceMap.Service<SomethingRepo>()(
   static Default = Layer.effect(this, this.make).pipe(Layer.provide(SomethingService.Default))
 }
 
-export class SomethingService2 extends ServiceMap.Service<SomethingService2>()(
+export class SomethingService2 extends Context.Service<SomethingService2>()(
   "SomethingService2",
   {
     make: Effect.gen(function*() {
@@ -284,13 +284,9 @@ export class SomethingService2 extends ServiceMap.Service<SomethingService2>()(
   static Default = Layer.effect(this, this.make)
 }
 
-export const { Router, matchAll } = makeRouter(
-  middleware
-)
+export const { Router, matchAll } = makeRouter(middleware.Default)
 
-export const r2 = makeRouter(
-  Object.assign(middleware2, { Default: middleware2.layer.pipe(Layer.provide([...MiddlewaresLive])) })
-)
+export const r2 = makeRouter(middleware.Default)
 
 const router = Router(Something)({
   dependencies: [
@@ -348,7 +344,7 @@ const router = Router(Something)({
         }
       },
       GetSomething2: {
-        raw: Some.use(() => Effect.succeed("12"))
+        raw: () => Some.use(() => Effect.succeed("12"))
       }
     })
   }
@@ -413,7 +409,7 @@ const router2 = r2.Router(Something)({
         }
       },
       GetSomething2: {
-        raw: Some.use(() => Effect.succeed("12"))
+        raw: () => Some.use(() => Effect.succeed("12"))
       }
     })
   }

package/test/cosmos-query.test.ts

@@ -0,0 +1,159 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { and, computed, make, projectComputed, relation, toFilter, where } from "effect-app/Model/query"
+import * as S from "effect-app/Schema"
+import { describe, expect, it } from "vitest"
+import { buildWhereCosmosQuery3 } from "../src/Store/Cosmos/query.js"
+
+class Order extends S.Class<Order>("Order")({
+  id: S.String,
+  packages: S.Array(S.Struct({ id: S.String, weight: S.Finite }))
+}) {}
+
+type OrderEnc = S.Codec.Encoded<typeof Order>
+
+// Length projection via `relation(...).length()` should emit a scalar
+// ARRAY_LENGTH expression rather than pulling (or reshaping) the array.
+describe("cosmos query projection: array length", () => {
+  it("projects packages length via ARRAY_LENGTH", () => {
+    const q = make<OrderEnc>().pipe(
+      projectComputed(
+        S.Struct({ id: S.String, packageCount: S.NonNegativeInt }),
+        computed({ packageCount: relation<OrderEnc>("packages").length() })
+      )
+    )
+
+    const ir = toFilter(q as any, Order as any)
+
+    const result = buildWhereCosmosQuery3(
+      "id",
+      ir.filter ?? [],
+      "Orders",
+      {},
+      ir.select as any
+    )
+
+    expect(result.query).toMatch(/ARRAY_LENGTH\(f(?:\.packages|\["packages"\])\)/)
+    expect(result.query).toContain("AS packageCount")
+    // Must not pull the full array nor reshape via subquery
+    expect(result.query).not.toMatch(/ARRAY\s*\(\s*SELECT[^)]*FROM\s+t\s+in\s+f[\.\["]/i)
+    expect(result.query).not.toMatch(/SELECT VALUE COUNT/)
+  })
+})
+
+// Regression: `relation-every` previously walked its filter twice (once for the
+// shared `where` variable, once for the NOT-EXISTS branch), double-bumping the
+// shared `i` counter and shifting every subsequent @v index against the bound
+// params array. Verify each filter element binds exactly one parameter and that
+// @v indices in the emitted SQL line up with the bindings.
+describe("cosmos query projection: relation-every parameter binding", () => {
+  class Item extends S.Class<Item>("Item")({
+    state: S.Struct({ _tag: S.Literals(["initial", "picking", "picked", "packed"]) })
+  }) {}
+  class DN extends S.Class<DN>("DN")({
+    id: S.String,
+    state: S.Struct({
+      _tag: S.Literals(["initial", "valid", "packed", "closed"]),
+      at: S.String
+    }),
+    items: S.Array(Item)
+  }) {}
+  type DNEnc = S.Codec.Encoded<typeof DN>
+
+  it("binds @v indices contiguously across every + main filter", () => {
+    const q = make<DNEnc>().pipe(
+      where("state.at", "gte", "2026-05-01T00:00:00.000Z"),
+      and("state._tag", "neq", "closed"),
+      projectComputed(
+        S.Struct({
+          id: S.String,
+          allItemsPicked: S.Boolean,
+          allItemsPacked: S.Boolean
+        }),
+        computed({
+          allItemsPicked: relation<DNEnc>("items").every(where("state._tag", "picked")),
+          allItemsPacked: relation<DNEnc>("items").every(where("state._tag", "packed"))
+        })
+      )
+    )
+
+    const ir = toFilter(q as any, DN as any)
+    const result = buildWhereCosmosQuery3("id", ir.filter ?? [], "DN", {}, ir.select as any)
+
+    // Each filter element binds exactly one parameter: 2 every filters + 2 main filter = 4.
+    expect(result.parameters).toHaveLength(4)
+    expect(result.parameters.map((_) => _.value)).toEqual([
+      "picked",
+      "packed",
+      "2026-05-01T00:00:00.000Z",
+      "closed"
+    ])
+
+    // SQL must reference exactly @v0..@v3 in order, no gaps, no overruns.
+    const refs = [...result.query.matchAll(/@v\d+/g)].map((m) => m[0])
+    expect(refs).toEqual(["@v0", "@v1", "@v2", "@v3"])
+  })
+})
+
+describe("cosmos query: aggregate (GROUP BY + agg functions)", () => {
+  it("generates GROUP BY and SUM(IIF(...)) for agg-count-when", () => {
+    const result = buildWhereCosmosQuery3(
+      "id",
+      [],
+      "Orders",
+      {},
+      [
+        { key: "city", path: "address.city" },
+        {
+          key: "activeCount",
+          aggregate: {
+            _tag: "agg-count-when",
+            filter: [{ t: "where", path: "status", op: "eq", value: "active" }]
+          }
+        },
+        { key: "total", aggregate: { _tag: "agg-count" } }
+      ] as any
+    )
+
+    expect(result.query).toContain("GROUP BY")
+    expect(result.query).toContain("SUM(IIF(")
+    expect(result.query).toContain("COUNT(1) AS total")
+    expect(result.query).toContain("AS city")
+    expect(result.parameters[0]!.value).toBe("active")
+  })
+
+  it("generates agg-sum / agg-min / agg-max expressions", () => {
+    const result = buildWhereCosmosQuery3(
+      "id",
+      [],
+      "Orders",
+      {},
+      [
+        { key: "dept", path: "dept" },
+        { key: "totalSalary", aggregate: { _tag: "agg-sum", field: "salary" } },
+        { key: "minSalary", aggregate: { _tag: "agg-min", field: "salary" } },
+        { key: "maxSalary", aggregate: { _tag: "agg-max", field: "salary" } }
+      ] as any
+    )
+
+    expect(result.query).toContain(`SUM(f["salary"]) AS totalSalary`)
+    expect(result.query).toContain(`MIN(f["salary"]) AS minSalary`)
+    expect(result.query).toContain(`MAX(f["salary"]) AS maxSalary`)
+    expect(result.query).toMatch(/GROUP BY f(?:\.dept|\["dept"\])/)
+  })
+
+  it("generates correct GROUP BY for nested path field", () => {
+    const result = buildWhereCosmosQuery3(
+      "id",
+      [],
+      "Orders",
+      {},
+      [
+        { key: "city", path: "address.city" },
+        { key: "count", aggregate: { _tag: "agg-count" } }
+      ] as any
+    )
+
+    // Must GROUP BY the nested path in Cosmos access notation
+    expect(result.query).toMatch(/GROUP BY f(?:\.address\.city|\["address"\]\["city"\])/)
+  })
+})

package/test/dist/auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.test.d.ts","sourceRoot":"","sources":["../auth.test.ts"],"names":[],"mappings":""}

package/test/dist/contextProvider.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contextProvider.test.d.ts","sourceRoot":"","sources":["../contextProvider.test.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,IAAI,EAAY,WAAW,EAAE,MAAM,eAAe,CAAA;AAkFzE,eAAO,MAAM,mBAAmB;;CAkB9B,CAAA;AACF,eAAO,MAAM,sBAAsB;;CAkBjC,CAAA"}
+{"version":3,"file":"contextProvider.test.d.ts","sourceRoot":"","sources":["../contextProvider.test.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,OAAO,MAAM,oBAAoB,CAAA;AAC7C,OAAO,KAAK,MAAM,MAAM,mBAAmB,CAAA;AAC3C,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAY,WAAW,EAAE,MAAM,eAAe,CAAA;AAkFzE,eAAO,MAAM,mBAAmB;;CAkB9B,CAAA;AACF,eAAO,MAAM,sBAAsB;;CAkBjC,CAAA"}

package/test/dist/controller.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.test.d.ts","sourceRoot":"","sources":["../controller.test.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAc,MAAM,+BAA+B,CAAA;AAE7F,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAChE,OAAO,EAAoC,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAEvF,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAA;AAGtC,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAG3D,OAAO,EAAE,cAAc,EAAsB,YAAY,EAAqB,YAAY,EAAoB,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAY,MAAM,eAAe,CAAA;;cAuE/G,QAAQ;;AADzE,cAAM,kBACJ,SAAQ,uBAA0F;IAElG,MAAM,CAAC,OAAO,uDAUZ;CACH;;AAID,cAAM,GAAI,SAAQ,QAAuC;CAAG;;;;;AAE5D,qBAAa,eAAgB,SAAQ,oBAA4D;IAC/F,MAAM,CAAC,OAAO,2CAUZ;CACH;AAkFD,eAAO,MAAM,WAAW;;;;;;;;;;YAKM,CAAA;AAE9B,eAAO,MAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAqC,CAAA;;;;;;;;;;;;;;;;;;;;AAEtE,qBAAa,GAAI,SAAQ,QAA0C;CAAG;;;;;;;;;;;;;;;;AACtE,qBAAa,GAAI,SAAQ,QAAqB;CAAG;;;;;;;;;;;;;;;;;;;;;;;;AAIjD,qBAAa,WAAY,SAAQ,gBAEV;CAAG;;;;;;;;;;;;;;;;;;;;;;;;AAgB1B,qBAAa,YAAa,SAAQ,iBAET;CAAG;;;;;;;;;;;;;;;;;;;;;;;;AAE5B,qBAAa,aAAc,SAAQ,kBAEA;CAAG;;;;;;;;AAOtC,qBAAa,gBAAiB,SAAQ,qBASrC;IACC,MAAM,CAAC,OAAO,8CAAgC;CAC/C;;;;;;;;AASD,qBAAa,aAAc,SAAQ,kBASlC;IACC,MAAM,CAAC,OAAO,2CAA8E;CAC7F;;;;;;;;AAED,qBAAa,iBAAkB,SAAQ,sBAOtC;IACC,MAAM,CAAC,OAAO,+CAAgC;CAC/C;AAED,eAAO,MAAQ,MAAM;;;;;SA/KX,CADL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgLkB,QAAQ;;0FAE9B,CAAA;AAED,eAAO,MAAM,EAAE;;;;;;;;;aAnLL,CADL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsLJ,CAAA"}
+{"version":3,"file":"controller.test.d.ts","sourceRoot":"","sources":["../controller.test.ts"],"names":[],"mappings":"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"}