saeeol 1.3.0 → 1.3.1

package/src/provider/model-cache.ts

@@ -1,5 +1,5 @@
-import { fetchSaeeolModels, type SaeeolModelsResult } from "@saeeol/gateway"
-import { TTLCache } from "@saeeol/boxes/ttl-cache"
+import { fetchSaeeolModels, type SaeeolModelsResult } from "@saeeol/gateway"
+import { TTLCache } from "@/boxes/ttl-cache"
 import { Config } from "../config/config"
 import { Auth } from "../auth"
 import * as Log from "@saeeol/core/util/log"

package/src/provider/provider-resolve.ts

@@ -188,7 +188,7 @@ export async function resolveSDK(model: Model, s: State, envs: Record<string, st
       void Bus.publish(ProviderInstallEvent.Started, {
         providerID: model.providerID,
         pkg: model.api.npm,
-      })
+      }).catch(() => {})
       try {
         const item = await Npm.add(model.api.npm)
         if (!item.entrypoint) throw new Error(`Package ${model.api.npm} has no import entrypoint`)
@@ -196,13 +196,13 @@ export async function resolveSDK(model: Model, s: State, envs: Record<string, st
         void Bus.publish(ProviderInstallEvent.Completed, {
           providerID: model.providerID,
           pkg: model.api.npm,
-        })
+        }).catch(() => {})
       } catch (installErr) {
         void Bus.publish(ProviderInstallEvent.Failed, {
           providerID: model.providerID,
           pkg: model.api.npm,
           error: installErr instanceof Error ? installErr.message : String(installErr),
-        })
+        }).catch(() => {})
         throw installErr
       }
     } else {

package/src/provider/transform-message.ts

@@ -1,4 +1,4 @@
-import { parse as parseDataUrl } from "@saeeol/boxes/dataurl"
+import { parse as parseDataUrl } from "@/boxes/dataurl"
 import type { ModelMessage } from "ai"
 import { mergeDeep, unique } from "remeda"
 import type * as Provider from "./provider"

package/src/server/routes/game.ts

@@ -0,0 +1,284 @@
+import { Hono } from "hono"
+import { z } from "zod"
+import { generateText } from "ai"
+import { createOpenAI } from "@ai-sdk/openai"
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible"
+import * as Log from "@saeeol/core/util/log"
+import { lazy } from "@/util/lazy"
+
+const log = Log.create({ service: "game-event" })
+
+// ── Request schemas ──────────────────────────────────────────────
+
+const GameContextSchema = z.object({
+  character: z.object({ id: z.string(), name: z.string() }).optional(),
+  stats: z.record(z.number()).optional(),
+  flags: z.record(z.any()).optional(),
+  items: z.record(z.number()).optional(),
+  route: z.string().optional(),
+  act: z.string().optional(),
+  choice_history: z.array(z.string()).optional(),
+  bosses_defeated: z.array(z.string()).optional(),
+})
+
+const EventSchema = z.object({
+  id: z.string().optional(),
+  lines: z.array(z.object({ speaker: z.string(), text: z.string() }).passthrough()).optional(),
+  choices: z.array(z.any()).optional(),
+  nextSceneId: z.string().optional(),
+}).passthrough()
+
+const BaseRequestSchema = z.object({
+  action: z.enum(["augment", "generate", "reaction"]),
+  context: GameContextSchema.optional(),
+})
+
+const AugmentRequestSchema = BaseRequestSchema.extend({
+  action: z.literal("augment"),
+  event: EventSchema,
+})
+
+const GenerateRequestSchema = BaseRequestSchema.extend({
+  action: z.literal("generate"),
+  event_id: z.string(),
+  prompt_hint: z.record(z.any()).optional(),
+})
+
+const ReactionRequestSchema = BaseRequestSchema.extend({
+  action: z.literal("reaction"),
+  choice_text: z.string(),
+  event: EventSchema,
+})
+
+const RequestSchema = z.discriminatedUnion("action", [
+  AugmentRequestSchema,
+  GenerateRequestSchema,
+  ReactionRequestSchema,
+])
+
+// ── Prompt builders ──────────────────────────────────────────────
+
+function buildSystemPrompt(hint: Record<string, any> = {}): string {
+  const tone = hint.tone ?? "몰입감 있고 생생한 묘사"
+  const themes = (hint.themes ?? []).join(", ")
+  const escalation = hint.escalation ?? ""
+
+  return `너는 에로틱 판타지 던전 크롤러 게임의 AI 내레이터다.
+
+## 역할
+- 플레이어의 행동과 상황에 맞는 생생한 묘사를 생성한다
+- 캐릭터의 성격과 현재 상태(HP, 음란도, 개발도, 소지 아이템, 플래그)를 반영한다
+- 항상 한국어로 응답한다
+
+## 분위기
+- 톤: ${tone}
+- 테마: ${themes}
+${escalation ? `- 에스컬레이션: ${escalation}` : ""}
+
+## 응답 형식
+항상 다음 JSON 스키마로 응답한다. 다른 텍스트는 절대 포함하지 않는다:
+{
+  "lines": [
+    { "speaker": "나레이션", "text": "묘사 텍스트", "ai": true }
+  ]
+}
+
+## 규칙
+- lines는 1~3개
+- 각 line의 text는 1~3문장
+- 캐릭터 이름은 context에서 가져와서 자연스럽게 사용
+- 현재 루트와 act의 분위기를 반영
+- 플래그가 있으면 이전 경험을 참조
+- 절대 JSON 이외의 텍스트를 출력하지 않는다`
+}
+
+function buildAugmentPrompt(event: any, context: any): string {
+  const charName = context?.character?.name ?? "모험자"
+  const charId = context?.character?.id ?? ""
+  const route = context?.route ?? ""
+  const flags = context?.flags ?? {}
+  const stats = context?.stats ?? {}
+  const originalLines = (event?.lines ?? []).map((l: any) => `${l.speaker}: ${l.text}`).join("\n")
+
+  return `이 이벤트에 분위기를 더하는 AI 묘사를 생성하라.
+
+## 현재 상태
+- 캐릭터: ${charName} (${charId})
+- 루트: ${route}
+- HP: ${stats.hp ?? "?"}, 음란도: ${stats.lewdness ?? "?"}, 개발도: ${stats.corruption ?? "?"}
+- 플래그: ${JSON.stringify(flags)}
+
+## 원본 이벤트 대사
+${originalLines}
+
+## 요청
+원본 대사 앞에 들어갈 1~2줄의 분위기 묘사를 생성하라. 캐릭터의 현재 상태와 플래그를 반영하라.`
+}
+
+function buildGeneratePrompt(eventId: string, context: any, hint: Record<string, any> = {}): string {
+  const charName = context?.character?.name ?? "모험자"
+  const route = context?.route ?? ""
+  const act = context?.act ?? ""
+  const stats = context?.stats ?? {}
+  const flags = context?.flags ?? {}
+  const items = context?.items ?? {}
+  const charHints = hint.character_hints ?? {}
+  const charId = context?.character?.id ?? ""
+  const charHint = charHints[charId] ?? ""
+
+  return `완전히 새로운 게임 이벤트를 생성하라.
+
+## 이벤트 ID: ${eventId}
+## Act: ${act}, Route: ${route}
+
+## 캐릭터
+- 이름: ${charName} (${charId})
+- 성향: ${charHint}
+- HP: ${stats.hp ?? "?"}, 음란도: ${stats.lewdness ?? "?"}, 개발도: ${stats.corruption ?? "?"}
+
+## 소지품
+${JSON.stringify(items)}
+
+## 경험한 일들 (플래그)
+${JSON.stringify(flags)}
+
+## 요청
+다음 JSON 스키마로 완전한 이벤트를 생성하라:
+{
+  "id": "${eventId}",
+  "act": "${act}",
+  "lines": [
+    { "speaker": "나레이션", "text": "...", "ai": true }
+  ],
+  "choices": [
+    { "text": "선택지 텍스트", "nextSceneId": "다음_이벤트_ID", "conditions": [], "effects": [] }
+  ],
+  "nextSceneId": "기본_다음_이벤트_ID"
+}
+
+2~4줄의 대사와 2~3개의 선택지를 만들어라.`
+}
+
+function buildReactionPrompt(choiceText: string, event: any, context: any): string {
+  const charName = context?.character?.name ?? "모험자"
+  const stats = context?.stats ?? {}
+
+  return `플레이어가 선택을 한 직후의 반응 묘사를 생성하라.
+
+## 선택한 것: "${choiceText}"
+## 캐릭터: ${charName}
+- HP: ${stats.hp ?? "?"}, 음란도: ${stats.lewdness ?? "?"}
+
+## 요청
+선택 직후의 짧은 반응 묘사 1~2줄을 생성하라. 캐릭터의 감정과 상황 변화를 반영하라.
+
+JSON 형식:
+{
+  "lines": [
+    { "speaker": "나레이션", "text": "...", "ai": true }
+  ]
+}`
+}
+
+// ── LLM call ─────────────────────────────────────────────────────
+
+function createProvider() {
+  // Use OPENAI_API_KEY or OPENAI_BASE_URL from env
+  const apiKey = process.env.OPENAI_API_KEY ?? process.env.ANTHROPIC_API_KEY ?? ""
+  const baseURL = process.env.OPENAI_BASE_URL
+
+  if (baseURL) {
+    return createOpenAICompatible({ name: "custom", baseURL, apiKey })
+  }
+
+  return createOpenAI({ apiKey })
+}
+
+async function callLLM(systemPrompt: string, userPrompt: string): Promise<any> {
+  const provider = createProvider()
+  const modelId = process.env.GAME_LLM_MODEL ?? "gpt-4o-mini"
+  const model = provider(modelId)
+
+  const result = await generateText({
+    model,
+    system: systemPrompt,
+    prompt: userPrompt,
+    maxTokens: 1024,
+    temperature: 0.8,
+  })
+
+  // Extract JSON from response (handle markdown code blocks)
+  let text = result.text.trim()
+  const jsonMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/)
+  if (jsonMatch) {
+    text = jsonMatch[1].trim()
+  }
+
+  return JSON.parse(text)
+}
+
+// ── Routes ───────────────────────────────────────────────────────
+
+export const GameEventRoutes = lazy(() =>
+  new Hono()
+    .post(
+      "/event",
+      async (c) => {
+        const body = await c.req.json()
+        const parsed = RequestSchema.safeParse(body)
+
+        if (!parsed.success) {
+          return c.json({ error: "Invalid request", details: parsed.error.flatten() }, 400)
+        }
+
+        const req = parsed.data
+        const context = req.context ?? {}
+
+        try {
+          switch (req.action) {
+            case "augment": {
+              const hint: Record<string, any> = {}
+              const systemPrompt = buildSystemPrompt(hint)
+              const userPrompt = buildAugmentPrompt(req.event, context)
+
+              const result = await callLLM(systemPrompt, userPrompt)
+
+              // Merge AI lines into original event
+              const aiLines: any[] = result.lines ?? []
+              const originalLines: any[] = req.event?.lines ?? []
+              const merged = {
+                ...req.event,
+                lines: [...aiLines, ...originalLines],
+              }
+
+              log.info("augment event", { id: req.event?.id, aiLines: aiLines.length })
+              return c.json(merged)
+            }
+
+            case "generate": {
+              const hint = req.prompt_hint ?? {}
+              const systemPrompt = buildSystemPrompt(hint)
+              const userPrompt = buildGeneratePrompt(req.event_id, context, hint)
+
+              const result = await callLLM(systemPrompt, userPrompt)
+              log.info("generate event", { id: req.event_id })
+              return c.json(result)
+            }
+
+            case "reaction": {
+              const hint: Record<string, any> = {}
+              const systemPrompt = buildSystemPrompt(hint)
+              const userPrompt = buildReactionPrompt(req.choice_text, req.event, context)
+
+              const result = await callLLM(systemPrompt, userPrompt)
+              log.info("reaction", { choice: req.choice_text })
+              return c.json(result)
+            }
+          }
+        } catch (err: any) {
+          log.error("game event failed", { error: err.message })
+          return c.json({ error: err.message }, 500)
+        }
+      },
+    ),
+)

package/src/server/server.ts

@@ -13,6 +13,7 @@ import { InstanceRoutes } from "./routes/instance"
 import { ControlPlaneRoutes } from "./routes/control"
 import { UIRoutes } from "./routes/ui"
 import { GlobalRoutes } from "./routes/global"
+import { GameEventRoutes } from "./routes/game"
 import { WorkspaceRouterMiddleware } from "./workspace"
 import { InstanceMiddleware } from "./routes/instance/middleware"
 import { WorkspaceRoutes } from "./routes/control/workspace"
@@ -106,6 +107,7 @@ function createHono(opts: CorsOptions, selection: ServerBackend.Selection = Serv
     .use(CompressionMiddleware)
     .use(CorsMiddleware(opts))
     .route("/global", GlobalRoutes())
+    .route("/api", GameEventRoutes())
 
   const runtime = adapter.create(app)
 

package/src/session/core/compaction/compaction-helpers.ts

@@ -1,4 +1,4 @@
-import { clamp } from "@saeeol/boxes/clamp"
+import { clamp } from "@/boxes/clamp"
 import { BusEvent } from "@/bus/bus-event"
 import { SessionID, MessageID } from "../schema"
 import { Provider } from "@/provider/provider"

package/src/session/core/compaction/compaction.ts

@@ -1,4 +1,4 @@
-import { clamp } from "@saeeol/boxes/clamp"
+import { clamp } from "@/boxes/clamp"
 import { BusEvent } from "@/bus/bus-event"
 import { Bus } from "@/bus"
 import * as Session from "../session"

package/src/session/core/session.ts

@@ -317,7 +317,9 @@ export const getUsage = (input: {
         input.metadata?.["anthropic"]?.["cacheCreationInputTokens"] ??
         // google-vertex-anthropic returns metadata under "vertex" key
         input.metadata?.["vertex"]?.["cacheCreationInputTokens"] ??
+        // @ts-expect-error
         input.metadata?.["bedrock"]?.["usage"]?.["cacheWriteInputTokens"] ??
+        // @ts-expect-error
         input.metadata?.["venice"]?.["usage"]?.["cacheCreationInputTokens"] ??
         0,
     ),

package/src/sessions/ingest-queue.ts

@@ -1,7 +1,7 @@
-import { ulid } from "ulid"
+import { ulid } from "ulid"
 import type * as SDK from "@saeeol/sdk/v2"
 import type { SaeeolSession } from "@/saeeol/session"
-import { expDelay } from "@saeeol/boxes/schedule"
+import { expDelay } from "@/boxes/schedule"
 
 export namespace IngestQueue {
   export type Client = {

package/src/sessions/remote-ws.ts

@@ -1,4 +1,4 @@
-import { random as randomId } from "@saeeol/boxes/uid"
+import { random as randomId } from "@/boxes/uid"
 import { RemoteProtocol } from "@/sessions/remote-protocol"
 
 export namespace RemoteWS {

package/src/tool/workflow/question.ts

@@ -1,5 +1,5 @@
 import { Effect, Schema } from "effect"
-import { plural } from "@saeeol/boxes/plural"
+import { plural } from "@/boxes/plural"
 import * as Tool from "../core/tool"
 import { Question } from "../../question"
 import DESCRIPTION from "./question.txt"

package/src/util/abort.ts

@@ -1 +1 @@
-export { cancelAfter as abortAfter, cancelAny as abortAfterAny } from "@saeeol/boxes/cancel"
+export { cancelAfter as abortAfter, cancelAny as abortAfterAny } from "@/boxes/cancel"

package/src/util/bom.ts

@@ -1,7 +1,7 @@
-export { split, join } from "@saeeol/boxes/bom"
+export { split, join } from "@/boxes/bom"
 import { Effect } from "effect"
 import { AppFileSystem } from "@saeeol/core/filesystem"
-import { split, join } from "@saeeol/boxes/bom"
+import { split, join } from "@/boxes/bom"
 
 export const readFile = Effect.fn("Bom.readFile")(function* (fs: AppFileSystem.Interface, filePath: string) {
   return split(new TextDecoder("utf-8", { ignoreBOM: true }).decode(yield* fs.readFile(filePath)))

package/src/util/color.ts

@@ -1,3 +1,3 @@
-export { valid as isValidHex, rgb as hexToRgb, bold as hexToAnsiBold } from "@saeeol/boxes/ansi"
+export { valid as isValidHex, rgb as hexToRgb, bold as hexToAnsiBold } from "@/boxes/ansi"
 
 export * as Color from "./color"

package/src/util/data-url.ts

@@ -1 +1 @@
-export { decode as decodeDataUrl } from "@saeeol/boxes/dataurl"
+export { decode as decodeDataUrl } from "@/boxes/dataurl"

package/src/util/defer.ts

@@ -1 +1 @@
-export { disposable as defer } from "@saeeol/boxes/disposable"
+export { disposable as defer } from "@/boxes/disposable"

package/src/util/error.ts

@@ -1,5 +1,5 @@
-export { msg as errorMessage, fmt as errorFormat } from "@saeeol/boxes/err"
-import { msg as errorMessage, fmt as errorFormat } from "@saeeol/boxes/err"
+export { msg as errorMessage, fmt as errorFormat } from "@/boxes/err"
+import { msg as errorMessage, fmt as errorFormat } from "@/boxes/err"
 import { isRecord } from "./record"
 
 export function errorData(error: unknown) {

package/src/util/filesystem.ts

@@ -1,5 +1,5 @@
-import { chmod, mkdir, readFile, stat as statFile, writeFile } from "fs/promises" 
-import { atomicWrite } from "@saeeol/boxes/atomic-write"
+import { chmod, mkdir, readFile, stat as statFile, writeFile } from "fs/promises" 
+import { atomicWrite } from "@/boxes/atomic-write"
 import { createWriteStream, existsSync, statSync } from "fs"
 import { realpathSync } from "fs"
 import { dirname, isAbsolute, join, relative, resolve as pathResolve, sep, win32 } from "path"

package/src/util/format.ts

@@ -1 +1 @@
-export { secsDuration as formatDuration } from "@saeeol/boxes/human"
+export { secsDuration as formatDuration } from "@/boxes/human"

package/src/util/iife.ts

@@ -1 +1 @@
-export { iife } from "@saeeol/boxes/iife"
+export { iife } from "@/boxes/iife"

package/src/util/local-context.ts

@@ -1,3 +1,3 @@
-export { scope as create, NotFound } from "@saeeol/boxes/scope"
+export { scope as create, NotFound } from "@/boxes/scope"
 
 export * as LocalContext from "./local-context"

package/src/util/locale.ts

@@ -1,5 +1,5 @@
-import { time, datetime } from "@saeeol/boxes/human"
-export { title as titlecase, time, datetime, compact as number, duration, truncate, truncateMid as truncateMiddle, plural as pluralize } from "@saeeol/boxes/human"
+import { time, datetime } from "@/boxes/human"
+export { title as titlecase, time, datetime, compact as number, duration, truncate, truncateMid as truncateMiddle, plural as pluralize } from "@/boxes/human"
 
 export function todayTimeOrDateTime(input: number): string {
   const date = new Date(input)

package/src/util/lock.ts

@@ -1,3 +1,3 @@
-export { read, write } from "@saeeol/boxes/rwlock"
+export { read, write } from "@/boxes/rwlock"
 
 export * as Lock from "./lock"

package/src/util/network.ts

@@ -1 +1 @@
-export { online, proxied } from "@saeeol/boxes/net"
+export { online, proxied } from "@/boxes/net"

package/src/util/signal.ts

@@ -1,4 +1,4 @@
-import { latch } from "@saeeol/boxes/latch"
+import { latch } from "@/boxes/latch"
 
 /** One-shot signal (latch wrapper matching original trigger/wait API) */
 export function signal() {

package/src/util/token.ts

@@ -1,3 +1,3 @@
-export { count as estimate } from "@saeeol/boxes/tokens"
+export { count as estimate } from "@/boxes/tokens"
 
 export * as Token from "./token"

package/src/util/wildcard.ts

@@ -1,4 +1,4 @@
-import { globMatch, globBest, globStructured } from "@saeeol/boxes/wildcard"
+import { globMatch, globBest, globStructured } from "@/boxes/wildcard"
 
 const ci = process.platform === "win32"
 

package/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/test/AGENTS.md

@@ -0,0 +1,133 @@
+# Test Fixtures Guide
+
+## Temporary Directory Fixture
+
+The `tmpdir` function in `fixture/fixture.ts` creates temporary directories for tests with automatic cleanup.
+
+### Basic Usage
+
+```typescript
+import { tmpdir } from "./fixture/fixture"
+
+test("example", async () => {
+  await using tmp = await tmpdir()
+  // tmp.path is the temp directory path
+  // automatically cleaned up when test ends
+})
+```
+
+### Options
+
+- `git?: boolean` - Initialize a git repo with a root commit
+- `config?: Partial<Config.Info>` - Write an `saeeol.json` config file
+- `init?: (dir: string) => Promise<T>` - Custom setup function, returns value accessible as `tmp.extra`
+- `dispose?: (dir: string) => Promise<T>` - Custom cleanup function
+
+### Examples
+
+**Git repository:**
+
+```typescript
+await using tmp = await tmpdir({ git: true })
+```
+
+**With config file:**
+
+```typescript
+await using tmp = await tmpdir({
+  config: { model: "test/model", username: "testuser" },
+})
+```
+
+**Custom initialization (returns extra data):**
+
+```typescript
+await using tmp = await tmpdir<string>({
+  init: async (dir) => {
+    await Bun.write(path.join(dir, "file.txt"), "content")
+    return "extra data"
+  },
+})
+// Access extra data via tmp.extra
+console.log(tmp.extra) // "extra data"
+```
+
+**With cleanup:**
+
+```typescript
+await using tmp = await tmpdir({
+  init: async (dir) => {
+    const specialDir = path.join(dir, "special")
+    await fs.mkdir(specialDir)
+    return specialDir
+  },
+  dispose: async (dir) => {
+    // Custom cleanup logic
+    await fs.rm(path.join(dir, "special"), { recursive: true })
+  },
+})
+```
+
+### Returned Object
+
+- `path: string` - Absolute path to the temp directory (realpath resolved)
+- `extra: T` - Value returned by the `init` function
+- `[Symbol.asyncDispose]` - Enables automatic cleanup via `await using`
+
+### Notes
+
+- Directories are created in the system temp folder with prefix `saeeol-test-`
+- Use `await using` for automatic cleanup when the variable goes out of scope
+- Paths are sanitized to strip null bytes (defensive fix for CI environments)
+
+## Testing With Effects
+
+Use `testEffect(...)` from `test/lib/effect.ts` for tests that exercise Effect services or Effect-based workflows.
+
+### Core Pattern
+
+```typescript
+import { describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { provideTmpdirInstance } from "../fixture/fixture"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(Layer.mergeAll(MyService.defaultLayer))
+
+describe("my service", () => {
+  it.live("does the thing", () =>
+    provideTmpdirInstance(() =>
+      Effect.gen(function* () {
+        const svc = yield* MyService.Service
+        const out = yield* svc.run()
+        expect(out).toEqual("ok")
+      }),
+    ),
+  )
+})
+```
+
+### `it.effect` vs `it.live`
+
+- Use `it.effect(...)` when the test should run with `TestClock` and `TestConsole`.
+- Use `it.live(...)` when the test depends on real time, filesystem mtimes, child processes, git, locks, or other live OS behavior.
+- Most integration-style tests in this package use `it.live(...)`.
+
+### Effect Fixtures
+
+Prefer the Effect-aware helpers from `fixture/fixture.ts` instead of building a manual runtime in each test.
+
+- `tmpdirScoped(options?)` creates a scoped temp directory and cleans it up when the Effect scope closes.
+- `provideInstance(dir)(effect)` is the low-level helper. It does not create a directory; it just runs an Effect with `Instance.current` bound to `dir`.
+- `provideTmpdirInstance((dir) => effect, options?)` is the convenience helper. It creates a temp directory, binds it as the active instance, and disposes the instance on cleanup.
+- `provideTmpdirServer((input) => effect, options?)` does the same, but also provides the test LLM server.
+
+Use `provideTmpdirInstance(...)` by default when a test only needs one temp instance. Use `tmpdirScoped()` plus `provideInstance(...)` when a test needs multiple directories, custom setup before binding, or needs to switch instance context within one test.
+
+### Style
+
+- Define `const it = testEffect(...)` near the top of the file.
+- Keep the test body inside `Effect.gen(function* () { ... })`.
+- Yield services directly with `yield* MyService.Service` or `yield* MyTool`.
+- Avoid custom `ManagedRuntime`, `attach(...)`, or ad hoc `run(...)` wrappers when `testEffect(...)` already provides the runtime.
+- When a test needs instance-local state, prefer `provideTmpdirInstance(...)` or `provideInstance(...)` over manual `Instance.provide(...)` inside Promise-style tests.